xiaobei-harmony-mcp 0.0.0-stage → 1.0.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aoqi Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# 小贝鸿蒙 MCP 电脑连接组件
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+让电脑上的 AI 客户端通过局域网操作鸿蒙手机。电脑端使用 stdio 连接本组件，本组件连接手机上的小贝。
+
+手机需要安装小贝、登录账号、具备 AI 功能会员权益，并按 App 指引完成手机设置。电脑需要 Node.js 18 或更新版本，以及支持本地 stdio MCP 的 AI 客户端。电脑与手机必须处于可互通的局域网，无需 USB 数据线。
+
+## 连接小贝
+
+打开 [小贝接入指引](https://mcp.aoqi360.com)，选择你使用的 AI 客户端，按页面指引配置。支持执行本机命令的 AI 可阅读 [接入教程](https://mcp.aoqi360.com/autoclicker/llms.txt) 帮你完成配置；其他客户端通过自身的 MCP 设置导入配置。
+
+需要手动生成配置时，运行：
+
+```sh
+npx -y xiaobei-harmony-mcp config --client=cursor
+```
+
+将 `cursor` 换成目标客户端标识，例如 `codex`。命令只输出配置，不创建配对。输出中的 `XIAOBEI_MCP_INSTANCE_ID` 已生成，保存后保持不变。将输出导入该客户端对应的 MCP 设置，不要把 JSON 直接写入 Codex 的 TOML 配置文件。
+
+其他电脑 AI 可使用 `--client=other`。在生成配置的 `env` 中设置 `XIAOBEI_MCP_CLIENT_NAME`，填写客户端名称。名称用于手机确认和后台展示，不是客户端身份认证。
+
+1. 在 AI 客户端启用小贝 MCP。客户端启动连接组件后，电脑打开扫码页面。
+2. 在手机小贝的「AI 连接」扫码或输入配对码，核对客户端和电脑名称，允许连接。
+3. 保持小贝和电脑 AI 开启，等待电脑保存配对并检查局域网连接。
+4. 回到 AI 客户端发送：**用小贝检查一下手机连接。** 检查成功后，说出你想完成的任务。
+
+若安装后没有打开扫码页，在同一个 AI 客户端发送“帮我继续连接小贝”。AI 可调用 `xiaobei_get_connection_status({connect:true})` 接续连接。若客户端尚未加载新增 MCP 配置，先使用该客户端的重新加载功能。
+
+### Windows 启动配置
+
+部分 Windows 客户端不能直接启动 `npx`。这种情况下，将生成配置的启动字段改为下面的形式，保留原有 `env` 和实例 ID：
+
+```json
+{
+	"command": "cmd",
+	"args": ["/c", "npx", "-y", "xiaobei-harmony-mcp"]
+}
+```
+
+电脑需要已安装 Node.js，且客户端进程能够找到 `npx`。具体配置位置按所用 AI 客户端的说明操作。此启动方式尚未完成 Windows 真机端到端验收。
+
+## 配对过期或中途退出
+
+二维码有效期为 **10 分钟**。未授权申请到期后停止轮询，网页不会创建或刷新电脑端配对申请。
+
+重新打开原 AI 客户端，发送：
+
+> 帮我继续连接小贝。
+
+`xiaobei_get_connection_status({connect:true})` 会重新打开仍有效的扫码页；后端确认未授权申请已过期时，创建新的申请。保留现有配置和实例 ID，无需重装或清理配对文件。手机已经批准但电脑保存或验证失败时，会保留原申请并提示后续操作，不自动覆盖授权。
+
+## 切换已授权的 AI
+
+同一个 npm 包可以给多个客户端使用。每个客户端配置必须有独立的 `XIAOBEI_MCP_INSTANCE_ID`，各自保存凭据，不要把同一份实例配置复制给其他 AI。
+
+手机保留多个已授权客户端，同一时间只启用一个。在小贝的「AI 连接」选择并确认切换，然后回到目标 AI 检查连接。每个配对有独立 Token，正常切换不轮换 Token，无需重新扫码。新客户端首次使用仍需配置和手机授权。
+
+仅在授权已移除或永久失效、需要重新授权时，按接入教程在原配置身份下执行：
+
+```sh
+npx -y xiaobei-harmony-mcp reconnect --client=cursor --instance=原配置中的实例ID
+```
+
+命令返回 `queued: true` 表示重新连接请求已保存，不表示手机授权完成。随后在原 AI 客户端调用 `xiaobei_get_connection_status({connect:true})`，按手机提示确认。正常切换、IP 变化或临时断网不需要执行 `reconnect`。
+
+## 工具列表与连接状态
+
+手机提供自动化工具列表，连接组件负责获取和缓存。首次没有配对或目录缓存时，仅提供电脑侧工具 `xiaobei_get_connection_status`。配对完成后，连接组件获取手机 `tools/list`，并发送 `notifications/tools/list_changed` 通知客户端更新工具。
+
+客户端不支持动态刷新时，需要重新加载 MCP 连接，无需重新扫码。之后手机新增工具可通过目录刷新被发现，无需为了增加工具名称而更新本组件。缓存目录不代表手机当前在线、会员有效或手机设置已完成。
+
+连接状态工具支持以下参数：
+
+- `{}`：读取本地状态，不探测手机、不发起配对。
+- `{"probe":true}`：对已有配对做有限的只读局域网检查，不打开网页、不新建配对。
+- `{"connect":true}`：明确接续连接；需要配对时打开扫码页。
+
+连接组件空闲时每 60 秒通过局域网发送一次认证 ping。近期成功的工具请求可替代 ping，不调用截图或执行引擎。电脑休眠、客户端关闭和系统网络限制可能中断检测，不保证永久在线。
+
+## 处理连接问题
+
+- **局域网不通**：打开手机小贝，检查双方网络、服务开关和电脑的本地网络权限，再让 AI 检查连接。手机 IP 变化时，组件可凭原配对查询最新地址，无需重新扫码。
+- **手机已接收请求，但结果超时或断开**：返回 `MCP_RESPONSE_UNKNOWN`。先打开小贝恢复前台，再观察目标页面核对结果。操作可能已经执行，不要直接重做。网络超时不能证明手机被系统冻结。
+- **客户端未启用**：返回 `MCP_CLIENT_INACTIVE`。在小贝切换到目标 AI，再重试，无需重新扫码。
+- **登录或会员异常**：在手机处理账号或权益后，用原配对检查连接。
+- **实例正在使用**：返回 `MCP_INSTANCE_BUSY`，本次操作尚未发送。等待正在执行的调用结束后检查连接；持续出现时检查重复连接或重启当前客户端的小贝 MCP，不要删除活进程的锁文件。
+
+普通工具请求的响应上限为 65 秒。桥接器不会自动重发结果未知的手机操作，也不会因为临时网络错误自动弹出新的扫码页。AI 客户端收到错误后，可根据返回的错误码、执行状态和下一步建议继续处理。
+
+完成任务时，AI 应先核对业务结果，再调用 `mobile_return_to_xiaobei` 返回小贝。该工具用于减少后台挂起风险，不代表业务任务成功，也不能唤醒已冻结的服务。用户要求停留目标页面，或仍在等待验证码、登录等操作时，保留该页面。
+
+## 数据与连接范围
+
+- 后台 API 默认使用 `https://api.aoqi360.com`，负责配对、授权及最新地址查询；配对网页使用 `https://mcp.aoqi360.com`。
+- 手机操作只通过局域网发送，接受私有 IPv4 的 `http://手机地址:端口/mcp`。不经云端转发手机截图和控件树，不使用 USB 回环兜底。
+- 连接组件只接收 AI 客户端发送的 MCP 请求，不能读取整段聊天记录。截图和控件树返回 AI 客户端后，可能由该客户端发送到模型服务。
+- 凭据分别保存在 `~/.xiaobei/clients/<clientId>/<instanceId>/<appId>/<hubHash>/session.json`，不要分享或提交这些文件。支持 POSIX 权限的平台使用目录 `0700`、文件 `0600`；Windows 文件访问由系统 ACL 管理。
+- 配对凭据不放入浏览器 URL，不打印到 CLI 或 MCP 错误。旧共享文件 `~/.xiaobei/mcp-session.json` 不自动导入或复制。
+
+## 许可证
+
+本组件采用 [MIT 许可证](LICENSE)。