Skip to content

RollingTheRock/osagent

BranchesTags

Repository files navigation

osagent

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

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

  • 运维操作的可解释执行（preview -> policy -> execute）
  • 危险命令的分级防护（deny / needs_approval / dry-run 强制）
  • 多主机批量执行与任务化流程（global-agent / guardian-agent）
  • 可扩展工具注册表（YAML capability）

核心能力

  • 自然语言到运维动作：/intent、/intent/preview、SSE 流式输出
  • 直接命令治理执行：/command/preview、/command/execute
  • 策略引擎（OPA + Rego）：热更新、风险等级、审批和并发控制
  • 执行引擎（Go）：本地/SSH 执行、连接池、host-pinned worker
  • 任务编排：
    • Global Agent：按工作流计划 -> 运行 -> 审批 -> 完成
    • Guardian Agent：周期健康巡检和守护计划
  • 多入口：
    • Bubble Tea TUI（cmd/tui）
    • FastAPI 服务（services/core）
    • Tauri + React 桌面客户端（apps/client）

系统架构

[TUI / Client / curl]
         |
         v
   osagent-core (FastAPI, Python)
      |                 |
      | policy eval     | exec request
      v                 v
osagent-policy (Go)   osagent-exec (Go)
   Rego/OPA             Local/SSH command execution

组件职责：

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

仓库结构

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

快速开始（后端 + TUI）

1) 前置依赖

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

2) 启动服务

在仓库根目录执行：

./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/

3) 健康检查

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

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

4) 配置 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"}'

5) 启动 TUI

/tmp/osagent-tui

常用输入范式：

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

6) 停止服务

./scripts/dev-down.sh

桌面客户端（apps/client）

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}

工具能力（tools）

当前内置 16 个 capability：

  • check_service_status
  • cleanup_service_cache
  • deploy_service
  • health_check
  • query_disk_usage
  • query_dns_lookup
  • query_environment_profile
  • query_firewall_status
  • query_memory_usage
  • query_package_info
  • query_ports
  • query_process_list
  • query_routes
  • query_service_logs
  • restart_service
  • rollback_service

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

安全与治理模型

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

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

典型流程：

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

测试与验证

后端链路冒烟：

./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_BASE_URL
  • KIMI_MODEL
  • KIMI_MAX_CONCURRENT
  • 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 复现与证据采集

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages