okx-onchain-console 0.1.0

package/COMPANION.md

@@ -0,0 +1,42 @@
+# 本机只读数据桥接
+
+## 本地 Web 入口
+
+`npm start` / 发布后的 `npx okx-onchain-console` 使用 `web.mjs` 启动仅监听 `127.0.0.1` 的 HTTP 服务。该服务直接调用 Companion 导出的 `snapshot()`，不启动 Native Messaging 协议；原扩展仍按原协议工作。
+
+Web 服务托管 `dist-web` 界面（`npm run build:web` 生成），通过页面标记明确选择真实数据模式。`GET /api/snapshot` 必须携带每次启动新生成的 Bearer 凭证，同时验证 Host、Origin 和跨站请求标记；不提供跨域访问和写入接口，也不接受 CLI 参数。凭证通过 URL fragment 交给页面，再移入 sessionStorage，避免通过 HTTP URL 或 Referer 发送。并发快照请求复用同一轮查询。Web 模式不读取演示操作历史、不支持模拟执行，也不会在查询失败时回退模拟数据。
+
+`--port` 可指定端口（默认 0，由系统选择），`--no-open` 禁止自动打开浏览器。使用 Ctrl+C 停止服务；再次启动会生成新的访问凭证。Web 与扩展复用原有 CLI 白名单、脱敏和数据来源状态。
+
+## 边界
+
+实际扩展的数据链路为：UI → 扩展后台 → Native Messaging → `companion.mjs` → OnchainOS CLI → OKX 服务。开发预览仍使用 `MockOnchainDataSource`，两种模式不会混合或自动回退。
+
+真实模式只读。网页内容脚本不能调用 Companion；后台验证发送者必须是专用 OKX.AI 路由中的扩展 iframe。Companion 只接受 `snapshot`，不存在任意命令入口，也不提供平台写入、签名、付款、领取或登录操作。
+
+## 只读映射
+
+| 领域             | 已接入 CLI 能力                                     |
+| ---------------- | --------------------------------------------------- |
+| 账户与钱包       | wallet status / addresses / balance --all / history |
+| 身份、审核、服务 | agent get-my-agents / service-list / feedback-list  |
+| 调用与任务       | 本机 payments 记录 / active-tasks / my-tasks        |
+| 奖励             | asp-claimable / arbitration-claimable               |
+| 订阅             | my-subscriptions --role buyer / provider            |
+| 争议、退款       | arbitration-list / refund-list                      |
+
+命令已按本机 OnchainOS CLI 4.6.0 核实。单个列表最多读取 50 条，未知角色使用 `Unknown`，未知服务类型和缺失字段显示「未提供」，不推断审核、账单、退款或争议结果。
+
+余额按 `details → data → tokenAssets` 读取，流水按批次内的 `orderList` 读取，服务按账户分组内的 `list` 读取；这些层级均来自 CLI 4.6.0 的实际响应，不再使用通用数组猜测。角色优先采用 `roleLabel`，并兼容 CLI 的 `1 User / 2 ASP / 3 Evaluator` 数值协议。
+
+快照附带每个来源的可用性：成功且有记录、成功但当前为空、查询失败或暂无结构化数据。`asp-claimable` 与 `arbitration-claimable` 当前仅输出人类可读文本，因此真实模式不解析、不展示奖励金额。
+
+A2MCP 不会创建 A2A 任务，CLI 4.6.0 也没有调用历史列表命令。Companion 只读解析 `~/.onchainos/payments/pay_*.json` 中由 CLI 保存的 A2MCP 执行状态，按当前账户过滤，仅输出服务说明、请求方式、调用参数、请求金额、时间和执行状态；付款地址、原始协议内容、签名及响应正文不会进入快照。CLI 文件中的执行成功不等同于链上结算成功；本地记录没有付款回执时，界面明确显示结算未确认。
+
+## Native Messaging 协议
+
+扩展后台使用 `connectNative` 保持 Port，在同一个 Companion 进程内重复请求；Port 断开时拒绝未完成请求，下次刷新自动重连。请求 `{ version: 1, requestId, method: "snapshot" }`；响应 `{ version: 1, requestId, ok, data?, error? }`。
+
+使用 `npm run companion:install` 注册 `com.okx.onchain_console`，并生成使用 Node 绝对路径的固定启动器，避免 Chrome 的精简环境找不到 Node。宿主只允许 manifest 固定公钥对应的扩展 ID。CLI 通过 `execFile` 参数数组调用，无 shell 拼接；每条命令限制 20 秒与 2 MB 输出。未登录、命令缺失、网络故障与权限不足作为 warnings 返回，禁止静默切换模拟数据。
+
+敏感字段按精确键名递归移除，包括 access/refresh token、API key/secret、passphrase、Session/TEE/签名材料、私钥、助记词和原始交易。Companion 不直接读取 OnchainOS 凭证文件。真实写入另行设计，不复用当前只读协议。

package/README.md

@@ -0,0 +1,240 @@
+<p align="center">
+  <img src="public/product-icon.png" width="160" alt="Onchain OS Console product icon" />
+</p>
+
+<h1 align="center">Onchain OS Console</h1>
+
+<p align="center">把本机 OnchainOS CLI 数据带到 OKX.AI 的只读个人控制台。<br />A local, read-only personal console for OnchainOS data inside OKX.AI.</p>
+
+## Preview / 预览
+
+![Onchain OS Console overview](public/screenshots/console-overview.png)
+
+> This project does not read wallet private keys or initiate signatures, payments, or onchain transactions.
+
+## 中文
+
+### 常用命令
+
+| 命令                      | 用途                                                                            |
+| ------------------------- | ------------------------------------------------------------------------------- |
+| `npm run start:web`       | 构建 Web 版、启动本地服务并自动打开浏览器                                       |
+| `npm run start:extension` | 构建扩展、注册本机 Companion，并打开 Chrome 扩展管理页和 OKX.AI 控制台（macOS） |
+| `npm run build:web`       | 仅构建 Web 版到 `dist-web`                                                      |
+| `npm run build:extension` | 仅构建浏览器扩展到 `dist`                                                       |
+| `npm run build`           | 构建两种版本                                                                    |
+| `npm run dev`             | 启动 Vite 热更新预览，使用模拟数据                                              |
+
+`npm start` 是 `start:web` 的快捷入口。两种构建使用独立目录，不会相互覆盖。扩展首次启动仍需在 Chrome 管理页开启开发者模式、手动加载 `dist`；已加载的扩展在重建后点击刷新。`start:extension` 沿用当前 macOS Companion 安装方式。
+
+### 本地 Web 版（推荐）
+
+Web 版与 Chrome 扩展版共用界面和只读查询。Web 版不需要安装扩展或注册 Native Messaging Host；浏览器直接访问本机服务。需要 Node.js 22.14+、OnchainOS CLI，并由用户在本机完成 `onchainos wallet login`。
+
+从源码启动：
+
+```sh
+npm ci
+npm run start:web
+```
+
+默认选择空闲端口，自动打开浏览器。关闭标签页不会停止服务，在终端按 Ctrl+C 停止。指定固定端口可以保留该地址下的账户选择：
+
+```sh
+npm run start:web -- --port 43127
+npm run start:web -- --no-open
+```
+
+服务只监听 `127.0.0.1`，启动地址包含随机凭证。请使用终端输出的完整地址；页面加载后会从地址栏移除凭证，并在当前标签页会话中保留。重启后需要使用新地址。页面仅通过同源、鉴权的 `/api/snapshot` 读取真实数据，连接失败不会切换模拟数据。浏览器开发预览仍由 `npm run dev` 提供。
+
+### npx 分发
+
+仓库已配置 `okx-onchain-console` 命令和 npm 发布文件白名单；**目前尚未发布到 npm，包名可用性和发布权限需在发布时确认**。先在本地打包并验证：
+
+```sh
+npm pack
+npx --yes --package ./okx-onchain-console-0.1.0.tgz okx-onchain-console
+```
+
+打包会自动构建，并包含 Web 启动器、只读查询和扩展构建文件。发布成功后，用户才能直接运行：
+
+```sh
+npx --yes okx-onchain-console
+npx --yes okx-onchain-console --port 43127 --no-open
+```
+
+不会自动安装 CLI、登录钱包或注册 ASP。Chrome 扩展继续按下方安装步骤使用，`npm run build` 仍生成可加载的 `dist`。
+
+### 为什么做这个项目
+
+OKX.AI 上的 Agent、服务与任务逐渐增多，但与个人相关的数据主要分散在 OnchainOS CLI 的不同命令和本机记录中。用户需要反复切换终端，才能确认自己有哪些身份、钱包地址、服务、调用、订阅和交易记录；当结果为空时，也很难立即判断是“确实没有数据”、登录失效，还是接口查询失败。
+
+Onchain OS Console 希望补上这个个人控制台：不复制一套账户系统，也不托管用户数据，而是在用户已经使用的 OKX.AI 页面中，将本机 CLI 能确认的数据整理成带有来源状态的只读视图。它尤其解决以下问题：
+
+- 将分散的 CLI 查询集中到一个界面，减少重复命令和上下文切换。
+- 展示钱包地址、调用记录和付款/结算状态等容易遗漏的信息。
+- 明确区分空数据、查询错误与暂不支持的数据，避免用占位内容制造“看起来完整”的假象。
+- 沿用 OKX.AI 原生 header、footer 和页面滚动体验，不再依赖狭窄的插件侧边栏。
+
+### 如何解决
+
+```text
+OKX.AI 专用路由
+  → Chrome 扩展后台
+  → Native Messaging
+  → 本机 Node Companion
+  → 只读 OnchainOS CLI 命令
+```
+
+扩展在 `/_onchain-os-console` 只替换原本的 404 内容区，并把隔离的控制台 iframe 嵌入其中。界面请求经扩展后台发送给 Native Messaging 宿主；Companion 由 Chrome 按需启动，并在 Native Messaging 端口存续期间复用。它按固定白名单调用 OnchainOS CLI，再将结果规范化后返回。
+
+项目只接入已经通过 CLI 实际响应确认的结构化字段。登录有效时，每个已接入来源都会同时返回可用性状态；登录失效时则统一提示重新登录。因此界面可以说明“有数据”“当前为空”“查询失败”或“CLI 暂无结构化数据”，而不是猜测字段和业务结果。本机数据模式只提供查看能力，所有模拟操作只存在于隔离的开发预览中。
+
+### 功能
+
+- 在 OKX.AI 顶栏增加「控制台」入口，并在 `/_onchain-os-console` 替换 404 内容区；原生 header 与 footer 保持不变。
+- 通过 Chrome Native Messaging 连接由 Chrome 按需启动的本机 Node Companion，再调用 OnchainOS CLI 获取数据快照；扩展页面本身不运行 Node。
+- 汇总本机账户、Agent 身份与审核、ASP 服务、调用与任务、订阅、钱包地址、资产、流水、争议与评价。
+- 设置页明确区分“有数据”“当前为空”“查询失败”和“暂无结构化数据”，不把空结果伪装成故障或业务状态。
+- 自适应深色界面，以及支持筛选与详情查看的控制台交互。
+
+### 环境要求
+
+- Node.js 22.14+
+- Chrome 116+ 桌面版
+- 已安装并可运行 OnchainOS CLI
+
+### 安装
+
+```sh
+git clone https://github.com/BiscuitCoder/okxai_console.git
+cd okxai_console
+npm ci
+npm test
+npm run build
+npm run companion:install
+```
+
+确认 `onchainos wallet status` 显示已登录；若登录过期，请运行 `onchainos wallet login`。随后打开 `chrome://extensions`，开启开发者模式，选择“加载已解压的扩展程序”，加载项目中的 `dist` 目录。
+
+访问或刷新 [OKX.AI](https://www.okx.ai/zh-hans)，从顶栏进入「控制台」。未安装扩展时，`https://www.okx.ai/_onchain-os-console` 仍是正常的 404 页面。
+
+开发界面时可运行：
+
+```sh
+npm run dev
+```
+
+浏览器预览使用隔离的模拟数据，不代表 Native Messaging 已连接。需要验证真实数据时，请加载构建后的扩展。
+
+### 安全模型
+
+安全不是一句“只读”声明，而是由权限、调用路径和数据处理共同限制：
+
+| 用户可能担心什么       | 项目如何限制风险                                                                                                                                         |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 会读取私钥或助记词吗？ | 不读取 OnchainOS 凭证文件，不请求私钥、助记词或签名材料，也没有签名和交易入口。                                                                          |
+| 会读取 OKX.AI 网页吗？ | 内容脚本只挂载导航和替换专用路由 DOM，并仅读取网页可访问的 `locale` Cookie 以跟随界面语言；不申请 `cookies` 或 `webRequest` 权限，也不解析网页账户数据。 |
+| 能执行任意本机命令吗？ | Companion 协议只接受 `snapshot`；网页和扩展请求不能传入命令或参数。固定命令通过 `execFile` 参数数组执行，不经过 shell。                                  |
+| 数据会发到哪里？       | 快照只在本机 Companion 与扩展 iframe 间传递；项目没有自建服务器、遥测或云同步。CLI 查询仍会按其自身配置访问 OKX 服务。                                   |
+| OKX.AI 能读取快照吗？  | 控制台 iframe 是 `chrome-extension://` 独立来源，OKX.AI 页面脚本不能读取其中的数据；后台也只接受专用路由内的扩展 iframe。                                |
+| 返回内容包含令牌吗？   | 数据进入扩展前会按已知敏感字段键名递归移除 Token、API Key、Session、TEE、私钥、助记词、签名和原始交易等内容。新增上游字段仍需持续审查。                  |
+
+扩展仅申请 `storage`、`nativeMessaging` 和两个 OKX.AI HTTPS 域名权限。账户选择只保存在 `chrome.storage.local`，不进行云同步。每条 CLI 命令限制为 20 秒和 2 MB 输出；本机数据模式没有平台写入、领取、付款或登录操作。`companion:install` 只会在 Chrome 的 NativeMessagingHosts 目录注册宿主清单并创建固定启动脚本，不会安装系统守护进程。代码完全公开，安装前可以直接审查 [manifest](./public/manifest.json)、[扩展后台](./src/background.ts) 和 [Companion](./companion.mjs)。
+
+对于支持且显式指定分页的查询，当前只读取第一页、最多 50 条；其他查询遵循 CLI 的默认返回范围。CLI 只有可读文本、没有稳定结构化输出的数据不会被猜测解析。
+
+更多连接机制与命令范围见 [COMPANION.md](./COMPANION.md)。
+
+---
+
+## English
+
+### Local web app and npx
+
+Run `npm ci`, then `npm run start:web` to build and open the local web console. Node.js 22.14+ and a locally installed, authenticated OnchainOS CLI are required. The server binds only to `127.0.0.1`, chooses an available port, and opens a session-authenticated browser URL. Use `npm run start:web -- --port 43127 --no-open` for a fixed port without opening a browser; press Ctrl+C to stop. `npm start` is an alias for `start:web`.
+
+`npm run build:web` builds to `dist-web`; `npm run build:extension` builds the Chrome extension to `dist`; `npm run build` builds both. On macOS, `npm run start:extension` builds the extension, registers the Companion, and opens Chrome's extensions page and OKX.AI. First-time users must manually load `dist`; existing users must reload the extension after rebuilding.
+
+The npm package is **not published yet**. Test distribution with `npm pack` and `npx --yes --package ./okx-onchain-console-0.1.0.tgz okx-onchain-console`. After publication, users can run `npx --yes okx-onchain-console`. Chrome extension builds and installation remain supported. `npm run dev` continues to use isolated demo data.
+
+### Why this project exists
+
+As the number of Agents, services, and tasks on OKX.AI grows, personal data remains spread across separate OnchainOS CLI commands and local records. Users must repeatedly switch to a terminal to understand their identities, wallet addresses, services, invocations, subscriptions, and transactions. An empty response also leaves an important ambiguity: there may be no data, the login may have expired, or the query may have failed.
+
+Onchain OS Console fills that personal-console gap. It does not create another account system or host user data. Instead, it organizes data that the local CLI can verify into a read-only view with explicit source status inside the OKX.AI experience. In practical terms, it:
+
+- Consolidates fragmented CLI queries and reduces repeated commands and context switching.
+- Surfaces wallet addresses, invocation records, and payment or settlement status that are otherwise easy to miss.
+- Separates empty data, failed queries, and unsupported data instead of filling the UI with invented placeholders.
+- Reuses the native OKX.AI header, footer, and page scrolling rather than relying on a narrow extension sidebar.
+
+### How it works
+
+```text
+Dedicated OKX.AI route
+  → Chrome extension background
+  → Native Messaging
+  → Local Node companion
+  → Read-only OnchainOS CLI commands
+```
+
+At `/_onchain-os-console`, the extension replaces only the original 404 content and embeds an isolated console iframe. UI requests go through the extension background to a Native Messaging host. Chrome starts the local companion on demand and reuses it while the Native Messaging port remains open. The companion invokes a fixed allowlist of OnchainOS CLI commands, normalizes their results, and returns the snapshot.
+
+Only structured fields verified against real CLI responses are integrated. When the login is valid, every integrated source reports its availability; an expired login produces a single login warning. This lets the UI distinguish available, empty, failed, and currently unstructured data without guessing fields or business outcomes. Local-data mode is display-only; simulated actions exist only in the isolated development preview.
+
+### Features
+
+- Adds a Console entry to the OKX.AI header and replaces only the 404 content at `/_onchain-os-console`, preserving the native header and footer.
+- Uses Chrome Native Messaging to connect to a local Node companion started on demand by Chrome. The companion calls the OnchainOS CLI for a data snapshot; Node does not run inside the extension page.
+- Brings together local accounts, Agent identities and approval status, ASP services, invocations and tasks, subscriptions, wallet addresses, balances, transactions, disputes, and feedback.
+- Clearly distinguishes available, empty, failed, and unstructured data instead of inventing values or treating an empty result as an error.
+- Includes a responsive dark UI with filtering and record-detail interactions.
+
+### Requirements
+
+- Node.js 22.14+
+- Chrome 116+ for desktop
+- A working OnchainOS CLI installation
+
+### Installation
+
+```sh
+git clone https://github.com/BiscuitCoder/okxai_console.git
+cd okxai_console
+npm ci
+npm test
+npm run build
+npm run companion:install
+```
+
+Verify that `onchainos wallet status` reports an active login. If it has expired, run `onchainos wallet login`. Open `chrome://extensions`, enable Developer mode, choose **Load unpacked**, and select this project's `dist` directory.
+
+Open or refresh [OKX.AI](https://www.okx.ai/), then use the Console item in the header. Without the extension, `https://www.okx.ai/_onchain-os-console` remains a normal 404 page.
+
+For UI development:
+
+```sh
+npm run dev
+```
+
+The browser preview uses isolated mock data and does not validate Native Messaging. Load the built extension to verify live local data.
+
+### Security model
+
+Security is enforced through permissions, the request path, and data handling—not merely by describing the product as “read-only.”
+
+| Concern                          | Protection                                                                                                                                                                                                                                            |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Does it read private keys?       | It does not read OnchainOS credential files or request private keys, seed phrases, or signing material. There is no signing or transaction entry.                                                                                                     |
+| Does it inspect the OKX.AI page? | The content script only mounts navigation and replaces the dedicated route DOM. It reads only the page-accessible `locale` cookie to follow the UI language; it has no `cookies` or `webRequest` permission and parses no account data from the page. |
+| Can it run arbitrary commands?   | The companion accepts only `snapshot`; pages and extension requests cannot supply commands or arguments. Fixed commands use an `execFile` argument array without a shell.                                                                             |
+| Where does the data go?          | Snapshots pass only between the local companion and extension iframe. The project has no backend, telemetry, or cloud sync. CLI queries still access OKX services according to their own configuration.                                               |
+| Can OKX.AI read the snapshot?    | The console iframe has an isolated `chrome-extension://` origin, so OKX.AI page scripts cannot read its data. The background also accepts only the extension iframe on the dedicated route.                                                           |
+| Can tokens reach the UI?         | Known sensitive field names are recursively removed, including tokens, API keys, sessions, TEE data, private keys, seed phrases, signatures, and raw transactions. New upstream fields still require review.                                          |
+
+The extension requests only `storage`, `nativeMessaging`, and the two OKX.AI HTTPS host permissions. Account selection remains in `chrome.storage.local` and is not synced. Each CLI command has a 20-second timeout and a 2 MB output limit. Local-data mode has no platform write, claim, payment, or login operations. `companion:install` only registers a host manifest in Chrome's NativeMessagingHosts directory and creates a fixed launcher; it does not install a system daemon. The code is open for inspection: review the [manifest](./public/manifest.json), [extension background](./src/background.ts), and [companion](./companion.mjs) before installing.
+
+For queries that support and explicitly specify pagination, the console currently reads only the first page, up to 50 records; other queries follow the CLI's default response range. Data without stable structured CLI output is not guessed or scraped.
+
+See [COMPANION.md](./COMPANION.md) for the connection model and command scope.