# 开发者集成文档

## 集成边界

`jimu-platform` 提供云端能力：账号、订阅、授权码、签名授权、MCP 浏览器实例编排。MCP 是开发者和 AI Agent 的主入口，可以生成启动参数、直接启动 `chrome.exe`，并在浏览器启动后继续通过 CDP / Control API 控制页面。

```text
开发者应用 / Cursor / AI Agent
  -> 获取 MCP token
  -> 调 browser.launch_args 预览启动命令，或调 browser.launch 直接启动 MJYBrowser
  -> chrome.exe 使用 --launch-token 完成授权
  -> 可选：继续通过 MCP 控制标签、环境、截图和验收
```

## 启动 MJYBrowser

最小启动参数：

```text
chrome.exe --launch-token=<一次性加密启动 token> --auth-url=https://api.jimuie.com/api/v1/license/sign
```

`<一次性加密启动 token>` 由授权码临时生成；不要把授权码本身放进 `chrome.exe` 命令行。

开发测试可追加：

```text
--remote-debugging-port=41729
--remote-allow-origins=*
--mjy-control-port=41730
--mjy-control-token=<control_token>
```

## 授权 v2.1 行为

```text
1. chrome 先检查本地 signed lease。
2. lease 有效则直接启动。
3. lease 无效、缺失、过期或 device 不匹配时，chrome 使用 --launch-token 直连授权服务。
4. 服务端验证订阅和授权码后签发 nonce 响应，并返回短期 lease。
5. 任一验签或有效期检查失败，chrome 直接退出。
```

开发者不需要实现本地授权中转组件，也不持有 Ed25519 私钥。

## MCP 自动化

MCP 用于浏览器实例编排和启动后的自动化。

```text
一次性 launch token -> 传给 chrome.exe，完成启动授权
MCP token             -> 调 browser.launch_args / browser.launch / 页面控制工具
```

`Authorization: Bearer mcp_xxx` 里的 `mcp_xxx` 要填平台签发的 **MCP 明文令牌**，不是浏览器授权码。
MCP 明文令牌通常以 `mcp_` 开头，只展示一次；数据库只保存 SHA-256 哈希，丢失后需要停用旧 token 并重新生成。
可在会员中心 → MCP 接入自助生成或停用 MCP token。

推荐流程：

```text
1. 获取浏览器授权码，并在启动前生成一次性加密 launch token。
2. 用一次性 launch token 启动 MJYBrowser，并打开 CDP 41729 或 Control API 41730。
3. 获取 MCP 明文令牌，配置到 Cursor 或其它开发工具。
4. 开发工具通过 /api/v1/mcp 调 browser.open_tab / browser.navigate / browser.evaluate 等工具。
```

开发测试启动示例：

```text
chrome.exe --launch-token=<一次性加密启动token> --auth-url=https://api.jimuie.com/api/v1/license/sign --remote-debugging-port=41729 --remote-allow-origins=* --mjy-control-port=41730 --mjy-control-token=<control_token>
```

MCP 请求头示例：

```text
Authorization: Bearer mcp_这里填平台生成并只展示一次的明文控制令牌
```

## 权限建议

```text
只读巡检        browser:read
页面自动化      browser:read,browser:control,browser:evaluate
截图验收        browser:read,browser:control,browser:screenshot
内部管理员      *
```

MCP token 应按用户和应用隔离，泄露后在后台停用对应 token。