# @amoshydra/oktoso 中文文档

规范地址：https://npmcn.com/package/%40amoshydra/oktoso/

版本：0\.1\.22
npm 元数据更新时间：2026-11-07T17:08:59.475Z
中文译文更新时间：2026-11-06T13:55:05.066Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40amoshydra/oktoso
原文对照：https://npmcn.com/package/%40amoshydra/oktoso/?lang=original
项目主页：https://github.com/amoshydra/oktoso
源码仓库：https://github.com/amoshydra/oktoso

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：9.1 MB，45 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24
- 运行依赖：0 个
- 首次发布：2026-10-31T21:35:48.499Z
- 最新版本发布：2026-11-07T17:08:59.129Z
- 近 30 天下载量：3149（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

Oktoso——供AI代理商跨供应商和可穿戴客户使用的中枢和控制平面.

## 安装

```sh
npm install @amoshydra/oktoso
```

也可以使用：`pnpm add @amoshydra/oktoso`、`yarn add @amoshydra/oktoso`、`bun add @amoshydra/oktoso`

## README

![Oktoso — one hub for every agent session](https://npmcn.com/package/%40amoshydra/oktoso/docs/brand/banner.png)

[![npm version](https://img.shields.io/npm/v/@amoshydra/oktoso?color=3550c8&label=npm)](https://www.npmjs.com/package/@amoshydra/oktoso) [![MIT license](https://img.shields.io/badge/license-MIT-3550c8)](https://npmcn.com/package/%40amoshydra/oktoso/LICENSE) ![Node.js 24 or newer](https://img.shields.io/badge/node-%E2%89%A524-3550c8)

Oktoso是AI代理的中枢第一会话中心. 一个地方可以查看需要关注的内容,浏览会话,开始聊天,并跨OpenCode,Open WebUI,Hermes等供应商回复.

该枢纽是一个小型节点/TypeScript HTTP服务. 客户端是薄而可替换的:网络,移动,桌面,Even G2眼镜和VR.

## 屏幕

![An Oktoso session with the provider, live reasoning, tool activity, details, and a shell permission waiting for approval](https://npmcn.com/package/%40amoshydra/oktoso/docs/screenshots/session.png)

提供方上下文,现场推理,工具活动,以及等待您的权限.

## 状态

执行阶段. `v0.1.11` 传输聊天交互切片:消息复制、以枢机为后盾的拼写、OpenCode附件、Open WebUI in-chat分支切换和重试、OpenCode会话叉和一个保存刷新时消息顺序的提供者命令固定。 OpenCode和Open WebUI是活的,网络中枢有搜索,草稿,注意,最新的第一张记录誊本,以及递增的信息流,而Even G2客户端有对接,收件,聊天,提问,批发,发现,失败状态,以及glyph传奇. 经批准的UI参考被冻结为 `design-v1.3`。自 `v0.1.11`,执行MCP北行片: `oktoso mcp` 斯地迪奥桥和枢纽 `/mcp` 带有范围符号、许可列表、审计、费率限制和注意力/会议资源订阅。 所剩空白包括:真正的Hermes,G2语音和硬件接受,MCP OAuth,以及远程/多主机加固和Termux/跨主机接受运行.

## 文档

-   [`docs/design.md`](https://npmcn.com/package/%40amoshydra/oktoso/docs/design.md) - 架构、域模型、供应商适配器、API、安全、部署
-   [`docs/plan.md`](https://npmcn.com/package/%40amoshydra/oktoso/docs/plan.md) - 分阶段交付计划和接受标准
-   [`docs/code-structure.md`](https://npmcn.com/package/%40amoshydra/oktoso/docs/code-structure.md) - 执行系统、存储器布局、API添加和任务排序
-   [`docs/ui-ia.md`](https://npmcn.com/package/%40amoshydra/oktoso/docs/ui-ia.md) - 信息架构、屏幕、流量、反应和眼镜/VR适应
-   [`docs/visual-audit.md`](https://npmcn.com/package/%40amoshydra/oktoso/docs/visual-audit.md) - 对照审计、视觉标志和组件规则
-   [`docs/design-lock.md`](https://npmcn.com/package/%40amoshydra/oktoso/docs/design-lock.md) - 冻僵了 `design-v1.3` 参考和改革政策
-   [`docs/interaction-contract.md`](https://npmcn.com/package/%40amoshydra/oktoso/docs/interaction-contract.md) - 聊天副本、口语、附件、分枝、再试和叉语义
-   [`docs/package-evaluation.md`](https://npmcn.com/package/%40amoshydra/oktoso/docs/package-evaluation.md) - 一揽子援助计划决定记录
-   [`docs/brand/README.md`](https://npmcn.com/package/%40amoshydra/oktoso/docs/brand/README.md) - 商标、应用程序图标和横幅资产
-   [`AGENTS.md`](https://npmcn.com/package/%40amoshydra/oktoso/AGENTS.md) - 用户界面/设计合同和代理人存放处指示
-   [`docs/openapi.yaml`](https://npmcn.com/package/%40amoshydra/oktoso/docs/openapi.yaml) - 生成API合同
-   [`docs/deployment.md`](https://npmcn.com/package/%40amoshydra/oktoso/docs/deployment.md) - 远程提供者、Termux、Docker、系统、TLS和VPN部署
-   [`SECURITY.md`](https://npmcn.com/package/%40amoshydra/oktoso/SECURITY.md) - 证书处理和脆弱性报告
-   [`docs/publishing.md`](https://npmcn.com/package/%40amoshydra/oktoso/docs/publishing.md) - npm信任的出版和发布工作流程
-   [`docs/prototypes/index.html`](https://npmcn.com/package/%40amoshydra/oktoso/docs/prototypes/index.html) - 具有模拟数据的交互式UI原型

## 应用程序

-   [连G2](https://npmcn.com/package/%40amoshydra/oktoso/apps/even-realities-g2/README.md) ——可观的注意并回复眼镜表面.

## 原则

-   中心拥有提供者证书,会话索引编制,正常化,关注,以及活动粉丝出道.
-   客户端消费了1个HTTP/SSE API. 没有客户拥有商业逻辑.
-   提供方API是真理的来源. 枢纽缓存和索引.
-   非加太公司没有要求,枢纽上也没有本地代理程序.
-   没有网络假设。 电线守护(WireGuard),Tailscale(Tailscale),LAN(LAN),和TLS(TLS)是运营商的担忧.
-   一个代码库运行于Termux,Linux,macOS,一个Raspberry Pi,或者一个VPS上.

## 发展

```sh
pnpm install
pnpm dev
```

-   网络 : `http://localhost:5175`
-   中枢 API : `http://127.0.0.1:8787`
-   发展标志: `dev-token-oktoso` (预填入dev登录;运行) `pnpm pair:dev` 以链接代替)
-   OpenCode 读取/写出:会话索引、笔录、作曲、新会话和中断
-   打开 WebUI : 聊天, 当前分支, 模型, 新聊天, 并快速发送
-   提供者: OpenCode 和 Open WebUI 适配器; Hermes 仍然是只健康假名
-   注意:权限,表单,未读会话,失败,提供者支持的行动,以及活导航徽章

`pnpm dev` 启动枢机, Vite, 假 Open WebUI/Hermes 服务器, 以及假 OpenCode 服务器 。 真正的提供者证书属于被忽略的 `.env.local` 文件 :

```bash
OPENCODE_BASE_URL=http://127.0.0.1:4096
OPENCODE_USERNAME=opencode
OPENCODE_PASSWORD=...
OPENWEBUI_BASE_URL=https://openwebui.example
OPENWEBUI_API_KEY=...
```

当这些变量出现时,匹配的提供者使用真实实例而不是假实例. 关闭一个提供者的基础 URL 离开提供者在其本地的假端点。 dev 命令不会启动被冻结的原型.

`.env.local` 财务报告和审定财务报表 `.data/` 被忽略。 保留 `.env.local` 在模式下 `0600`承诺 `dev-token-oktoso` 是本地唯一的所有者符; 生成长随机 `HUB_TOKEN` 任何可达到的部署。 旋转它可以取消每对会话.

## 原型

```sh
pnpm prototype
```

打开 `http://127.0.0.1:4174` 在浏览器中。 调整窗口大小以查看移动布局 .

## 构建

```sh
pnpm typecheck
pnpm test
pnpm test:e2e
pnpm openapi:check
pnpm build
```

`pnpm test:e2e` 构建单端口捆绑,并运行Playwright浏览器套件,以对抗临时枢纽和假供应商.

不配置靴子开始本地工作空间空 :

```sh
pnpm start
```

它创建了没有提供者的集线器配置,生成了恒定所有者符,打印一次,并启动集线器. 第一次启动时,它也会在服务器监听后打印出一次性的对接链接. 在配置中添加提供者并重新启动 。 明确要求 `--config` 或者说 `HUB_CONFIG` 路径永远不会被隐含地创建.

配置与其它用户配置共存, 而不是在工作目录中 :

| 平台 | 配置 |
| --- | --- |
| Linux, Termux 软件 | `$XDG_CONFIG_HOME/oktoso/hub.config.json` (单位:千美元)`~/.config/oktoso/hub.config.json` (默认) |
| 马科斯 | `~/Library/Application Support/Oktoso/hub.config.json` |
| 窗口 | `%LOCALAPPDATA%\Oktoso\hub.config.json` |

`--config <path>` 或者说 `HUB_CONFIG` 超过它。 遗产 `./hub.config.json` 在工作目录中,当平台配置尚未存在时,仍然使用,而枢纽在返回时会打印出一行警告. 运行时状态默认为平台状态目录( R)`$XDG_STATE_HOME/oktoso`, (中文(简体) ), `~/Library/Application Support/Oktoso/data`, (中文(简体) ), `%LOCALAPPDATA%\Oktoso\data`)),所以读取标记和草稿不会将每个工作目录分叉.

文件持有所有者符和每个提供者证书. 它被创建 `0600` 内置 a `0700` 目录,当文件被另一个账户读取或写入时,中枢拒绝启动,打印 `chmod 600` 命令运行.

`pnpm start` 运行已建 `dist/hub.js`。同一切入点与 `oktoso` npx 安装的 bin : `npx @amoshydra/oktoso` 启动中枢,并 `npx @amoshydra/oktoso pair` 连接到运行中枢.

## 供应商证书

从提供者屏幕或配置文件中添加提供者, 包含基础 URL 和提供者签发的证书 。 身份证明只写:API从不返回,在编辑时留下密码空白保留所存储的值.

| 提供者 | 认证 | 证书来自哪里 |
| --- | --- | --- |
| 打开代码 | 基本认证, 用户名 `opencode` | `opencode service get password` 在运行 OpenCode 的机器上,或 `.password` 内 `~/.local/state/opencode/service.json` |
| 打开 WebUI | 借记符 | **设置 — 账户 — API 密钥** 在打开 WebUI 中 |
| 赫尔墨斯 | 借记符 | 这个 `API_SERVER_KEY` 它的 API 服务器启动于 |

提供者表单在证书字段下显示相同的提示. OpenCode 一次生成其服务密码, 并在整个重启时保留它; 如果它被重新生成, 更新提供者或行显示 `auth-error`。 。 。 .

## 对齐浏览器或可穿戴

配对避免将所有者代币复制到每个客户端.

在第一个创建配置的启动时,TUI打开一个设置面板,上面会显示一次所有者符号. 新闻 `p` 打开配对的 QR。 普通和非TTY模式打印出首个运行的对接链接。 后来开始打印一行提醒而不是链接. 链接打开一个确认页;在您按下前不会对齐 **配对此设备**。 。 。 .

在前景终端中, 类型 `p` 并随时按 Enter 键打印新链接。 服务器继续运行. 中心启动时, 这是正常的路径 `npx` 或者说 `pnpm start`。 。 。 .

对于背景进程或第二个终端,运行:

```sh
pnpm pair
```

用包装的CLI,即 `npx @amoshydra/oktoso pair`它为回回路和局域网地址打印一次性链接。 链接在五分钟后失效,工作一次。 主人代号从不共享. 对于已建服务器:

```sh
node dist/hub.js --pair
```

当终端是 TTY 有局域网地址时,命令还打印 a **扫描成对** QR码. 用手机相机扫描,打开确认页. 在支持的安全文本浏览器上,登录屏幕也提供 **扫描配对QR** 使用浏览器条码检测 API。 在Plain-HTTP 局域网的出处或浏览器上,没有API,取而代之的是使用电话相机应用.

使用 `--url https://hub.example.com` 当枢机在代理机后面时。 CLI从配置中以所有者代号认证,必须运行在可以到达中枢的主机上. 如果中枢被绑定在一个回回地址,则绑定 `0.0.0.0` 或通过 `--url` 用于配对另一个设备。 如果你以 `HUB_HOST` 或者说 `HUB_PORT` 覆盖, 将相同的变量传递到 `pair` 命令,所以打印的链接匹配。 对 Dev 配置, 使用 `pnpm pair:dev`。 。 。 .

Paired浏览器使用30天的HttpOnly会话 cookie,不将指针存储于JavaScript. 会话在浏览器活动时自动刷新;过期后闲置的浏览器再刷新. API 客户端可以打电话 `POST /api/v1/auth/refresh` 他们的会话代号。 从另一个来源装入的软件包仍然可以粘贴所有者或会话符号. 旋转 `HUB_TOKEN` 取消每对会话.

打开一对页不消耗代码,因此聊天链接预览是安全的. 按键 **配对此设备** 消耗它。 5分钟后,页面显示一个过期消息,让你按 `p` 在中枢终端中;如果浏览器已经对齐,则直接去应用.

## 用于代理的多氯乙烯

OpenCode等MCP客户端可以使用Oktoso作为其控制平面:

```sh
oktoso mcp              # read-only tools
oktoso mcp --allow-write
```

大桥会讲MCP过stdio,会读取"枢纽配置",并用"配置符"给"枢纽REST API"打电话. 只读是默认值 。 写作工具覆盖发送,创建,中断,标记读取,并采取行动引起注意. 服务器拒绝向引用并需要的 OpenCode 会话写入 `confirm: true` 在核准一个注意事项之前.

中枢也可以在 `/mcp` 超流性HTTP. 启用 `mcp` 在中心配置中添加一个带有可选写、提供者和工具瞄准镜的无记名符号:

```jsonc
{
  "mcp": {
    "enabled": true,
    "tokens": [
      { "id": "controller", "token": "${MCP_TOKEN}", "allowWrite": true }
    ]
  }
}
```

托管的电话是限速的,限时的,会话的,并附在 `<dataDir>/mcp-audit.jsonl`。会议也暴露 `oktoso://attention` 财务报告和审定财务报表 `oktoso://sessions` 有订阅更新的资源。 见 [`docs/mcp-northbound.md`](https://npmcn.com/package/%40amoshydra/oktoso/docs/mcp-northbound.md) 用于完整配置、 OpenCode 远程设置、 工具列表、 控制器快捷以及安全规则.

## 终端用户界面

在前台TTY中,枢纽制造出全屏仪表板:

```text
╭─ Oktoso ──────────────────────────────────────────── v0.1.0 ─╮
│ http://127.0.0.1:8787                      up 12m 04s   json │
├──────────────────────────────────────────────────────────────┤
│ Providers 2/3   Sessions 12   Attention 3              1 SSE │
│ Event 1042      Requests 142  Errors 0       p pair · ? help │
├──────────────────────────────────────────────────────────────┤
│ Activity                                                     │
│ 18:52:01  desktop-opencode  online                           │
│ 18:52:04  attention         permission · Fix auth            │
├──────────────────────────────────────────────────────────────┤
│ p pair · l logs · r refresh · o open · ^C quit · ? help      │
╰──────────────────────────────────────────────────────────────╯
```

密钥 :

-   `p` —对一设备;打开 QR/link 模式
-   `l` 切换活动和日志; `j`编号 :`k` 滚动
-   `r` ——重新检查提供者并刷新缓存
-   `o` ——打开web UI,或在模式打开时打开配对链接
-   `c` 复制配对链接或首发所有者代号
-   `t` ——在配对模式打开时只复制配对代码
-   `?` - 关键帮助
-   `Ctrl+C` ——退出

在第一次运行时,中枢打开了一个设置面板,上面显示的是一次所有者符号. 新闻 `p` 到对对。 配对模式保持了QR,主局域网链接,并可以在不重新油漆的情况下可见过期时间,因此链接仍然可以选择. 在一对设备后,面板在5秒后返回仪表板.

### 再次运行命令

如果 Oktoso 已经监听了配置的主机和端口, 则秒 `npx @amoshydra/oktoso` 不崩溃与 `EADDRINUSE`。它打印状态卡和退出:

```text
Oktoso 0.1.0 is already running at http://127.0.0.1:8787
  pid 1234 · up 12m 04s · event seq 1042

  Web UI   http://127.0.0.1:8787
  Pair     npx @amoshydra/oktoso pair
  Status   npx @amoshydra/oktoso status
  Stop     Ctrl+C in the original terminal, or kill 1234
```

有用的表格 :

```sh
npx @amoshydra/oktoso status          # is it running, and where?
npx @amoshydra/oktoso pair            # pair a device against the running hub
npx @amoshydra/oktoso --port 8788     # after stopping the current hub
npx @amoshydra/oktoso --host 0.0.0.0  # override the bind host on next start
```

第二例需要自己的状态和日志目录;先停止当前中枢,或用单独的目录运行:

```sh
HUB_DATA_DIR=.data-8788 HUB_LOG_DIR=.logs-8788 npx @amoshydra/oktoso --port 8788
```

如果端口被不同的过程所占用,命令会这样说并推荐另一个端口. 没有堆栈追踪.

结构化的日志不出现在仪表板上. 在TUI模式下,它们前往平台日志目录:

```text
Linux/Termux  $XDG_STATE_HOME/oktoso/logs/hub.log
macOS         ~/Library/Logs/Oktoso/hub.log
Windows       %LOCALAPPDATA%\Oktoso\Logs\hub.log
```

只有两个文件被保存: `hub.log` 当前运行和 `hub.log.prev` 用于上次运行。 运行在 25 MiB 旋转,如果单个运行是那么长,则替换上一个文件. `--log-file`, (中文(简体) ), `--log-dir`, (中文(简体) ), `--no-log-file`,以及 `HUB_LOG_MAX_BYTES` 覆盖默认值 .

使用 `--plain` 用于向后滚动的会话; 人类输出停留在 stdout上, JSON 日志进入 stderr 。 使用 `--log-json` 为服务和流程管理人员提供服务。 非 TTY 进程从不启动 TUI; 与之配对 `npx @amoshydra/oktoso pair` 从任何终端. `--help` 列出所有旗帜.

## 堆栈

-   节点.js 24+
-   类型脚本
-   24+节点上的Hono
-   反应 + 参考网络客户端的虚拟
-   纯 JavaScript 依赖性, 没有本地模块
-   JSON 状态存储器首先; 可选 `node:sqlite` 稍后的适配器
-   捆绑 `dist/hub.js` 便携式部署

## 警卫

提供方证书,所有者代币,配对链接,运行时状态远离Git. 见 [`SECURITY.md`](https://npmcn.com/package/%40amoshydra/oktoso/SECURITY.md) 用于报告和部署指导.

## 许可证

麻省理工学院. 见 [`LICENSE`](https://npmcn.com/package/%40amoshydra/oktoso/LICENSE)。 。 。 .

## 下一个

接下来:MCP北上. 实验桥上 `feat/mcp-northbound` 暴露了枢纽的阅读工具,与 `--allow-write` 对于写作工具,自控拒绝, 一个确认的门批准, 和一能发送。 未发运。 后续行动由中心主办 `/mcp` 有范围标志和每工具审计的终点.

## 常见问题

### @amoshydra/oktoso 是什么？

Oktoso——供AI代理商跨供应商和可穿戴客户使用的中枢和控制平面\.

### 如何安装 @amoshydra/oktoso？

在项目目录运行 npm install @amoshydra/oktoso，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 oktoso，可以用 npx oktoso 直接运行。

### @amoshydra/oktoso 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/amoshydra\_\_oktoso 是否存在。

### @amoshydra/oktoso 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @amoshydra/oktoso 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @amoshydra/oktoso 可以商用吗？

@amoshydra/oktoso 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @amoshydra/oktoso 的下载量有多少？

根据 npm 官方下载统计，@amoshydra/oktoso 在 2026/10/07 – 2026/11/05 这 30 天内被下载 3,149 次，日均约 105 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @amoshydra/oktoso 还在维护吗？

最新版本 0\.1\.22 发布于 2026/11/08（今天）；至今共发布 24 个版本，其中过去 12 个月发布了 24 个；首次发布于 2026/11/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。