内容
# OMP 实例
[Русская версия](README.ru.md)
用于运行 [Oh My Pi](https://omp.sh/) 进程的本地 MCP 控制平面。
当多个 OMP 会话正在运行时，其中一个会话需要发现、检查、消息、终止、重命名或停止另一个会话时使用。通过用户专属的 Unix 套接字在本地机器上进行通信。
无浏览器 UI。无 TCP 服务器。
## 安装
```sh
curl -fsSL https://raw.githubusercontent.com/DKeken/omp-instances-control-plane/main/install.sh | sh
```
安装后重启正在运行的 OMP 进程。
安装程序是幂等的。重新运行相同的命令会更新安装并保留无关的 MCP 服务器。
### 安装程序更改
- 将存储库安装到 `~/.local/share/omp-instances-control-plane`。
- 为 MCP 服务器安装锁定版本的 Bun 依赖项。
- 备份现有的 `omp-control.ts`、`omp-control.js` 和 `mcp.json` 到 `~/.omp/agent/backups`。
- 安装一个运行时扩展符号链接：`~/.omp/agent/extensions/omp-control.ts`。
- 仅将 `mcpServers["omp-instances"]` 合并到 `~/.omp/agent/mcp.json`。
在运行远程脚本之前查看：
```sh
curl -fsSL https://raw.githubusercontent.com/DKeken/omp-instances-control-plane/main/install.sh -o install.sh
cat install.sh
sh install.sh
```
## 可用工具
| 工具 | 用途 |
| --- | --- |
| `list` | 列出正在运行的 OMP 进程、别名、PID、会话、模型、工作目录和空闲/忙碌状态。 |
| `inspect` | 读取一个进程的当前元数据。 |
| `send` | 向一个 OMP 进程发送消息。 |
| `ask` | 发送相关请求并等待明确的 `reply`。 |
| `reply` | 完成一个待处理的相关请求。 |
| `broadcast` | 向所有可达的 OMP 进程发送一条消息。 |
| `rename` | 为一个进程分配一个可读的别名。 |
| `doctor` | 诊断权限、过时的套接字、重复的别名和过时的回复文件。 |
| `interrupt` | 终止当前模型/工具操作而不退出 OMP。 |
| `shutdown` | 正常停止一个 OMP 进程。 |
目标接受确切的别名、PID、实例 ID、会话 ID 或明确的实例/会话 ID 前缀。
## 工作原理
```mermaid
flowchart LR
A[OMP 进程 A] -->|0600 记录 + Unix 套接字| R[(0700 本地注册表)]
B[OMP 进程 B] -->|0600 记录 + Unix 套接字| R
M[MCP 服务器] -->|发现和验证| R
M -->|类型本地请求| A
M -->|类型本地请求| B
```
每个 OMP 进程加载 `omp-control.ts`。运行时扩展：
1. 创建随机实例 ID；
2. 将进程元数据写入本地注册表；
3. 监听私有 Unix 套接字；
4. 每五秒刷新状态；
5. 在正常关闭期间删除记录和套接字。
MCP 服务器将注册表文件视为发现元数据，而不是权限。在执行操作之前，它会检查进程活动状态并联系目标套接字。
## 配置
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `OMP_INSTANCES_HOME` | `$XDG_DATA_HOME/omp-instances-control-plane` 或 `~/.local/share/omp-instances-control-plane` | 安装存储库位置。 |
| `OMP_HOME` | `~/.omp/agent` | OMP 代理配置目录。 |
| `OMP_MCP_CONFIG` | `$OMP_HOME/mcp.json` | MCP 配置文件。 |
| `OMP_INSTANCES_REF` | `main` | 脚本安装的存储库分支。 |
| `OMP_CONTROL_DIR` | `/tmp/omp-control-<uid>` | 共享运行时注册表和套接字目录。必须对每个进程都相同。 |
| `OMP_INSTANCE_NAME` | `<cwd-name>-<pid>` | 一个 OMP 进程的初始别名。 |
便携式自定义安装示例：
```sh
curl -fsSL https://raw.githubusercontent.com/DKeken/omp-instances-control-plane/main/install.sh | \
OMP_INSTANCES_HOME="$HOME/tools/omp-instances" sh
```
`OMP_INSTANCES_HOME` 是失败关闭的，因为安装程序会存档、交换并可能在回滚期间删除此目录。它必须是一个专用路径。安装程序拒绝文件系统根目录、`HOME`、`OMP_HOME`、它们的祖先、`OMP_HOME` 内的路径、符号链接目标以及 `package.json#name` 不是 `omp-instances-control-plane` 的现有目录。`OMP_MCP_CONFIG` 不能位于安装根目录内。
## 更新
再次运行安装命令。安装程序在更改活动文件之前准备源代码、锁定依赖项和合并的 MCP 配置。然后，它会存档以前的安装并激活存储库、扩展符号链接和 MCP 配置，作为回滚支持的交易。任何激活错误都会恢复以前的状态。
重启 OMP 进程，以便它们加载新的运行时扩展和 MCP 配置。
## 回滚和卸载
备份存储在 `~/.omp/agent/backups` 中，每个安装都有一个时间戳。
要回滚升级，请停止 OMP 进程并恢复匹配的存储库和 MCP 备份：
```sh
rm -rf ~/.local/share/omp-instances-control-plane
tar -xzf ~/.omp/agent/backups/omp-instances-control-plane.<timestamp>.tar.gz \
-C ~/.local/share
cp ~/.omp/agent/backups/mcp.json.<timestamp>.bak ~/.omp/agent/mcp.json
```
已安装的扩展符号链接指向稳定的安装路径，因此恢复的存储库会自动提供以前的运行时。重启 OMP 进程后回滚。
如果 `OMP_INSTANCES_HOME`、`OMP_HOME` 或 `OMP_MCP_CONFIG` 已自定义，请使用这些路径。
对于首次安装卸载，请停止 OMP 进程，删除 `~/.omp/agent/extensions/omp-control.ts`，仅从 MCP 配置中删除 `mcpServers["omp-instances"]`，然后删除安装目录。
## 安全
- 注册表目录：`0700`。
- 记录和套接字：`0600`。
- 备份目录和扩展备份目录：`0700`。
- MCP 配置备份、安装存档和复制的扩展备份：`0600`。
- 传输：仅本地 Unix 套接字。
- 请求和响应帧大小有限。
- 没有通用 shell 执行、文件 API、HTTP 端点、剪贴板 API 或原始 PTY 注入。
- 相同用户进程保持在信任边界内。该项目不会隔离在同一 OS 帐户下运行的相互敌对的进程。
有关漏洞报告，请参阅 [SECURITY.md](SECURITY.md)。
## 故障排除
### 没有实例出现
安装后重启 OMP 进程。确认 `~/.omp/agent/extensions/omp-control.ts` 指向已安装的存储库，并且每个进程都使用相同的 `OMP_CONTROL_DIR`。
### 目标不明确
使用 `list` 返回的完整 `instanceId`。
### 权限或过时套接字错误
使用 `doctor` 且 `fix: true`。它修复注册表权限和过时文件；它不会终止正在运行的进程。
### MCP 服务器未加载
检查 `~/.omp/agent/mcp.json` 条目，并确保配置的 Bun 路径仍然存在。安装程序存储绝对的 Bun 可执行文件和安装路径。
### 套接字路径太长
为每个进程使用更短的注册表路径：
```sh
export OMP_CONTROL_DIR=/tmp/oc
```
## 开发
```sh
bun install
bun run check
```
存储库布局：
- `packages/mcp-server`：MCP 服务器和共享本地协议。
- `packages/omp-extension`：OMP 运行时扩展源代码。
- `install.sh`：幂等安装程序和升级路径。
- `skills/omp-orchestration`：可选代理/操作员参考。
## 许可证
存储库是公开的，但不是开源的。没有提供许可证授予。所有权利保留。
