Adam-Palacz/spaceops_mission_agent_lab
GitHub: Adam-Palacz/spaceops_mission_agent_lab
基于 LangGraph 和 OPA 策略引擎的航天任务异常分类 Agent，实现卫星与地面段事件的自动化分诊、调查、决策与报告全流程。
Stars: 0 | Forks: 0
# SpaceOps Mission Agent 实验室
用于卫星/地面段异常分类的 Agent：**摄取 ? 分类 ? 调查 ? 决策 ? 报告**。自动操作清单，用于配置 (S2) 的 GitOps PR，以及操作报告。运行在模拟数据（遥测、事件、日志）之上；架构为生产级别。
## 文档
| 文档 | 描述 |
|-----|-------------|
| [**roadmap/goals.md**](./roadmap/goals.md) | 目标、假设、需求 (F1–F10, NF1–NF9)、策略、MoE/MoP、生产就绪标准、审计日志 schema (§4.6)。 |
| [**roadmap/base-roadmap.md**](./roadmap/base-roadmap.md) | Sprint (S1, S2, S3)，第 4 阶段强化，技术债 Sprint，任务列表。 |
| [**roadmap/01-foundation-mvp.md**](./roadmap/01-foundation-mvp.md) | 基础/MVP 故事线：核心 Agent、MCP、评估和升级。 |
| [**roadmap/02-production-scale.md**](./roadmap/02-production-scale.md) | 后 MVP 生产化：流处理、安全门禁、LLM 后端、K8s/云。 |
| [**roadmap/post-mvp.md**](./roadmap/post-mvp.md) | 长期路线图：阶段、想法和生产级标准。 |
| [**roadmap/03-next-gen-autonomy.md**](./roadmap/03-next-gen-autonomy.md) | 下一代自主 (L3/L4)：飞行指挥官多 Agent 模式、协作规划、合规网关、边缘 SLM、GraphRAG。 |
| [**roadmap/README.md**](./roadmap/README.md) | 执行计划：阶段、Sprint、任务规范。 |
| [**docs/README.md**](./docs/README.md) | Mermaid 图表索引（Pipeline、架构、状态流、Act 流、仓库结构）。 |
| [**docs/process.md**](./docs/process.md) | 流程文档，包括技术债预算 (S3.8) 以及如何在 Sprint 中应用它。 |
| [**docs/shadow_models.md**](./docs/shadow_models.md) | 模型晋升：影子测试、报告布局、决策规则 (P4.8)。 |
| [**roadmap/01-core/README.md**](./roadmap/01-core/README.md) | Sprint 看板和任务规范 (S1.x, S2.x, S3.x)。 |
## 环境
- 将 **.env.example** 复制到 **.env** 并设置 LLM 提供商凭证：
- `LLM_PROVIDER=openai` + `OPENAI_API_KEY`，或
- `LLM_PROVIDER=cursor_sh` + `CURSOR_SH_API_KEY`。
可选的提供商端点设置：`OPENAI_BASE_URL`、`CURSOR_SH_BASE_URL`、`LLM_CHAT_COMPLETIONS_PATH`。
如果不使用默认值，可选设置：`POSTGRES_*`。
- **限制与超时 (S1.12, NF6)：** `AGENT_RUN_TIMEOUT_SECONDS` (默认 120；0 = 无限制)、`AGENT_LLM_CALL_TIMEOUT_SECONDS` (默认 30)、`AGENT_TOKEN_BUDGET_PER_RUN` (默认 50000；0 = 无限制)、`AGENT_MAX_LLM_CALLS_PER_RUN` (默认 10；0 = 无限制)。当超过限制时，运行将升级给人工处理。
- **OTel 链路追踪 (S1.10)：** 要将应用程序的追踪导出到本地 collector/Jaeger，请设置 `OTEL_EXPORTER_OTLP_ENDPOINT` (例如 `http://localhost:4317`，需与 `infra/docker-compose.yml` 匹配)。
- **MCP + GitOps (S2)：** MCP URL 可以通过 `TELEMETRY_MCP_URL`、`KB_MCP_URL`、`TICKET_MCP_URL`、`GITOPS_MCP_URL` 进行覆盖 (参见 `.env.example`)。要创建 GitOps PR，请设置 `GITHUB_TOKEN`、`GITHUB_REPO`、`GITHUB_REPO_BASE_BRANCH`。
- **OPA 策略 (S2.4)：** OPA 端点和超时可通过 `OPA_URL` 和 `OPA_TIMEOUT_SECONDS` 配置；默认情况下，OPA 作为 `opa` 服务在 `infra/docker-compose.yml` 中运行。**审批请求 (S2.5)：** 仅当 Agent 运行产生**受限**步骤 (带有 `safe=false` 的计划，例如 `change_config` / `restart_service`) 并且 **OPA 正在运行并允许**该步骤时，才会填充 `data/approvals/`。如果 OPA 宕机或拒绝 → 不会创建任何文件 (失败闭环)；为审批 API 设置 `APPROVAL_API_KEY`。要在没有完整运行的情况下测试审批 API，请植入一个请求：`python scripts/seed_approval_request.py` (然后使用返回的 id 调用 GET /approvals 和 POST …/approve 或 …/reject)。
- 不要提交 `.env` (在 `.gitignore` 中)。所有应用程序都通过 `config.settings` 从仓库根目录加载它。
## 快速开始
```
# 依赖项 (Python 3.12)
pip install -r requirements.txt
# Stack (Postgres+pgvector, OTel, Jaeger, Prometheus, Grafana)
docker compose -f infra/docker-compose.yml --project-directory . up -d
# API
python -m apps.api.main
# ? http://localhost:8000 | GET /health | GET /metrics | POST /ingest | POST /runs
# Prometheus: http://localhost:9090 | Grafana: http://localhost:3000 (admin/admin)
```
**摄取 fixture：**
`curl -X POST "http://localhost:8000/ingest?source=telemetry" -H "Content-Type: application/x-ndjson" --data-binary @data/telemetry/telemetry.ndjson`
**运行 Agent：**
带有请求体 `{"incident_id": "inc-1", "payload": {"time_range_start": "2025-02-14T09:00:00Z", "time_range_end": "2025-02-14T11:00:00Z"}}` 的 `POST /runs` ? 返回报告。或者使用 CLI：
`python -m apps.agent.run inc-1 '{"time_range_start":"2025-02-14T09:00:00Z","time_range_end":"2025-02-14T11:00:00Z"}'`
**可选（更丰富的调查）：** 运行 MCP 遥测 (端口 8001) 和 MCP KB (8002)；索引 KB：`python -m apps.mcp.kb_server.index_kb`。参见 [apps/agent/README.md](apps/agent/README.md)，[apps/mcp/](apps/mcp/)。
**GitOps / ops-config (S2)：** 来自 Agent 的配置 PR 的目标是位于仓库根目录的 [ops-config/](ops-config/) 子树。默认分支：`main`；MCP 的路径：`ops-config/` (本地) 或者如果拆分后的独立仓库 URL。参见 [ops-config/README.md](ops-config/README.md)。要在本地演练 GitOps PR 流程，请运行 GitOps MCP server (`python -m apps.mcp.gitops_server.main`) 并使用 `scripts/test_gitops_pr.py` (需要 `GITHUB_TOKEN` / `GITHUB_REPO`)。
## 测试
```
pytest tests/ -v
```
## 格式化
```
# 将标准格式应用于 Python 模块 (ruff format)
python -m ruff format .
```
**评估 (S1.11)：** `python -m evals.scoring` (需要已配置的 LLM 提供商凭证)。参见 [evals/README.md](evals/README.md)。**影子模型 (P4.8)：** 设置 `AGENT_CANDIDATE_MODEL_IDS` 后运行 `python -m evals.shadow_models` —— 参见 [docs/shadow_models.md](docs/shadow_models.md)；CI 工作流 `shadow-models.yml` (按需/计划运行)，不会在每个 PR 上运行。
**Pre-commit：** 使用 `pip install pre-commit && pre-commit install` 安装钩子。手动运行：`pre-commit run --all-files` (ruff, ruff-format, mypy)。CI 在推送/PR 时运行 ruff、mypy、pytest 和评估 (S1.13)。
## 代码风格 (Agent，MCP，评估)
- 控制流尽量每行编写一条语句 (不要将包含多个 `if`/`and`/`or` 分支的语句压缩在一行中)。
- 为中间值命名以阐明意图 (例如 `allowed_subsystems`、`telemetry_outcome`)，而不是使用深度嵌套的表达式。
- 首先保持评估和 Agent 逻辑的可读性；微观优化次于清晰度，尤其是在升级、限制和审计日志方面。
标签：Agent, CISA项目, CSV导出, GitOps, GraphRAG, LangGraph, MCP, OPA, 事件分类, 任务规划, 卫星通信, 地面站系统, 多智能体, 子域名突变, 安全策略, 异常分类, 影子模型, 提示词注入, 提示词设计, 操作报告, 测试用例, 状态机, 用户代理, 自动化响应, 自动化运维, 自定义请求头, 航天运维, 航天领域, 评估系统, 请求拦截, 边缘计算, 逆向工具, 遥测数据处理, 靶场