Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -376,15 +376,15 @@ off set 客厅吸顶灯 2/1 = false
<tr>
<td rowspan="3">连接</td>
<td><code>mijia_auth</code></td>
<td>连接米家网关(需 6 位一次性登录码;已连接时无需再次认证)</td>
<td>连接米家网关(需 6 位一次性登录码;已连接时无需再次认证。<code>reconnect=true</code> 更换网关或重新登录,新连接成功后才替换原连接)</td>
</tr>
<tr>
<td><code>mijia_disconnect</code></td>
<td>断开网关连接</td>
<td>断开网关连接(共享连接下所有客户端都会断开,需要新的登录码才能重连)</td>
</tr>
<tr>
<td><code>mijia_status</code></td>
<td>检查连接状态</td>
<td>检查连接状态(<code>verify=true</code> 实际询问网关一次,确认连接可用)</td>
</tr>
<tr>
<td rowspan="3">设备</td>
Expand Down
120 changes: 120 additions & 0 deletions docs/one-command-setup-plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
# 一条命令安装与管理:实施计划

状态:已确认方案,按三个阶段实施。第 1 阶段进行中。

## 1. 目标

把现在「先选部署方式、再改配置、再装 Skill」的安装过程,收敛为一条命令加一个三步向导:

```bash
npx -y oh-my-sage-mcp@latest setup
```

- 首次运行进入安装向导:选服务位置 → 连网关 → 接入 AI Agent。
- 之后运行进入管理菜单:网关登录与验证、AI Agent 接入、更新、高级设置、卸载。
- NAS 用户在 NAS 上用一条 `docker run` 起服务,再在电脑上用同一条命令接入。
- 用户需要提供的只有三样:网关 IP、6 位登录码、要接入哪些 AI Agent。

## 2. 已确定的设计决策

| 决策 | 原因 |
|---|---|
| 菜单入口是显式子命令 `setup`,不根据「是否在终端」自动切换 | `oh-my-sage-mcp` 是现有客户端的 MCP 启动命令,不能改变其行为 |
| 向导只装本机常驻服务;按需启动(stdio)保留为手动高级用法 | 菜单管不到 AI Agent 自己拉起的 stdio 进程 |
| 本机服务装在用户目录,不用 `npm install -g`,不要管理员权限 | 后台服务需要稳定路径;全局目录在部分系统需要 sudo |
| 本机服务也自动生成访问密钥并写入客户端配置 | 管理操作经过 HTTP,本机其他程序也能访问回环地址 |
| 菜单是一个带访问密钥的 MCP 客户端,调用服务现有工具 | 本机与 NAS 服务用同一套逻辑,不另造管理接口 |
| 登录码不保存、不记日志;保存网关地址 | 登录码一次性,协议层无法续期(见 `src/core/gateway/client.ts` `authenticate`) |
| Skill 随 npm 包下发同版本文件,向导和更新时一起安装 | `npx skills add allocnode/oh-my-sage` 取的是 GitHub main,可能和服务版本不一致 |
| 写入客户端配置时记录清单,只修改或移除本工具写入的内容 | 改密钥后同步、卸载时都需要知道写过哪里 |
| 换网关、重新登录必须「新连接成功后才替换旧连接」 | 共享服务里,失败的重新登录不能连带断掉所有客户端 |
| 更新默认「下次登录生效」,可选「立即重启」 | 立即重启会断开网关、要新的登录码 |
| 兼容 0.1.x:保留 `GATEWAY_URL` 与 stdio 方式;向导发现旧计划任务或旧配置时提供接管 | 已有用户按旧文档安装 |

## 3. 不做的事

- 不自动扫描局域网找网关(未验证可行性,且电脑上扫到不代表 NAS 能连到)。
- 不在电脑上的菜单里远程部署、升级 NAS 上的 Docker。
- 不把网页版并入向导。
- 不承诺网关登录长期有效或自动续登。

## 4. 第 1 阶段:修复共享连接的安全问题(发布 0.1.2)

不改用法,只修现有缺陷。NAS 上的常驻服务也直接受益。

| # | 问题 | 位置 | 改法 | 完成标准 |
|---|---|---|---|---|
| 1.1 | 重新登录时先关旧连接,新连接失败后所有客户端掉线 | `src/core/gateway/manager.ts` `connect()` | 新建客户端并认证成功后再替换,旧连接随后关闭;失败时关闭新客户端、保留旧连接 | 单元测试:新登录失败后 `isConnected()` 仍为 true 且仍是旧客户端 |
| 1.2 | 并发登录互相覆盖 | 同上 | `connect()` 串行化,后到的请求等前一个完成 | 单元测试:两次并发登录按顺序执行,结束后只有最后成功的那个连接存活 |
| 1.3 | 工具说明建议 AI 用完断开、重新登录先断开 | `src/mcp/tools/auth.ts` | 删除「建议在完成所有操作后调用」;`mijia_disconnect` 写明会断开所有客户端且登录码作废;`mijia_auth` 增加 `reconnect` 参数用于已连接时更换网关或重新登录,提示不再要求先断开 | 说明文本不再出现上述建议;已有 HTTP 测试通过 |
| 1.4 | 无法真实验证连接(只看本地标志,设备表有 30 秒缓存) | `manager.ts`、`mijia_status` | 管理器增加 `verify()`,绕过缓存向网关发一次轻量只读请求(`getVarScopeList`,实测约 23 ms、224 字节);`mijia_status` 增加可选 `verify` 参数,返回是否响应与耗时 | 单元测试覆盖响应、超时、未连接三种结果 |

验证(本地只做无副作用检查,行为测试由 CI 与 Alex 执行):

```bash
npm run lint
npx tsc --noEmit -p tsconfig.mcp.json
npx tsc --noEmit
```

CI 运行单元测试与打包冒烟测试。合并后按发版流程打 `v0.1.2`。

## 5. 第 2 阶段:服务端支撑与 setup 向导(发布 0.2.0)

### 5.1 服务端

- **状态目录**:`MCP_STATE_DIR`,默认 Windows `%LOCALAPPDATA%\oh-my-sage`,macOS `~/Library/Application Support/oh-my-sage`,Linux `${XDG_STATE_HOME:-~/.local/state}/oh-my-sage`,Docker `/data`。
- **保存网关地址**:`mijia_auth` 成功后把地址写入 `state.json`。地址优先级:本次参数 > 已保存 > `GATEWAY_URL`。
- **Docker**:`docker-compose.yml` 挂载数据卷到 `/data`;Dockerfile 设 `MCP_STATE_DIR=/data`。
- **规则草稿**:`src/mcp/tools/graphDraft.ts` 默认路径从系统临时目录移到状态目录(评估后决定,避免两个进程共用同一份临时文件的旧问题回归)。

### 5.2 npm 包

- `scripts/build-npm-package.mjs` 把 `.agents/skills/mijia-automation` 复制进包。
- 新增依赖评估:交互界面库(候选 `@clack/prompts`),以体积和 Windows 终端兼容性为准。

### 5.3 setup 命令(新文件 `src/mcp/setup/`)

```
首次运行
├─ 1. 服务:本机常驻 / 连接已有服务(地址 + 访问密钥,当场验证身份与版本)
├─ 2. 网关:输入地址 → 由服务所在机器测试 → 6 位登录码 → 验证并保存(可跳过)
└─ 3. AI Agent:用户勾选 → 写 MCP 配置 + 装同版本 Skill → 不支持的给出完整配置
完成页分别显示:服务 / 网关 / 客户端 状态

之后运行
顶部:服务状态 · 网关状态(附上次验证时间)· 已接入客户端
├─ 1. 网关:输入新登录码 / 验证连接 / 更换网关(新连接成功才替换)
├─ 2. AI Agent:添加 / 检查修复 / 移除(只动本工具写入的)/ 显示手动配置
├─ 3. 更新:下次登录生效(默认)/ 立即重启(需新登录码)
├─ 4. 高级:启停服务 / 改端口或密钥(同步各客户端)/ 查看日志(脱敏)/ 切换服务
├─ 5. 卸载或解除接入(先列清单再执行;远程服务只解除本机接入)
└─ 0. 退出(服务继续运行)
```

关键行为:

- 本机安装:`npm install --prefix <状态目录>/app oh-my-sage-mcp@<版本>`,后台服务指向该目录,复用 `deploy/install-local.*` 注册服务。
- 某步失败只重试该步,已完成部分保留。
- 已登录时不因打开菜单或重复安装而重新认证。
- 写配置清单保存在状态目录 `clients.json`:客户端、文件路径、写入的键、Skill 路径。
- 迁移:发现 `oh-my-sage-mcp` 计划任务 / launchd / systemd 服务或客户端里的 stdio 配置时,提示接管,不另装一份。

### 5.4 动手前要核实的事

- [ ] `add-mcp` 写入带注释的配置文件(JSONC)时是否保留注释与其他项;是否支持 HTTP `headers`。不满足就自己按客户端写。
- [ ] 各客户端 Skill 目录,以及 `npx skills add <本地路径>` 是否可用。
- [ ] 腾讯 WorkBuddy、TRAE、Qoder、通义灵码的 MCP 配置文件位置。
- [ ] 网关登录能保持多久(需在真实网关上观察,不能主动断开现有连接)。

## 6. 第 3 阶段:Docker 镜像与 README(随 0.2.0)

- `release.yml` 增加构建并推送镜像到 GHCR(`ghcr.io/allocnode/oh-my-sage-mcp`)。
- 首次推送后镜像可能默认私有,需要仓库所有者在 GitHub 上改为公开(未验证)。
- README「快速开始」缩成:电脑一条 `npx … setup`;NAS 一条 `docker run`。参数、手动配置、stdio 方式移到 `deploy/README.md`。

## 7. 边界与风险

- 发版到 npm、推送镜像、合并到 upstream 都是对外操作,每个阶段合并前确认。
- 不在真实网关上调用 `mijia_disconnect`,不触发设备。
- 在真实网关上的行为验证(重新登录、连接保持时长)由 Alex 安排,开发过程只用替身测试。
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "oh-my-sage",
"version": "0.1.1",
"version": "0.1.2",
"private": true,

"scripts": {
Expand Down
133 changes: 104 additions & 29 deletions src/core/gateway/manager.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
/**
* Core - Gateway 连接管理器
* 统一管理 Gateway 连接状态
*
* HTTP 常驻模式下所有客户端共享同一个管理器,因此:
* - 重新登录(换网关、换登录码)必须在新连接认证成功后才替换旧连接,
* 失败时保留旧连接,避免一次输错登录码让所有客户端一起掉线;
* - 登录请求串行执行,避免两个并发登录互相覆盖。
*/

import { GatewayClient } from './client';
Expand All @@ -19,61 +24,131 @@ async function warmUp(gateway: GatewayClient): Promise<void> {
}
}

/** 验证连接时使用的只读请求:返回体很小(实测约 200 字节、20 ms 级) */
export const VERIFY_METHOD = 'getVarScopeList';
export const VERIFY_TIMEOUT_MS = 5000;

export interface GatewayVerifyResult {
/** 本地记录的连接状态 */
connected: boolean;
/** 网关是否实际响应了只读请求;未连接时为 false */
responsive: boolean;
/** 请求耗时(毫秒),仅在发出请求时返回 */
latencyMs?: number;
/** 失败原因 */
error?: string;
}

/** 管理器使用的网关客户端最小接口,便于测试替换 */
export type GatewayClientLike = Pick<GatewayClient, 'connect' | 'authenticate' | 'close' | 'isConnected' | 'callApi'>;

export interface GatewayManagerOptions {
/** 创建网关客户端;默认 new GatewayClient(),测试时可替换 */
createClient?: () => GatewayClientLike;
/** 登录成功后是否后台预热设备表与 MIOT Spec,默认 true */
warmUp?: boolean;
}

export interface GatewayManager {
gateway: GatewayClient | null;
isConnected(): boolean;
/**
* 登录网关。已有连接时,新连接认证成功后才替换旧连接;失败时旧连接保持可用。
* 多次调用按顺序执行。
*/
connect(passcode: string, gatewayUrl?: string): Promise<void>;
disconnect(): Promise<void>;
ensureConnected(): void;
/** 向网关发一次轻量只读请求,确认连接确实可用(不读缓存、不重新登录) */
verify?(timeoutMs?: number): Promise<GatewayVerifyResult>;
}

export function createGatewayManager(): GatewayManager {
let gateway: GatewayClient | null = null;
export function createGatewayManager(options: GatewayManagerOptions = {}): GatewayManager {
const createClient = options.createClient ?? (() => new GatewayClient());
const shouldWarmUp = options.warmUp ?? true;
let gateway: GatewayClientLike | null = null;
// 登录队列:保证 connect() 串行执行
let queue: Promise<unknown> = Promise.resolve();

const closeQuietly = async (client: GatewayClientLike | null): Promise<void> => {
if (!client) return;
try {
await client.close();
} catch {
// 忽略关闭错误
}
};

const doConnect = async (passcode: string, gatewayUrl?: string): Promise<void> => {
const url = gatewayUrl || process.env.GATEWAY_URL;
if (!url) {
throw new Error('未配置网关地址:请在 mijia_auth 的 gateway_url 参数中提供网关地址,或在 MCP 配置里设置 GATEWAY_URL 环境变量');
}

const next = createClient();
try {
await next.connect(url);
await next.authenticate(passcode);
} catch (error) {
// 新连接失败:关闭它,旧连接(如果有)保持不变
await closeQuietly(next);
throw error;
}

const previous = gateway;
gateway = next;
await closeQuietly(previous);

// 后台预热:设备表与所有设备型号的 MIOT Spec(外网请求每个约数百毫秒)。
// 不等待、不影响登录结果,失败只是退回按需拉取。
if (shouldWarmUp && next instanceof GatewayClient) void warmUp(next);
};

return {
get gateway() {
return gateway;
return gateway as GatewayClient | null;
},

isConnected(): boolean {
return gateway !== null && gateway.isConnected();
},

async connect(passcode: string, gatewayUrl?: string): Promise<void> {
const url = gatewayUrl || process.env.GATEWAY_URL;
if (!url) {
throw new Error('未配置网关地址:请在 mijia_auth 的 gateway_url 参数中提供网关地址,或在 MCP 配置里设置 GATEWAY_URL 环境变量');
}

if (gateway) {
try {
await gateway.close();
} catch {
}
}

gateway = new GatewayClient();
await gateway.connect(url);
await gateway.authenticate(passcode);
// 后台预热:设备表与所有设备型号的 MIOT Spec(外网请求每个约数百毫秒)。
// 不等待、不影响登录结果,失败只是退回按需拉取。
void warmUp(gateway);
connect(passcode: string, gatewayUrl?: string): Promise<void> {
const run = queue.then(() => doConnect(passcode, gatewayUrl));
// 队列只关心顺序,不传播上一次的失败
queue = run.catch(() => undefined);
return run;
},

async disconnect(): Promise<void> {
if (gateway) {
try {
await gateway.close();
} catch {
}
gateway = null;
}
const current = gateway;
gateway = null;
await closeQuietly(current);
},

ensureConnected(): void {
if (!this.isConnected()) {
throw new Error('网关未连接,请先调用 mijia_auth');
}
},

async verify(timeoutMs: number = VERIFY_TIMEOUT_MS): Promise<GatewayVerifyResult> {
const current = gateway;
if (!current || !current.isConnected()) {
return { connected: false, responsive: false, error: '网关未连接' };
}
const started = Date.now();
try {
await current.callApi(VERIFY_METHOD, {}, timeoutMs);
return { connected: true, responsive: true, latencyMs: Date.now() - started };
} catch (error) {
return {
connected: current.isConnected(),
responsive: false,
latencyMs: Date.now() - started,
error: error instanceof Error ? error.message : String(error),
};
}
},
};
}
Loading
Loading