Metadata-Version: 2.4
Name: vigil-agent-harness
Version: 0.1.18
Summary: Vigil — 运维 agent harness：记住整个平台，安全地动生产（拓扑表事实层 + runbook 程序层 + 权限矩阵纵深防御）
Author: markjuneau
License-Expression: MIT
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=2.24.0
Requires-Dist: certifi>=2026.5.20
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: fire>=0.7.1
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: rich>=14.3.3
Requires-Dist: tenacity>=9.1.4
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: ruamel.yaml>=0.18.17
Requires-Dist: requests>=2.33.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pydantic>=2.13.4
Requires-Dist: prompt_toolkit>=3.0.52
Requires-Dist: croniter>=6.0.0
Requires-Dist: packaging>=26.0
Requires-Dist: Markdown>=3.10.2
Requires-Dist: PyJWT[crypto]>=2.13.0
Requires-Dist: urllib3<3,>=2.7.0
Requires-Dist: cryptography>=48.0.1
Requires-Dist: tzdata>=2025.3; sys_platform == "win32"
Requires-Dist: psutil>=7.2.2
Requires-Dist: websockets>=15.0.1
Requires-Dist: pathspec>=1.1.1
Requires-Dist: fastapi<1,>=0.104.0
Requires-Dist: uvicorn[standard]<1,>=0.24.0
Requires-Dist: python-multipart<1,>=0.0.9
Requires-Dist: ptyprocess<1,>=0.7.0; sys_platform != "win32"
Requires-Dist: pywinpty<3,>=2.0.0; sys_platform == "win32"
Requires-Dist: pywin32<312,>=306; sys_platform == "win32"
Requires-Dist: Pillow>=12.3.0
Requires-Dist: concurrent-log-handler>=0.9.29; sys_platform == "win32"
Requires-Dist: nemo-relay<0.7,>=0.6.0; (sys_platform == "darwin" and platform_machine == "arm64") or (sys_platform == "linux" and platform_machine == "x86_64" and "android" not in platform_release) or (sys_platform == "linux" and platform_machine == "aarch64" and "android" not in platform_release) or (sys_platform == "win32" and platform_machine == "AMD64") or (sys_platform == "win32" and platform_machine == "ARM64")
Provides-Extra: anthropic
Requires-Dist: anthropic==0.87.0; extra == "anthropic"
Provides-Extra: exa
Requires-Dist: exa-py==2.10.2; extra == "exa"
Provides-Extra: firecrawl
Requires-Dist: firecrawl-py==4.17.0; extra == "firecrawl"
Provides-Extra: parallel-web
Requires-Dist: parallel-web==0.4.2; extra == "parallel-web"
Provides-Extra: fal
Requires-Dist: fal-client==0.13.1; extra == "fal"
Provides-Extra: edge-tts
Requires-Dist: edge-tts==7.2.7; extra == "edge-tts"
Provides-Extra: modal
Requires-Dist: modal==1.3.4; extra == "modal"
Provides-Extra: daytona
Requires-Dist: daytona==0.155.0; extra == "daytona"
Provides-Extra: vercel
Requires-Dist: vercel==0.7.2; extra == "vercel"
Provides-Extra: hindsight
Requires-Dist: hindsight-client==0.6.1; extra == "hindsight"
Provides-Extra: dev
Requires-Dist: debugpy==1.8.20; extra == "dev"
Requires-Dist: pytest==9.1.1; extra == "dev"
Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
Requires-Dist: mcp==1.28.1; extra == "dev"
Requires-Dist: starlette==1.3.1; extra == "dev"
Requires-Dist: ty==0.0.21; extra == "dev"
Requires-Dist: ruff==0.15.10; extra == "dev"
Requires-Dist: setuptools==83.0.0; extra == "dev"
Provides-Extra: messaging
Requires-Dist: python-telegram-bot[webhooks]==22.6; extra == "messaging"
Requires-Dist: discord.py[voice]==2.7.1; extra == "messaging"
Requires-Dist: aiohttp==3.14.1; extra == "messaging"
Requires-Dist: brotlicffi==1.2.0.1; extra == "messaging"
Requires-Dist: slack-bolt==1.29.0; extra == "messaging"
Requires-Dist: slack-sdk==3.43.0; extra == "messaging"
Requires-Dist: qrcode==7.4.2; extra == "messaging"
Provides-Extra: cron
Provides-Extra: slack
Requires-Dist: slack-bolt==1.29.0; extra == "slack"
Requires-Dist: slack-sdk==3.43.0; extra == "slack"
Requires-Dist: aiohttp==3.14.1; extra == "slack"
Provides-Extra: matrix
Requires-Dist: mautrix[encryption]==0.21.0; extra == "matrix"
Requires-Dist: aiosqlite==0.22.1; extra == "matrix"
Requires-Dist: asyncpg==0.31.0; extra == "matrix"
Requires-Dist: aiohttp-socks==0.11.0; extra == "matrix"
Requires-Dist: aiohttp==3.14.1; extra == "matrix"
Provides-Extra: wecom
Requires-Dist: defusedxml==0.7.1; extra == "wecom"
Provides-Extra: cli
Requires-Dist: simple-term-menu==1.6.6; extra == "cli"
Provides-Extra: tts-premium
Requires-Dist: elevenlabs==1.59.0; extra == "tts-premium"
Provides-Extra: voice
Requires-Dist: faster-whisper==1.2.1; extra == "voice"
Requires-Dist: sounddevice==0.5.5; extra == "voice"
Requires-Dist: numpy==2.4.3; extra == "voice"
Provides-Extra: wake
Requires-Dist: openwakeword==0.6.0; extra == "wake"
Requires-Dist: onnxruntime==1.27.0; extra == "wake"
Requires-Dist: sherpa-onnx==1.13.4; extra == "wake"
Requires-Dist: sentencepiece==0.2.2; extra == "wake"
Requires-Dist: pvporcupine==4.0.3; extra == "wake"
Requires-Dist: sounddevice==0.5.5; extra == "wake"
Requires-Dist: numpy==2.4.3; extra == "wake"
Requires-Dist: ai-edge-litert==2.1.6; platform_system == "Darwin" and extra == "wake"
Provides-Extra: honcho
Requires-Dist: honcho-ai==2.2.0; extra == "honcho"
Provides-Extra: supermemory
Requires-Dist: supermemory==3.50.0; extra == "supermemory"
Provides-Extra: mem0
Requires-Dist: mem0ai==2.0.10; extra == "mem0"
Provides-Extra: vision
Provides-Extra: pty
Provides-Extra: mcp
Requires-Dist: mcp==1.28.1; extra == "mcp"
Requires-Dist: starlette==1.3.1; extra == "mcp"
Provides-Extra: nemo-relay
Provides-Extra: homeassistant
Requires-Dist: aiohttp==3.14.1; extra == "homeassistant"
Provides-Extra: sms
Requires-Dist: aiohttp==3.14.1; extra == "sms"
Provides-Extra: teams
Requires-Dist: microsoft-teams-apps==2.0.13.4; extra == "teams"
Requires-Dist: aiohttp==3.14.1; extra == "teams"
Provides-Extra: computer-use
Requires-Dist: mcp==1.28.1; extra == "computer-use"
Requires-Dist: starlette==1.3.1; extra == "computer-use"
Provides-Extra: acp
Requires-Dist: agent-client-protocol==0.9.0; extra == "acp"
Provides-Extra: mistral
Requires-Dist: mistralai==2.4.8; extra == "mistral"
Provides-Extra: otlp
Requires-Dist: opentelemetry-sdk==1.39.1; extra == "otlp"
Requires-Dist: opentelemetry-exporter-otlp-proto-http==1.39.1; extra == "otlp"
Provides-Extra: bedrock
Requires-Dist: boto3==1.42.89; extra == "bedrock"
Provides-Extra: vertex
Requires-Dist: google-auth==2.55.1; extra == "vertex"
Provides-Extra: azure-identity
Requires-Dist: azure-identity==1.25.3; extra == "azure-identity"
Provides-Extra: termux
Requires-Dist: python-telegram-bot[webhooks]==22.6; extra == "termux"
Requires-Dist: vigil-agent-harness[cron]; extra == "termux"
Requires-Dist: vigil-agent-harness[cli]; extra == "termux"
Requires-Dist: vigil-agent-harness[mcp]; extra == "termux"
Requires-Dist: vigil-agent-harness[honcho]; extra == "termux"
Requires-Dist: vigil-agent-harness[acp]; extra == "termux"
Provides-Extra: termux-all
Requires-Dist: vigil-agent-harness[termux]; extra == "termux-all"
Requires-Dist: vigil-agent-harness[google]; extra == "termux-all"
Requires-Dist: vigil-agent-harness[homeassistant]; extra == "termux-all"
Requires-Dist: vigil-agent-harness[sms]; extra == "termux-all"
Requires-Dist: vigil-agent-harness[web]; extra == "termux-all"
Requires-Dist: vigil-agent-harness[pty]; extra == "termux-all"
Provides-Extra: dingtalk
Requires-Dist: dingtalk-stream==0.24.3; extra == "dingtalk"
Requires-Dist: alibabacloud-dingtalk==2.2.42; extra == "dingtalk"
Requires-Dist: qrcode==7.4.2; extra == "dingtalk"
Provides-Extra: feishu
Requires-Dist: lark-oapi==1.6.8; extra == "feishu"
Requires-Dist: qrcode==7.4.2; extra == "feishu"
Provides-Extra: google
Requires-Dist: google-api-python-client==2.194.0; extra == "google"
Requires-Dist: google-auth==2.55.1; extra == "google"
Requires-Dist: google-auth-oauthlib==1.3.1; extra == "google"
Requires-Dist: google-auth-httplib2==0.3.1; extra == "google"
Requires-Dist: httplib2==0.32.0; extra == "google"
Requires-Dist: pyasn1==0.6.4; extra == "google"
Provides-Extra: youtube
Requires-Dist: youtube-transcript-api==1.2.4; extra == "youtube"
Provides-Extra: web
Requires-Dist: fastapi==0.133.1; extra == "web"
Requires-Dist: uvicorn[standard]==0.41.0; extra == "web"
Requires-Dist: starlette==1.3.1; extra == "web"
Requires-Dist: python-multipart==0.0.32; extra == "web"
Provides-Extra: all
Requires-Dist: hermes-agent[cron]; extra == "all"
Requires-Dist: hermes-agent[cli]; extra == "all"
Requires-Dist: hermes-agent[pty]; extra == "all"
Requires-Dist: hermes-agent[mcp]; extra == "all"
Requires-Dist: hermes-agent[homeassistant]; extra == "all"
Requires-Dist: hermes-agent[sms]; extra == "all"
Requires-Dist: hermes-agent[acp]; extra == "all"
Requires-Dist: hermes-agent[google]; extra == "all"
Requires-Dist: hermes-agent[web]; extra == "all"
Requires-Dist: hermes-agent[youtube]; extra == "all"
Dynamic: license-file

# Vigil ☉ —— 运维 Agent Harness

![Vigil](assets/banner.png)

> **记住整个平台，安全地动生产。**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![Python](https://img.shields.io/badge/Python-3.11%2B-blue)

Vigil 是一个**面向运维场景的 AI agent harness**：让 agent 在真实服务器环境里干活时，
既「记得住整个平台」，又「动得安全」。Vigil 完全 fork 自
[Hermes Agent](https://github.com/juneauwang/vigil-agent-harness)（MIT License），
保留其成熟的 agent 内核（终端、工具调用、会话、记忆、插件），独立演进出面向
生产运维的三层核心能力。

---

## 目录

- [为什么需要 Vigil](#为什么需要-vigil)
- [核心特性](#核心特性)
- [工作原理](#工作原理)
- [快速开始](#快速开始)
- [一次会话长什么样](#一次会话长什么样)
- [安全模型](#安全模型)
- [Roadmap](#roadmap)
- [License](#license)

---

## 为什么需要 Vigil

很多小团队**没有专职运维**：服务器是开发顺手管的，CMDB 不存在，故障手册不存在，
半夜出事靠回忆。Vigil 给这类团队三样最缺的东西：

- **记忆** —— 平台的户口本和关系图（拓扑表），agent 不会"换了会话就失忆"
- **经验** —— 出过的故障沉淀成可执行的 runbook，下次不再从头查
- **护栏** —— 权限矩阵硬性拦截危险命令，手滑删生产这件事从"靠自觉"变成"靠机制"

如果你有专职 SRE、完整 CMDB 和工单系统——Vigil 对你可能是锦上添花；
如果你一个人扛着几台服务器——Vigil 就是给你做的。

## 核心特性

| 层 | 载体 | 职责 |
|---|---|---|
| **事实层** | 平台拓扑表（`topo_query` / `topo_update` / `topo-discover`） | 长记忆地记住平台：实体、环境、依赖、归属。`topo-discover` 自动发现（SSH 扫 docker/k8s/端口）生成，任何运维动作前先确认目标身份与环境；跨环境操作默认拒绝 |
| **程序层** | runbook（`runbook_load` / `runbook_checkpoint` / `runbook_create`） | 唯一允许的「怎么动」：事故处理按 runbook 匹配流程执行；部署按 checklist 阶段门推进；跑通的处置流程可 `runbook_create` 沉淀为结构化 YAML，越用越厚 |
| **审计层** | 运行轨迹（`vigil trajectory` / Web 审计页） | append-only 事件级日志：谁在什么时间执行了什么命令、结果如何；可查询、可回放、可裁剪——运维审计合规的底账 |
| **纵深防御** | 权限矩阵（命令分级 L1–L4 × 环境 local/test/dev/prod） | 命令 → **执行 / 审批 / 拒绝** 三态裁决。矩阵 DENY 不可被 yolo、mode=off 或 allowlist 绕过；approve 必须有真人在场 |

额外两个让它"越用越强"的机制：

- **自进化**：每次真实排障会沉淀成 runbook / skill——Vigil 用一天，强一点
- **会话记忆**：平台事实（拓扑）与人的偏好（memory）分离存储，互不挤占

## 工作原理

```text
               ┌─────────────────────────────────────┐
               │        Vigil 会话（每个 session）      │
               │                                     │
  启动时注入 ───▶  TOPO 段（拓扑表第一层）              │
               │        │                           │
  用户指令 ────▶  topo_query 确认目标身份/环境 ──▶ 权限矩阵
               │        │                    (目标级 env 判定)
               │   runbook_load 匹配处置流程          │
               │        │                    execute / approve / deny
               │   工具执行（ssh / kubectl / docker）│
               │        │                           │
  执行后 ─────▶  topo_update 更新事实 + 审计戳        │
               │        │                           │
               │   经验沉淀：runbook / skill 自动成长  │
               └─────────────────────────────────────┘
```

两条铁律贯穿始终：

- **先确认，再动手**：任何运维操作前先查拓扑确认目标；命令的目标是谁，就用谁的
  环境来裁决（test 会话操作 prod 节点？矩阵直接拦）
- **默认 fail-closed**：不确定就拒绝。topo/runbook 工具按数据存在性自动可用，权限矩阵默认启用（显式 `enabled: false` 可关）；矩阵默认 `env: test`，核对通过后再切 prod

## 快速开始

**前置**：Python 3.11+、git

```bash
# 1. 安装（生成 vigil 命令入口）
pip install vigil-agent-harness

# 2. 直接进入 Vigil——ops 能力默认加载（topology / runbooks / 权限矩阵），
#    全新安装的 default profile 自带 ops 配置与样例拓扑，无需任何初始化
vigil

# 3. 配置模型（如 DeepSeek）——在 ~/.vigil/config.yaml 添加 model 段，
#    并在同目录 .env 放 API key
```

> 如需手动重建样例 profile，可用 `vigil ops-init`（可选——老用户/自托管
> 显式重建或迁移仍可用，首装已不需要）。

首次进入后，让 Vigil 摸清你的平台：**自动发现拓扑**——把每台机器的 IP 和
SSH 凭据告诉它，它会 SSH 进去扫 docker / k8s / systemd 服务 / 端口，生成实体
清单供你确认后落盘：

```bash
vigil topo-discover          # 引导式：填 IP + 凭据 → 扫描 → 人工确认 → 写入 topology.yaml
```

也可以手动编辑拓扑表（`topology.yaml` + `entities/`，高级用法）。然后让它干
第一件真活：**"检查拓扑里哪些实体 last_verified 过期了"**。

### Web 控制台（UI 壳）

v0.1.15 起带 Web 控制台（`vigil dashboard`，默认 http://127.0.0.1:9119）：
- **对话页**（`/chat`）：浏览器里和 Vigil 对话，流式回复、工具调用折叠展示、
  多会话并行互不干扰
- **拓扑图**（`/topology`）：可交互拓扑图（缩放/平移/点击节点看详情抽屉），
  状态着色 + 活性显示（"X 分钟前活跃"，来自 agent 真实交互打点，零主动探测）
- **审批全局弹窗**：agent 请求审批时任何页面弹出决策框（批准/拒绝/忽略），
  顶栏铃铛角标实时；Web 上批准 = 与 CLI 同一个审批流，prod 变更确认门照样拦
- 其余页面：Runbook / 状态 / 审计等可视化
```bash
vigil dashboard        # 启动控制台，浏览器打开 http://127.0.0.1:9119
```

### 从源码安装（开发者 / 自托管）

想改代码、跑测试、自定义 fork 时用这条路。一键脚本 `setup-vigil.sh`
（clone → 装依赖 → 初始化）：

```bash
# 方式 A：已 clone 仓库，在仓库根目录直接跑
git clone https://github.com/juneauwang/vigil-agent-harness.git
cd vigil-agent-harness
./setup-vigil.sh

# 方式 B：未 clone，远程一键（自动 clone 到 ~/.vigil/vigil-agent-harness）
bash <(curl -fsSL https://raw.githubusercontent.com/juneauwang/vigil-agent-harness/main/setup-vigil.sh)
```

脚本会创建 `.venv`、安装依赖、把 `vigil` 软链到 `~/.local/bin`，并询问是否
执行 `vigil ops-init`。也可以手动装：

```bash
python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/vigil ops-init          # 或 .venv/bin/python scripts/ops_init.py（同入口）
.venv/bin/vigil -p ops
```

## 常见问题

**国内镜像装不到？**
新发布的包，国内镜像（阿里云/清华/中科大）同步有延迟（几小时到一天），装不到先换 pypi.org 直连：

```bash
pip install vigil-agent-harness -i https://pypi.org/simple/
# 或：主包走 pypi.org，依赖走国内镜像（更快）
pip install vigil-agent-harness \
  --index-url https://pypi.org/simple/ \
  --extra-index-url https://mirrors.aliyun.com/pypi/simple/
```

**报 "from versions: none"？**
Vigil 要求 **Python >= 3.11 且 < 3.14**。Python 版本过低时，pip 会报
`Could not find a version that satisfies the requirement ... (from versions: none)`——
这是版本门槛，不是网络问题。先查 `python3 --version`，装 Python 3.11+ 再试。
推荐用 uv 一步到位：

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv --python 3.12 .venv && source .venv/bin/activate
pip install vigil-agent-harness -i https://pypi.org/simple/
```

**数据目录**
Vigil 的数据目录为 `~/.vigil`（可用 `VIGIL_HOME` 覆盖）。

## 一次会话长什么样

启动 `vigil -p ops` 后,控制台头部长这样(真实输出):

```text
╭──────────────────── Vigil v0.1.15 (2026.8.15) ──────────────────╮
│                PROFILE     ops                                   │
│       /\_/\    ENV         [test]                                │
│      ( ◉.◉ )   GATES       matrix ON · L1–L4 × env               │
│       > ^ <                → execute / approve / deny            │
│                TOPOLOGY    20 entities                           │
│                RUNBOOKS    6 loaded                              │
│ deepseek-v4-flash          HOME  ~/.vigil/profiles/ops           │
│ /home/your-name                                                  │
│ Session: 20260809_171603   ◈ topo_query · runbook_load           │
│                                · permission matrix · /help       │
╰──────────────────────────────────────────────────────────────────╯

Welcome to Vigil — topology loaded, runbooks ready, permission gates armed.

你：帮我排查 node2 的 sshd 为什么连不上
Vigil：先确认目标身份 → topo_query node2 → runbook_load 匹配
       "ssh-idle-hang" → 诊断（sshd -T / 保活配置）→ 修复 → 验证
```

左边是模型/工作目录/会话锚点，右边是运维能力实时状态——在哪个环境、
权限门开没开、记住了多少实体、有哪些 runbook，一眼可见。

## 安全模型

| 层 | 机制 | 说明 |
|---|---|---|
| L1 | toolset 裁剪 | 会话按角色加载最小工具集，减少攻击面 |
| L2 | 静态规则硬 gate | 危险命令模式（rm -rf / drop table / delete namespace）直接拦截，0 token |
| L3 | 目标级权限矩阵 | 命令目标（拓扑实体）的 env 决定裁决：prod 的 L3/L4 硬拒、L2 审批 |
| L4 | 部署 checklist | 生产部署强制走 runbook 阶段门：前置核对 → 发布 → 真实验证 → 回滚预案 |

## Roadmap

- [x] 拓扑表（事实层）+ topo_query / topo_update
- [x] runbook 程序层 + L4 部署阶段门
- [x] 目标级权限矩阵（跨环境硬约束）
- [x] 品牌化（Vigil 入口 / banner / 皮肤）
- [x] PyPI 分发（pip install vigil-agent-harness）
- [x] 一键安装脚本 `setup-vigil.sh`（源码安装/自托管路径：clone → 装依赖 → 初始化）
- [x] Web 控制台（`vigil dashboard`，拓扑/runbook/审批/审计/终端）
- [x] 运行轨迹审计（`vigil trajectory`，append-only 事件日志 + 查询/回放/裁剪）
- [x] 反馈闭环（`runbook_create`：跑通的任务沉淀为结构化 runbook）
- [ ] 同步 adapter（terraform.tfstate / k8s API）
- [ ] 拓扑体检 cron（自动检查实体 freshness）
- [x] 数据目录独立（默认 `~/.vigil`，`VIGIL_HOME` 可覆盖）

## License

MIT。Vigil 是 [Hermes Agent](https://github.com/juneauwang/vigil-agent-harness) 的独立 fork，版权声明见 [LICENSE](LICENSE)。
