osagent

面向 Linux 运维场景的本地优先（local-first）智能代理系统。

将自然语言意图、策略治理、命令执行和多主机编排拆分为独立组件， 支持 TUI、HTTP API 和桌面客户端三种入口。

快速开始 · 核心能力 · 系统架构 · API 速览 · 安全治理

Bubble Tea TUI 界面：自然语言意图解析、策略预览、多主机执行与审批门禁

Tauri + React 桌面客户端：可视化指标、执行历史、多主机管理与自然语言输入

---

核心能力

🧠 自然语言到运维动作

• /intent — 将自然语言描述解析为匹配的 capability 和参数
• /intent/preview — 预览意图解析结果，不实际执行
• SSE 流式输出 — 实时查看意图分析、策略评估和执行过程

🛡️ 可解释执行与策略治理

• /command/preview — 查看命令执行前的完整预览
• /command/execute — 经策略审批后的安全执行
• OPA + Rego 策略引擎 — 热更新、风险等级、审批和并发控制
• 分级防护 — deny / needs_approval / dry-run 强制

⚡ 执行引擎

• 本地 / SSH 执行 — 支持单主机和批量多主机
• 连接池 — 高效管理多主机 SSH 连接
• Host-pinned Worker — 确保同一主机任务顺序执行

📋 任务编排

• Global Agent — 按工作流计划 → 运行 → 审批 → 完成
• Guardian Agent — 周期健康巡检和守护计划

🖥️ 多入口支持

入口	技术栈	场景
TUI	Bubble Tea (Go)	本地终端交互
HTTP API	FastAPI (Python)	程序化调用、集成
桌面客户端	Tauri + React	可视化运维管理

---

快速开始

前置依赖

• Go >= 1.26
• Python >= 3.11
• curl
• 可选：jq
• 如需 LLM 意图质量：Moonshot/Kimi API Key

1. 启动服务

在仓库根目录执行：

./scripts/dev-up.sh

该脚本会：

• 编译 osagent-policy / osagent-exec / osagent-tui
• 启动服务并监听：
  • /tmp/osagent-policy.sock
  • /tmp/osagent-exec.sock
  • http://127.0.0.1:18080
• 日志输出到 /tmp/osagent-logs/

2. 健康检查

curl -sS http://127.0.0.1:18080/health

期望返回：{"status":"ok","version":"0.1.0"}

3. 配置 LLM（可选但推荐）

方式 A：环境变量（启动前设置）

export KIMI_API_KEY=your_key
export KIMI_BASE_URL=https://api.moonshot.cn/v1
export KIMI_MODEL=kimi-k2.5

方式 B：运行时 API

curl -sS -X POST http://127.0.0.1:18080/config/llm \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"your_key","base_url":"https://api.moonshot.cn/v1","model":"kimi-k2.5"}'

4. 启动 TUI

/tmp/osagent-tui

常用输入范式：

输入	说明
cmd	在默认主机执行命令
@host cmd	在指定主机执行
> 自然语言	进入 copilot draft 流程
:dry on|off	切换 dry-run
:mode console|copilot	切换模式
:auto manual|assisted|guided_auto	切换自动级别

5. 停止服务

./scripts/dev-down.sh

---

系统架构

组件职责

组件	语言	职责
osagent-core	Python / FastAPI	意图解析、工具匹配、编排、会话、流式输出、任务 API
osagent-policy	Go / OPA	策略决策（allow / deny / needs_approval / ...）+ 审计标签
osagent-exec	Go	执行命令并返回 host 级结果（本地 / SSH）
tools/*.yaml	YAML	能力定义、参数、治理元数据、CLI 渲染模板
policies/*.rego	Rego	审批、黑名单、并发模式、dry-run 规则

执行流程

Intent / Command → Core → Policy Eval → Exec → Hosts
                        ↓
                   Preview → Approve → Execute

---

桌面客户端

apps/client 是 Tauri + React 客户端，包含终端、多标签、SFTP、拓扑、IDE、插件、全局 Agent 面板等能力。

开发运行：

cd apps/client
npm install
npm run tauri dev

仅前端调试：

cd apps/client
npm run dev

建议依赖：

• Node.js >= 20
• Rust stable（Tauri 2）

---

API 速览

基础地址：http://127.0.0.1:18080

基础与配置

• GET /health
• POST /config/apikey
• POST /config/llm

意图与执行

• POST /intent
• POST /intent/preview
• POST /intent/stream
• POST /intent/preview/stream
• POST /execute
• POST /command/preview
• POST /command/execute

会话与运行时视图

• POST /session/start
• GET /session/{session_id}
• GET /session/{session_id}/messages
• GET /sessions
• GET /sessions/{session_id}/turns
• GET /nodes
• GET /providers
• GET /resource-sessions

任务编排

• POST /global-agent/plan
• POST /global-agent/tasks/{task_id}/run
• POST /global-agent/tasks/{task_id}/approve
• GET /global-agent/tasks
• GET /global-agent/tasks/{task_id}
• GET /global-agent/tasks/{task_id}/events

Guardian

• POST /guardian-agent/plans
• POST /guardian-agent/plans/{plan_id}/start
• POST /guardian-agent/plans/{plan_id}/stop
• GET /guardian-agent/plans
• GET /guardian-agent/plans/{plan_id}
• GET /guardian-agent/plans/{plan_id}/events

工具注册表

• GET /tools
• GET /tools/{capability}

---

工具能力

当前内置 16 个 capability：

Capability	说明	风险
check_service_status	检查服务运行状态	L1
cleanup_service_cache	清理服务缓存	L2
deploy_service	部署服务	L2
health_check	健康检查	L1
query_disk_usage	查询磁盘使用	L1
query_dns_lookup	DNS 查询	L1
query_environment_profile	环境配置查询	L1
query_firewall_status	防火墙状态	L1
query_memory_usage	查询内存使用	L1
query_package_info	包信息查询	L1
query_ports	端口查询	L1
query_process_list	进程列表	L1
query_routes	路由查询	L1
query_service_logs	服务日志查询	L1
restart_service	重启服务	L2
rollback_service	回滚服务	L2

治理元数据由每个 YAML 中的 governance 字段定义（风险级别、审批需求、执行模式、标签）。

---

安全与治理模型

策略引擎位于 policies/*.rego，核心机制：

• 黑名单拒绝 — 高危目标直接 deny
• 审批门禁 — L2 默认审批，多主机 destructive 自动加强
• 并发控制 — 高风险任务强制顺序执行
• dry-run 强制 — 生产环境或 destructive 多主机场景自动要求

典型流程

1. Core 根据 intent/argv 生成 capability + 参数
2. 向 policy 发起评估
3. 根据 policy 决策执行 / 拒绝 / 等待审批
4. Exec 按 host 返回结构化结果

---

仓库结构

osagent/
├── cmd/
│   ├── exec/                  # Go 执行服务
│   ├── policy/                # Go 策略服务
│   └── tui/                   # Go TUI 客户端
├── services/
│   └── core/                  # Python FastAPI 编排服务
├── apps/
│   └── client/                # Tauri + React 桌面客户端
├── tools/                     # YAML 工具注册表（16 个能力）
├── policies/                  # Rego 策略
├── scripts/
│   ├── dev-up.sh              # 启动 policy/exec/core
│   ├── dev-down.sh            # 停止服务并清理
│   ├── local-first-test.sh    # 本地链路验证
│   └── test-streaming.sh      # SSE/流式测试
├── docs/
│   └── demo/materials_bundle/ # demo 与证据采集脚本
├── proto/                     # 协议定义
├── ADR/                       # 架构决策记录
└── README.md                  # 本文件

---

测试与验证

后端链路冒烟

./scripts/local-first-test.sh

流式接口验证

./scripts/test-streaming.sh

Go 测试

go test ./...

前端测试

cd apps/client
npm test

---

配置说明

重点配置参考：

• services/core/CONFIG.md
• docs/demo/materials_bundle/config/osagent-demo.env.example

常用变量：

变量	说明
KIMI_API_KEY	Kimi API 密钥
KIMI_BASE_URL	Kimi API 基础 URL
KIMI_MODEL	模型名称，如 kimi-k2.5
KIMI_MAX_CONCURRENT	LLM 最大并发
OSAGENT_PLAN_MAX_CONCURRENT	计划最大并发
OSAGENT_EXEC_MAX_CONCURRENT	执行最大并发
OSAGENT_INTENT_DEDUPE_ENABLED	意图去重开关
OSAGENT_INTENT_DEDUPE_WAIT_SECONDS	去重等待秒数

---

当前约束与注意事项

• osagent-core 当前启动逻辑固定从 ~/dev/ttyd/tools 加载工具目录。
• TUI 中 --core-socket 参数目前未实际参与 HTTP 请求路由，core 默认仍走 127.0.0.1:18080。
• 客户端中嵌入式 TUI 引导命令存在本地路径假设（见 apps/client/src/osagent/EmbeddedTuiTerminal.tsx）。
• 策略和工具模板可扩展，但生产落地前建议补全审计、发布流程和回滚保护测试。

---

参考文档

• ADR/：架构决策记录
• INTEGRATION_TEST_REPORT.md：集成测试结果
• LOCAL_AGENT_BENCHMARK_REQUIREMENTS.md：本地 agent 行为基准
• docs/demo/materials_bundle/：Demo 复现与证据采集

---

许可证

MIT License

有问题？欢迎提交 Issue 或联系维护者。