Cirdan

Cirdan

Cirdan 是一款值班软件修复 Agent。 生产告警触发时——无论来自 Grafana、 Alertmanager 还是 Slack。Cirdan 会根据 cirdan.yaml 中明确配置的 services: 注册表， 解析受影响的服务及其代码仓库，在隔离的运行器（Docker Compose 或 Kubernetes）中 复现故障，让编码 Agent 修复代码——可以使用你自己已登录的 Claude Code / Codex CLI， 也可以使用 API 提供商——然后通过固定的复现探针和代码仓库的测试套件重新验证修复， 并创建已验证的拉取请求。策略允许时，它还会合并、部署并验证生产环境是否恢复； 若恢复失败，则会以 manual_required 状态停止，并提供完整证据。

alert ─▶ resolve service + repo (the services: registry) ─▶ reproduce in an isolated runner
      ─▶ coding agent fixes the code ─▶ verify (pinned repro probe + sandboxed test suite)
      ─▶ verified PR (@cirdan review loop; CI checks watched) ─▶ optional merge + deploy
      ─▶ verify recovery in production

它的作用是：凌晨 3 点因代码问题触发告警时，你等到的将是已验证的修复拉取请求 （或已完成的部署及恢复确认），而不是一条呼叫通知。

Cirdan 有意不充当基础设施映射器、拓扑探索器、可观测性仪表板、通用 Agent 启动器 或 ChatOps 机器人。它只修复你注册的服务——不会发现任何内容，也不会隐式修复任何内容。

快速入门

pipx install "cirdanops[all]"      # or uv / pip / npm / brew / curl / docker — see Install
cirdan setup                       # opens the local, loopback-only setup UI

cirdan setup 会引导你完成一条简短流程，并显示就绪状态横幅；只有在此安装确实能够 修复问题时，横幅才会变为**“已就绪，可以修复”**：

1. 选择接入方式——使用 CLI（使用此计算机上已登录的工具）或使用 API（托管凭据
   • GitHub App）。请参阅两种运行方式。
2. 连接告警来源——Grafana webhook（+ HMAC）、原生 Alertmanager 接收端或 Slack。
3. 选择修复代码仓库——在源代码连接中，Cirdan 会列出你的 gh 登录帐号 有权推送的代码仓库；选择允许它修复的仓库。它只会修复选中的代码仓库。
4. 验证路由——告警路由步骤会生成一条示例告警（或使用你粘贴的真实负载），并且 必须显示该告警已解析到一个选中的代码仓库**，并且**路由到代码修复流水线。
5. 启动守护进程并发送演示告警：

cirdand serve --http
curl -X POST localhost:8090/v1/ingest/grafana -d @examples/demo/alert.firing.json

examples/demo/ 中可运行的演示会串联起整个流程。同一份检查清单也可 在无界面模式下使用——cirdan status --checks 会打印相同的表格，并在安装就绪前以 状态码 1 退出。常用的设置选项：

• cirdan setup --terminal — 使用文本步骤流程，而非 UI
• cirdan setup --all — 无需提示，运行所有步骤（脚本 / CI）
• cirdan setup --system — 使用 ~/.cirdan 作为机器级作用域，而非代码仓库

安装

从 PyPI 安装（推荐）：

uv tool install "cirdanops[all]"
# or
pipx install "cirdanops[all]"
pip install "cirdanops[all]"

无需 Python — npm / Homebrew / curl：

npx -y @cirdanops/cli serve-mcp        # run the MCP server, zero install
npm install -g @cirdanops/cli          # or put the `cirdan` command on your PATH
brew install adanb13/tap/cirdan        # macOS / Linux (Homebrew)
curl -LsSf https://raw.githubusercontent.com/adanb13/cirdan/main/packaging/install.sh | sh
# Windows: irm https://raw.githubusercontent.com/adanb13/cirdan/main/packaging/install.ps1 | iex

这些方式会安装一个独立二进制文件——无需 Python 3.11+。支持的平台：macOS（arm64）、Linux x64/arm64（glibc）、Windows x64。在 Intel Mac、Alpine/musl 或其他平台上，请使用上述 PyPI 安装方式。

然后用一条命令完成设置（参见快速入门）：

cirdan setup              # inside a repo
# or, machine-level scope in ~/.cirdan:
cirdan setup --system

两种方式都会打开相同的引导式设置流程：选择路径，连接告警来源和 GitHub， 选择修复仓库，验证路由，然后启动持续运行的守护进程。

针对性安装：cirdanops[mcp]、cirdanops[api]、cirdanops[slack]、 cirdanops[agent]、cirdanops[github-app]、cirdanops[secrets]，或组合安装， 例如 cirdanops[api,mcp]。沙箱运行器无需额外依赖——它们使用 PATH 中已有的 docker/kubectl CLI。

各平台的前置条件（Python 3.11+ 和 uv 或 pipx）：

# macOS
brew install [email protected] uv

# Windows
winget install astral-sh.uv

# Ubuntu / Debian
sudo apt install python3.12 python3-pip pipx
# or get uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

Docker（无需 Python）：

# run the always-on repair daemon: alert receiver + isolated repair runner,
# using the host's Docker for sandboxes
docker run -d \
  -v "$PWD":/workspace:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 127.0.0.1:8090:8090 \
  ghcr.io/adanb13/cirdan

（或使用提供的 docker-compose.yml 运行 docker compose up）

从源码安装（最新未发布版本）：

pip install "cirdanops[all] @ git+https://github.com/adanb13/cirdan.git"

会安装两个命令：

命令	说明
cirdan	面向用户/Agent 的 CLI
cirdand	长时间运行的 Always ON 守护进程

本地开发（从克隆的仓库开始）

贡献者从克隆的仓库进行开发，并使用可编辑的虚拟环境，因此工作树中的更改会立即生效——编辑后无需重新安装。make install 会创建 .venv，并以可编辑模式安装软件包（发行包名称为 cirdanops），附带 [all,dev] 额外依赖——包括所有运行时功能和测试工具链：

git clone https://github.com/adanb13/cirdan.git
cd cirdan
make install     # ≈ python3 -m venv .venv && .venv/bin/pip install -e ".[all,dev]"
make test        # .venv/bin/python -m pytest tests/ -q

需要 Python 3.11+。手动执行的两行等效命令适用于标准 Python； make install 还会处理不含 pip 的虚拟环境（此时会改用 python3 -m venv --without-pip，并在虚拟环境中引导安装 pip）。

可编辑安装会将两个控制台脚本放入 .venv/bin，无需重新构建即可运行工作树中的代码：

.venv/bin/cirdan setup                                    # or: .venv/bin/python -m cirdan.cli.main setup
.venv/bin/cirdand serve --http
.venv/bin/python -m pytest tests/test_slack_events.py -q  # a single test module

常用 Make 目标（运行 make help 可查看全部目标）：

目标	作用
make install	创建 .venv 并以可编辑模式安装 [all,dev]
make test	运行完整的 pytest 测试套件
make build	将 sdist 和 wheel 构建到 dist/
make setup-wipe DIR=<dir> [KEY=1]	重置项目的引导设置，让 cirdan setup 从第 0 步重新开始（KEY=1 还会删除全局主密钥）
make demo-up … make demo-clean	构建并运行 examples/demo/ 中可运行的堆栈

在没有操作系统密钥环的无头设备上，执行 cirdan setup 时要存储凭据， 需先在环境中设置主密钥： export CIRDAN_MASTER_KEY=$(.venv/bin/python -c 'import os,base64;print(base64.b64encode(os.urandom(32)).decode())')。

两种运行方式：使用 CLI / 使用 API

初始设置界面会选择部署模式（cirdan.yaml 中的 deployment_mode:），后续所有配置都受其限制：

使用 CLI（cli，默认）——Cirdan 使用此计算机上已登录的工具运行。GitHub 写入通过你的 gh auth login 进行；编码 Agent 是检测到的、已登录的 Claude Code 或 Codex CLI，并在隔离的修复工作区中以无头模式启动；沙盒运行器是本地 Docker（或 kubectl）。顺利完成设置无需存储密钥，也无需 GitHub App——环境变量 API 密钥和 GitHub App 仍可通过明确标记为“高级”的开关启用。

使用 API（api）——采用无头托管模式，适用于共享部署或企业部署。提供商 API 密钥会加密存储（cirdan secret；AES-256-GCM），GitHub 写入通过 GitHub App（引导式清单配置）进行，并使用短期有效的逐仓库安装令牌；企业安全配置会自动生成：在加载配置时拒绝继承的 gh 身份验证和由主机启动的 CLI Agent。

两种方式最终都满足同一套就绪条件——设置界面横幅和 cirdan status --checks 会呈现相同的表格：已选择修复仓库（每个仓库均可解析）· 已连接告警来源 · 路由验证（证明示例告警或实时告警已解析到所选仓库，并路由到代码流水线）· remediation.mode ∈ {develop, deliver} · 已通过实时探测的编码 Agent · 已验证的 GitHub 写入路径（包括访问每个所选仓库的权限）· PATH 中有 git · 可正常工作的沙盒运行器 · 守护进程正在运行。每项红色状态都会显示确切的修复命令或可解决问题的设置步骤。

旧版配置将始终可加载：deployment_mode: single-user 会按 cli 读取，business 会按 api 读取；下次保存设置时，文件内容会迁移。

配置

cirdan setup 会为你写入 cirdan.yaml；所有内容也都可以手动编辑——参见 cirdan.yaml.example。文件的核心是 services: 注册表：Cirdan 可以修复的明确服务列表、警报如何映射到这些服务，以及它们的代码所在位置。

services:
  - name: checkout-api                 # canonical id (lowercase, node-id-safe)
    repo: acme/checkout                # "org/name" — the PR / repair target
    aliases: [checkout, checkout-svc]  # extra alert-label names for this service
    match_labels: {team: payments}     # optional exact label matchers (first match wins)
    deploy:                            # how it runs in prod + how the runner rebuilds it
      kind: compose                    # compose | k8s | helm
      compose_service: checkout-api    # defaults to the entry name
      compose_files: [docker-compose.yml]
    deploy_workflow: deploy.yml        # per-service GitHub Actions deploy (optional)
    telemetry_service: checkout        # Loki/PromQL service label; defaults to name

  - name: payments-api
    repo: acme/payments
    source_root: ~/src/payments        # local checkout (cli pathway only)
    deploy:
      kind: k8s
      namespace: prod
      workload: payments-api           # kubernetes_kind defaults to Deployment

警报按以下顺序映射到服务：明确的 cirdan_node 标签、match_labels，然后是一组常见标签（service、service_name、app、job、 deployment、statefulset、pod、container、instance 的主机名、 annotations.service、alertname），与名称和别名进行匹配。没有隐式默认值：未匹配到任何服务的警报会创建一个分诊事件，绝不会自动修复“唯一已注册的代码库”。

路由策略。 每个警报来源都会经过同一套优先匹配策略：

routing_policy:
  rules:
    - when: {service: checkout-api, severity: [high, critical]}
      pipeline: full_remediation       # may merge/deploy — only under mode: deliver + the auto_* gates
    - when: {source: slack}
      pipeline: triage_only

如果没有匹配的规则，映射到已注册服务且其代码库可解析的警报，在达到相应严重级别（responder.severities，默认为 high/critical）时，默认采用 reproduce_and_pr_only；其他情况均安全地降级为 triage_only。流水线按处理深度递减排列：full_remediation · reproduce_and_pr_only · lightweight_pr_only · triage_only。

安全门控（位于 source_hosts.github 和 remediation 下）：

门控	默认值	作用
require_verified_pr	true	只有在复现故障（基线探测失败）且验证修复（修复后探测通过）时，才会创建 PR
require_tests	false	额外要求在创建任何 PR 前，通过沙箱运行的代码库测试
auto_merge	false	为 Cirdan PR 启用 GitHub 原生自动合并——分支保护和审核者仍会把关实际合并；Cirdan 绝不会强制合并
auto_deploy	false	交付总开关：部署已合并的修复，并在生产环境中重新验证
require_checks	true	在合并提交的 CI 检查全部通过前，阻止触发部署（仅用于阻止：可以阻止部署，但绝不会启动部署）
remediation.mode	develop	限制任何流水线可执行操作的上限；deliver 可解锁合并/部署

部署失败或生产验证失败时，交付会停止在 manual_required 状态，并通知相关失败证据、记录审计信息——Cirdan 会停下来等待人工介入（自动回滚明确暂不支持）。

命令

cirdan setup                  # guided setup: loopback UI (default) or --terminal
cirdan install --project      # scripted variant: hook agents, register MCP, arm responder, start daemon
cirdan incidents              # detection pass + list incidents
cirdan explain <incident-id>  # evidence-backed explanation
cirdan respond <incident-id>  # write the incident brief + invoke the responder once under a mode
cirdan remediate <incident-id>  # durable fix: isolated workspace → reproduce → fix → verify → PR
cirdan deliver <incident-id>  # manually drive an in-flight delivery (merge → deploy → prod-verify)
cirdan watch                  # foreground event + incident stream
cirdan status [--checks]      # daemon status; --checks runs the full readiness checklist
cirdan stop                   # stop the daemon for this scope
cirdan secret set|get|list|delete   # encrypted credential store (provider keys, App key)
cirdan slack-app              # emit the importable Slack app manifest for the configured intake
cirdan preview-intake         # dry-parse a sample payload; --source/--service runs the routing proof
cirdan serve-mcp              # MCP server (stdio; --transport streamable-http)

始终开启

cirdand serve                        # ingest alerts, detect incidents, repair, deliver — forever
cirdand serve --http                 # + the HTTP API (alert ingestion endpoints)
cirdand serve --http --mcp           # + MCP mounted at /mcp

守护进程会运行受监管的循环任务——访问权限刷新、警报接收与事件检测、交付、PR 检查监控、@cirdan 评论处理，以及 Slack 收件箱（还有按配置启用的 Socket Mode 客户端和 Webhook 唤醒器）。循环任务崩溃时会记录日志并重启；绝不会导致守护进程退出。

每个作用域只允许运行一个实例：针对同一作用域启动第二个 cirdand serve（或 cirdan watch）时，会显示正在运行的进程 ID 并拒绝启动。cirdan status / cirdan stop（也可通过 cirdand 使用）可检查并关闭守护进程。

Agent 集成

Cirdan 也为你的编码 Agent 提供工具接口：CLI 背后的同一引擎通过 MCP 暴露恰好六个只读／证据工具——list_incidents、 explain_incident、get_recent_errors、get_logs、get_state 和 get_audit。 get_logs 和 get_state 接受来自 services: 的已注册服务名称（或别名），并自行解析运行中的容器／Pod。所有返回内容都会经过脱敏处理。

cirdan install --project             # full guided setup (recommended)
cirdan setup                         # re-run the guided setup anytime
cirdan install --platform claude     # .claude/skills/cirdan/SKILL.md + CLAUDE.md + .mcp.json
cirdan install --platform codex      # AGENTS.md + .codex/cirdan.md
cirdan install --platform cursor     # .cursor/rules/cirdan.mdc + .cursor/mcp.json
cirdan install --platform gemini     # GEMINI.md
cirdan install --platform vscode     # .github/copilot-instructions.md + .vscode/mcp.json
cirdan install --platform windsurf   # .windsurf/rules/cirdan.md  (MCP: global config)
cirdan install --platform roo        # .roo/rules/cirdan.md + .roo/mcp.json
cirdan install --platform cline      # .clinerules/cirdan.md  (MCP: editor UI)
cirdan install --platform opencode   # AGENTS.md + opencode.json
cirdan install --platform goose      # .goosehints  (MCP: global config)
cirdan install --platform generic    # .agents/skills/cirdan/SKILL.md + AGENTS.md

cirdan install --project 是引导式设置，可让 Cirdan 持续运行修复循环，而不只是记录相关说明：

1. 检测你机器上的 Agent（claude/codex/cursor/gemini/vscode/windsurf/opencode/goose 配置或 CLI），并仅为检测到的 Agent 写入指令文件（另加通用的 AGENTS.md）
2. 在 .mcp.json 中注册 MCP 服务
3. 启用事件响应器，让守护进程告警转发给你的 Agent
4. 启动常驻守护进程（分离运行；cirdand status / cirdand stop）

步骤 3–4 会提示确认（默认是），也可以通过标志为脚本指定： --responder/--no-responder、--daemon/--no-daemon、--all-platforms。之后可随时通过 cirdan setup 重新运行这些步骤；它会显示每一步的当前状态，并且只提出尚未完成的步骤。安装操作具有幂等性，且绝不会修改 Cirdan 自有标记块以外的内容。

支持的 Agent。 首要支持的自动注册（原生指令文件，以及 Agent 支持可写配置时的 MCP）涵盖 Claude Code、Codex、Cursor、Gemini、VS Code（+ GitHub Copilot）、Windsurf、Roo Code、Cline、opencode 和 Goose。其他 Agent 均可通过通用的 AGENTS.md + .agents/skills/cirdan/SKILL.md 使用。自动检测可发现 claude/codex/cursor/gemini/vscode/windsurf/opencode/goose；可显式传入 --platform roo 或 --platform cline（它们是没有 CLI 可供检测的 VS Code 扩展，而 Cline 会将 MCP 配置保存在编辑器存储中，因此请通过其界面添加）。

对于未列出的任何 MCP 客户端，都可以手动注册 Cirdan——无需 Python：

// npx form — zero install
{ "command": "npx", "args": ["-y", "@cirdanops/cli", "serve-mcp"] }
// or, if `cirdan` is already on PATH (pip / npm -g / brew / curl install):
{ "command": "cirdan", "args": ["serve-mcp"] }

HTTP API

安装 [api] extra 后，cirdand serve --http 会暴露 /health、/incidents、 /incidents/{id}、/incidents/{id}/explain、/audit、位于 /v1/ingest/{grafana|alertmanager|…} 下的告警接收端点（以及 /v1/ingest/slack/events 和经过签名验证的 /v1/ingest/github webhook 唤醒端点）、/v1/slack/interactions、位于 /v1/logs 的精简 OTLP/HTTP JSON 接收端，以及位于 /setup 下的设置界面和 API。 添加 --mcp 可将 MCP 服务挂载到 /mcp。状态变更路由均受保护——参见 SECURITY.md。

升级

不会自动执行任何操作——PyPI 只提供拉取，因此已安装的版本会继续照常工作，直到你升级。新安装始终会获取最新版本。只需运行一个命令即可升级，具体取决于你的安装方式：

安装方式	升级命令
uv tool install	uv tool upgrade cirdanops
pipx install	pipx upgrade cirdanops
pip install	pip install -U cirdanops
npm（-g）	npm install -g @cirdanops/cli@latest（或直接运行 npx @cirdanops/cli@latest …）
Homebrew	brew upgrade cirdan
curl 安装程序	重新运行安装脚本（它会获取最新版本）
Docker	docker pull ghcr.io/adanb13/cirdan:latest（然后重启容器）

两个运维方面的说明：目前，各版本之间的现有 cirdan-out/ 产物和 SQLite 存储均兼容（1.0 之前会加入架构版本键和迁移机制）。此外，如果有更新版本，CLI 会在 stderr 打印一行暗色提示（最多每天检查一次，且仅限交互式终端）——设置 CIRDAN_NO_UPDATE_CHECK=1 可关闭提示。

从映射版本（≤ 0.9）升级

Cirdan 承诺专注于单一产品：修复工作流。基础设施映射功能——图谱/探索命令、运行时配置文件及其产物——已被移除。已移除的命令及其替代方案如下：

已移除的命令	替代方案
map、graph、enrich、fingerprint	cirdan.yaml 中显式声明的 services: 注册表——由你声明 Cirdan 可以修复的内容；不会发现任何内容
query、show	cirdan incidents、cirdan explain <id> 和 MCP 证据工具（get_logs、get_state、get_recent_errors）
access	cirdan status --checks——就绪检查清单

旧配置仍可加载：adapters:、enrich: 和 profile: 键会被接受并忽略（profile 只发出一次警告——Cirdan 始终运行修复工作流），而 deployment_mode: single-user/business 会规范化为 cli/api。打包中不再包含 [map] 和 [terraform] 额外组件。旧产物（infra.graph.json、INFRA_REPORT.md、infra.html、fingerprint.json 等）将不再生成——Cirdan 绝不会删除你的文件。

安全性

Cirdan 遵循其运行进程的访问权限，绝不提升权限；所有写入内容都会经过脱敏并接受审计。两种使用方式划定了不同的信任边界：“使用 CLI”会使用你自己的已登录工具和权限，而“使用 API”则强制采用企业配置文件（GitHub App + 已存储的密钥，不使用主机 CLI）。详情——包括网络行为，以及 PR 为什么只能针对配置的仓库——请参阅 SECURITY.md。

许可证

Apache-2.0