# lspo

**Repository Path**: liyanda/lspo

## Basic Information

- **Project Name**: lspo
- **Description**: 面向 Linux 系统管理场景的智能体编排与控制服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-24
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LSPO

**LSPO（Linux System Policy Orchestrator）** 是面向 Linux 桌面系统管理场景的智能体
服务。用户通过自然语言与 Agent 对话，完成系统状态查询、策略分析和受控操作编排。

## 功能

- 支持 CLI 和本地 D-Bus 两种交互入口。
- 支持调用远程 OpenAI-compatible LLM，例如 vLLM。
- 支持查询系统摘要、CPU、内存、网络、磁盘、进程、硬件、服务、安全状态和电源信息。
- 支持 MCP Tool 动态发现，并自动同步为 Agent Skill。
- 支持 Skill 白名单、Pydantic 参数校验和风险等级控制。
- 支持高风险操作的用户确认、拒绝和超时处理。
- 支持 SQLite 会话状态持久化。
- 提供临时 Qt/D-Bus 调试客户端。
- 提供 Debian 安装包和用户级 systemd 服务配置。
- 提供可选的 SystemBus 特权 Helper 样板，支持白名单 systemd 服务重启、
  Polkit 授权和 JSONL 审计。

## 工作原理

```text
CLI / Qt / 其他 D-Bus 客户端
              |
              v
        D-Bus SessionBus
              |
              v
        LSPO AgentService
              |
              v
          LangGraph
       /      |       \
   LLM    确认流程    Skill执行
                         |
                         v
                 MCP Client stdio
                         |
                         v
                    lspo_mcp
                         |
                         v
                  Linux 系统适配器
```

1. 客户端把用户消息发送给 Agent。
2. Agent 将消息和当前 Skill 清单交给远程 LLM。
3. LLM 返回最终回答，或返回一个结构化 `tool_call`。
4. Agent 校验 Skill 和参数，需要时暂停等待用户确认。
5. MCP Client 调用本机 MCP Tool，读取 Linux 状态并返回结构化结果。
6. LangGraph 将结果交回 LLM，生成最终回答，并保存会话 checkpoint。

D-Bus 只负责客户端与 Agent 的本地通信；MCP 由 Agent 通过 stdio 直接连接，不经过
D-Bus。

系统级写操作默认关闭。启用特权 Helper 后，写操作链路为：

```text
MCP Server -> D-Bus SystemBus -> Privileged Helper -> Polkit -> systemctl
```

Helper 只接受固定的业务接口和允许列表中的 `.service` 单元，不提供任意 Shell
执行能力。

快速了解整体模块、调用链和代码阅读顺序，见 `PROJECT_OVERVIEW.md`。
详细的模块职责、状态图、权限回路和扩展方式见 `ARCHITECTURE.md`。

## 快速运行

### 环境准备

要求 Python `>= 3.11`。如果需要运行 D-Bus 服务，Ubuntu 还需要系统 D-Bus 和 GLib
Python 模块：

```bash
sudo apt install python3 python3-venv python3-pip python3-dbus python3-gi \
  gir1.2-glib-2.0 dbus-user-session

python3 -m venv --system-site-packages .venv-hf
.venv-hf/bin/python -m pip install -e ".[test]"
```

编辑 `configs/agent.yaml`，至少修改：

```yaml
llm:
  base_url: "http://127.0.0.1:8000/v1"
  model: "your-model"
```

### CLI Mock 模式

Mock 模式只模拟 Skill 执行，不会修改真实系统：

```bash
.venv-hf/bin/lspo --config configs/agent.yaml
```

### CLI MCP 模式

启用真实只读 Linux MCP Tool：

```bash
LSPO_SKILL_MODE=mcp .venv-hf/bin/lspo --config configs/agent.yaml
```

### D-Bus 服务

启动 Agent 服务：

```bash
LSPO_SKILL_MODE=mcp \
.venv-hf/bin/lspo --config configs/agent.yaml --transport dbus
```

服务标识：

```text
Bus name:    org.lspo.Control
Object path: /org/lspo/Control
Interface:   org.lspo.Control1
```

检查服务：

```bash
gdbus introspect --session \
  --dest org.lspo.Control \
  --object-path /org/lspo/Control
```

D-Bus 主要方法包括 `Chat`、`ResumeConfirmation`、`CancelTask`、`GetSession` 和
`ResetSession`。

### Qt 调试客户端

```bash
.venv-hf/bin/python -m pip install -e ".[client]"
.venv-hf/bin/lspo --transport dbus
.venv-hf/bin/lspo-debug-client
```

## Debian 部署

构建 Debian 安装包：

```bash
sudo apt install python3 python3-venv python3-pip python3-setuptools \
  python3-wheel dpkg-dev build-essential
./packaging/deb/build-deb.sh
```

构建结果：

```text
dist/lspo_0.1.0_amd64.deb
```

安装并启动用户级服务：

```bash
sudo apt install python3-dbus python3-gi gir1.2-glib-2.0 dbus-user-session systemd
sudo apt install ./dist/lspo_0.1.0_amd64.deb
sudoedit /etc/lspo/agent.yaml
lspo-enable
```

查看日志：

```bash
journalctl --user -u lspo.service -f
```

停止服务：

```bash
systemctl --user disable --now lspo.service
```

当前 Debian 方案采用用户级 systemd、D-Bus `SessionBus` 和非 root Agent，适合有桌面
会话的 Ubuntu 主机。`lspo-enable` 必须由桌面用户执行，不要使用 `sudo`。

系统级特权 Helper 是可选组件，默认不启动。需要启用时，先在
`/etc/lspo/privileged.yaml` 配置 `allowed_services`，再启用 Agent 配置中的
`system_restart_service` 策略，最后执行：

```bash
sudo lspo-privileged-enable
```

Helper 使用 D-Bus `SystemBus`、Polkit 和固定参数的 `systemctl` 调用，审计记录默认
写入 `/var/log/lspo/helper-audit.jsonl`。当前示例操作“重启服务”明确标记为不可回滚。

## 配置和状态

常用环境变量：

| 变量 | 作用 |
| --- | --- |
| `LSPO_BASE_URL` | 覆盖远程 LLM 地址 |
| `LSPO_MODEL` | 覆盖模型名称 |
| `LSPO_SKILL_MODE` | 设置 `mock` 或 `mcp` |
| `LSPO_PERSISTENCE_BACKEND` | 设置 `sqlite` 或 `memory` |
| `LSPO_PERSISTENCE_PATH` | 覆盖 checkpoint 路径 |

默认 checkpoint 文件为 `.agent_state/checkpoints.sqlite3`。Debian 服务使用当前用户的
`~/.local/state/lspo/.agent_state/checkpoints.sqlite3`。

## 测试

```bash
.venv-hf/bin/python -m pytest -q
```