Lumis SDK

面向数据、ML 和软件 pipeline 的确定性优先、基于证据的故障恢复方案。

CI · Apache-2.0 · 架构 · 配置 · 实用指南 · 路线图

Lumis SDK 是一个开源的 Python 实现，作为伴随研究中所提出的**智能体恢复与事件响应**参考架构的配套工具。它提供了可重用的契约和本地参考 adapter，用于诊断数据、机器学习和软件交付 pipeline 中的故障，同时保持模型为可选组件，并确保后果性操作（consequential actions）受到明确控制。 Lumis SDK 从“诊断即代码”（Diagnosis-as-Code）开始：将本地事件证据转化为结构化、可审查的诊断、Markdown 报告和操作记忆记录。其发展方向是“修复即代码”（Healing-as-Code）：涵盖检测、分流、诊断、规划、审批、修复、验证和学习的安全守护生命周期。 ## 研究与实现边界 | 产物 | 角色 | 仓库边界 | | --- | --- | --- | | **参考架构** | 智能体恢复与事件响应生命周期。 | 论文描述的技术灵活性设计。 | | **Lumis SDK** | Apache-2.0 框架和本地实现配套工具。 | 领域契约、应用服务、port、安全的参考 adapter、CLI、testkit 和实用指南。 | ## 设计原则 - **确定性优先。** 已知的特征签名和项目规则先于可选的模型推理运行。 - **基于证据。** 事实、证据、假设、置信度、矛盾和缺失的证据始终保持可区分。 - **模型可选。** 核心功能可在离线环境下工作；提供商集成实现了轻量级的 gateway port。 - **本地优先。** SQLite 和 Markdown 是可检查的默认选项，而非强制性的托管服务。 - **受保护的恢复。** 方案是加入白名单的建议；审批和验证具有明确的边界。 - **经过确认的记忆。** 模型输出绝不会被悄悄提升为已确认的操作真相。 - **厂商无关。** 领域和应用包不导入任何可观测性、编排、云或 agent SDK。 ## 架构 ``` flowchart LR subgraph USERS[Project entry points] CLI[Lumis SDK CLI] PY[Python application] end subgraph CORE[Lumis SDK framework] CFG[Strict project and rule configuration] APP[Application services] DOMAIN[Domain contracts] PORTS[Optional provider ports] end subgraph LOCAL[Local reference adapters] DET[Deterministic diagnosis] MEM[SQLite incident memory] REPORT[Markdown reports] REDACT[Evidence redaction] end CLI --> CFG CLI --> DET CLI --> MEM CLI --> REPORT PY --> APP APP --> DOMAIN APP --> PORTS APP --> DET CFG --> DET REDACT --> PORTS ``` 规范的包边界： ``` src/lumis_sdk/ ├── domain/ # strict vendor-neutral models ├── application/ # use-case orchestration ├── ports/ # replaceable provider interfaces ├── adapters/ # deterministic, SQLite, Markdown, and local adapters ├── config/ # versioned strict configuration ├── cli/ # command composition ├── security/ # redaction and evidence-safety utilities └── testkit/ # deterministic test doubles ``` 概念验证阶段的扁平化模块已被移除。新代码将导入上述显式的领域、应用、port、adapter、配置和安全包。 阅读[架构概述](docs/architecture/overview.md)、[SDK 参考](docs/LUMIS_SDK_REFERENCE.md)和[配置参考](docs/configuration.md)。 [结构化规则 API 指南](docs/python-api/structured-rules.md)涵盖了复合事件 字段、证据、fixture 测试以及从 `all_contains` 的迁移。 ## 当前功能 | 功能 | 当前行为 | | --- | --- | | 事件输入 | 本地日志归一化和类型化的厂商中立事件契约。 | | 确定性诊断 | 传统的有序文本规则，以及具有类型化比较、所需证据、排序和候选解释的结构化 `all`/`any`/`not` 规则。 | | 版本化配置 | 严格的 `lumis.dev/v1alpha1` 项目和规则集文档；未知字段会导致验证失败。 | | 报告 | 确定性的 Markdown，包含事实、证据、假设、置信度、审查要求和安全边界。 | | 本地记忆 | SQLite 记录、人工干预结果、可见的真实状态以及透明的词汇搜索。 | | 模型边界 | 显式的策略、预算、经过 schema 验证的输出、伪 CI gateway 以及确定性回退机制。 | | 受保护的生命周期 | 上下文、策略、审批、验证和审计 port，且核心不包含任何操作执行器。 | | CLI | 初始化、诊断、doctor、规则验证、报告、干预结果处理和记忆搜索。 | | 实用指南 | 包含可选 Agno/OpenRouter 路径的合成数据、ML 回归和软件交付调查。 | ## 快速开始 Lumis SDK 支持 Python 3.11+，并使用 [uv](https://docs.astral.sh/uv/)。 ``` git clone https://github.com/soloshun/lumis-sdk.git cd lumis-sdk uv sync --all-groups uv run lumis --help ``` ## 安装 Lumis SDK Lumis SDK 已发布到 PyPI，名为 `lumis-sdk`。使用 `uv` 将其添加到项目中： ``` uv add "lumis-sdk>=0.0.1,<0.1.0" ``` 或者使用 pip 将其安装到现有环境中： ``` pip install lumis-sdk ``` 为确保特定版本的可复现性，请锁定版本： ``` uv add "lumis-sdk==0.0.2" pip install "lumis-sdk==0.0.2" ``` 该仓库的 GitHub Actions 工作流通过 PyPI Trusted Publishing 发布经过审查的版本。 运行本地的确定性示例： ``` uv run lumis doctor \ --config cookbook/simple-log-diagnosis/lumis/lumis.yml uv run lumis diagnose \ --config cookbook/simple-log-diagnosis/lumis/lumis.yml ``` 该命令会读取合成的本地日志，生成 Markdown 报告，将未确认的事件记录（episode）保存到本地 SQLite 中，并打印其事件 ID。它不会发起任何网络或模型调用。 ``` uv run lumis report \ --config cookbook/simple-log-diagnosis/lumis/lumis.yml uv run lumis resolve \ --resolution "Human-confirmed cause, action, and outcome." \ --config cookbook/simple-log-diagnosis/lumis/lumis.yml uv run lumis memory search "KeyError Close" \ --config cookbook/simple-log-diagnosis/lumis/lumis.yml ``` ## 版本化的项目配置 ``` apiVersion: lumis.dev/v1alpha1 kind: Project metadata: name: customer-pipeline spec: environment: local memory: provider: sqlite path: .lumis/incidents.db reports: provider: markdown outputDir: .lumis/reports incidentSources: - provider: local-log path: logs/latest-failure.log rules: files: [rules.yml] model: enabled: false ``` 配置非常严格：拼写错误或未知字段会导致验证错误。相对路径会从项目文档开始解析。超过配置安全限制的文件将被拒绝。[项目](schemas/lumis-project-v1alpha1.schema.json)和[规则集](schemas/lumis-rules-v1alpha1.schema.json)的已检查 schema 支持编辑器和相关工具。 在此次预发布重构期间，Lumis SDK 有意仅接受版本化的项目和规则集结构。请阅读[配置参考](docs/configuration.md)以了解每个字段及其含义。 ## CLI ``` lumis init lumis doctor lumis diagnose lumis report lumis resolve lumis memory search lumis rules validate lumis rules test ``` `doctor` 和验证命令不会发起网络调用，也不会写入事件状态。除非应用程序代码同时提供已启用的策略和 gateway adapter，否则模型辅助功能将保持禁用状态。 ## Python API ``` import asyncio from pathlib import Path from lumis_sdk.application import DiagnosisService from lumis_sdk.config import load_config from lumis_sdk.domain import IncidentInput config = load_config(Path("lumis.yml")) service = DiagnosisService(rules=config.rules) incident = IncidentInput( source_tool="local-log", pipeline_name=config.project, raw_payload={"log": "ERROR KeyError: Close"}, ) diagnosis = asyncio.run(service.diagnose(incident)) ``` ## 实用指南 - [简单的本地诊断](cookbook/simple-log-diagnosis/README.md) - [数据 pipeline 调查](cookbook/data-pipeline-investigation/README.md) - [ML 回归监控](cookbook/ml-regression-monitoring/README.md) - [软件交付 CI 调查](cookbook/software-delivery-ci-investigation/README.md) - [结构化规则评估](cookbook/structured-rule-evaluation/README.md) - [记录人工干预结果](cookbook/recording-resolution/README.md) 请从实用指南开始查看可运行的演示，然后使用上方的架构和核心参考来检查其背后的框架契约。所有示例均为合成的、可执行的研究演示：它们展示了消费级应用程序如何使用 Lumis SDK，但并不声称自己是生产级的控制平面或自主修复系统。Agent 框架和模型提供商仍然是仅限于实用指南的可选依赖项。 ## 安全性 Lumis SDK 将日志、工单、runbook、源文件和模型输出视为不受信任的输入。 - 核心功能中不包含直接的 shell、云管理、Kubernetes 管理或数据库驱动（actuation）操作。 - CI 中不包含实时的模型密钥或计费请求。 - 默认情况下不导出遥测数据。 - 限制配置和日志读取范围。 - 在可选的模型使用前进行保守的脱敏处理。 - 在人类或验证器确认之前，模型输出始终是未确认的假设。 - 执行能力需要未来的 RFC、加入白名单的类型化操作、策略、审批、审计、限制和验证。 阅读[威胁模型](docs/safety/threat-model.md)和[安全策略](SECURITY.md)。 ## 开发 ``` uv sync --all-groups uv run ruff format --check . uv run ruff check . uv run mypy src uv run python scripts/generate_config_schema.py --check uv run pytest uv build ``` 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)、[GOVERNANCE.md](GOVERNANCE.md)、[SUPPORT.md](SUPPORT.md)、[CHANGELOG.md](CHANGELOG.md) 和 [ROADMAP.md](ROADMAP.md)。 ## 发布 Lumis SDK 的版本发布通过 GitHub Actions 手动调度，并使用 PyPI Trusted Publishing 进行发布。 ## 研究与标准背景 Lumis SDK 的设计受到了 [OpenTelemetry](https://opentelemetry.io/)、[OpenLineage](https://openlineage.io/)、[Prometheus](https://prometheus.io/)、[站点可靠性工程](https://sre.google/sre-book/table-of-contents/)、[ReAct](https://arxiv.org/abs/2210.03629) 以及 [基于 LLM 的事件根因分析（RCA）研究](https://doi.org/10.1145/3627703.3629553) 的影响。这些是设计上的参考，并非强制依赖项或合规性声明。 ## 维护者与许可证 Lumis SDK 目前由 [Solomon Eshun](mailto:solomoneshun373@gmail.com) 维护，并根据 [Apache License 2.0](LICENSE) 获得许可。

标签：AIOps, Python, 事故响应, 文档结构分析, 无后门, 模块化设计, 流水线, 自动化修复, 逆向工具, 防御加固