@x-otto/service 0.0.1-alpha.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +119 -0
- package/dist/index.d.ts +617 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +44 -0
- package/dist/index.js.map +1 -0
- package/package.json +48 -0
package/README.md
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# @x-otto/service
|
|
2
|
+
|
|
3
|
+
## 模块定位
|
|
4
|
+
|
|
5
|
+
Otto 的网络传输层：基于 Hono 的 HTTP API + WebSocket 实时通信 + 事件桥接 +
|
|
6
|
+
独立持久化存储服务（persistenced）。
|
|
7
|
+
|
|
8
|
+
## 核心功能
|
|
9
|
+
|
|
10
|
+
| 模块/导出 | 功能 |
|
|
11
|
+
|-----------|------|
|
|
12
|
+
| `CodingService` | Hono 应用生命周期 + 组件编排（WS Manager / DebugBridge / InboundRouter） |
|
|
13
|
+
| `WebSocketManager` | WebSocket 连接管理 + 会话订阅 + 鉴权（origin/token） |
|
|
14
|
+
| `EventBridge` | AgentSession 事件 → WS `Session.event` 的单向映射 |
|
|
15
|
+
| `TraceBridge` | per-session trace tail → WS（`Trace.event`） |
|
|
16
|
+
| `DebugBridge` | devtools 调试协议桥接到 HTTP/WebSocket |
|
|
17
|
+
| `InboundRouter` | 前端 → 服务端入站消息分发 |
|
|
18
|
+
| `EventBus` | 进程内事件总线（`append / subscribe`） |
|
|
19
|
+
| `startPersistenced` | 独立持久化存储服务启动器（SQLite + HTTP API） |
|
|
20
|
+
|
|
21
|
+
## HTTP API 路由
|
|
22
|
+
|
|
23
|
+
| 路由前缀 | 端点 | 说明 |
|
|
24
|
+
|----------|------|------|
|
|
25
|
+
| `/api/health` | `GET /` | 健康检查 |
|
|
26
|
+
| `/api/chat` | `POST /query` / `GET /messages` / `POST /interrupt` / `DELETE /clear` | 会话对话 |
|
|
27
|
+
| `/api/sessions` | `GET/POST /` / `GET /current` / `GET /:id/messages` / `POST /:id/resume` (501) / `GET /:id/trace` / `GET /:id/export` / `GET/PUT/DELETE /:id/model` | 会话 CRUD |
|
|
28
|
+
| `/api/sessions` (子域) | `POST /verify-path` / `POST /browse-directory` / `GET /files` (workspace) + 时间旅行端点 | workspace + timetravel |
|
|
29
|
+
| `/api/storage` | `GET /:namespace` / `GET/PUT/DELETE /:namespace/:id` | RemotePersistence 线缆协议服务端 |
|
|
30
|
+
| `/api/setting` | `GET/PUT /` (PUT 501) / `GET /providers` / `GET /models` / `POST /verify-model` / `POST /mode\|autonomy\|thinking` (501) | 设置管理 |
|
|
31
|
+
| `/api/devtools` | `GET /status` / `GET /breakpoints` | Devtools Worker 桥接 |
|
|
32
|
+
| `/api/debugger` | 断点 CRUD / pause / resume / inject / state | 调试器 API |
|
|
33
|
+
| `/api/logs` | `GET /history` / `GET /stream` (SSE) | 日志查询与流式推送 |
|
|
34
|
+
| `/api/catalog` | Extension/sigil 目录暴露给前端 | 插件目录 |
|
|
35
|
+
|
|
36
|
+
## WebSocket
|
|
37
|
+
|
|
38
|
+
- 升级路由：`/ws`
|
|
39
|
+
- 可选 origin 白名单 + `?token=` Bearer 鉴权（fail-closed，timingSafeEqual）
|
|
40
|
+
- 客户端连接后订阅指定 session 的事件流（`Session.subscribe` / `Session.unsubscribe`）
|
|
41
|
+
- 消息格式：服务端→客户端为 discriminated union `{ type, data }`；客户端→服务端为
|
|
42
|
+
`{ method, params }` JSON-RPC 风格
|
|
43
|
+
|
|
44
|
+
## 安装
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
pnpm add @x-otto/service
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
或从仓库构建：
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
pnpm --filter @x-otto/service build
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## 快速开始
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
import { createApp } from '@x-otto/coding'
|
|
60
|
+
import { createCodingService } from '@x-otto/service'
|
|
61
|
+
|
|
62
|
+
const app = createApp(options)
|
|
63
|
+
await app.start()
|
|
64
|
+
|
|
65
|
+
const service = createCodingService(app, { port: 8417, host: '127.0.0.1' })
|
|
66
|
+
await service.start()
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## API
|
|
70
|
+
|
|
71
|
+
| 导出 | 类型 | 说明 |
|
|
72
|
+
|------|------|------|
|
|
73
|
+
| `CodingService` | `class` | 核心服务类（编排 WS Manager / bridges / InboundRouter） |
|
|
74
|
+
| `createCodingService` | `function` | 工厂函数 |
|
|
75
|
+
| `WebSocketManager` | `class` | WebSocket 连接管理 + 订阅 + 广播 |
|
|
76
|
+
| `EventBridge` | `class` | AgentSession 事件 → WS 映射 |
|
|
77
|
+
| `DebugBridge` | `class` | 调试协议桥接 |
|
|
78
|
+
| `InboundRouter` | `class` | 入站消息分发 |
|
|
79
|
+
| `encodeSessionEvent` | `function` | 会话事件 → Session.event 信封 |
|
|
80
|
+
| `createProjectorState` | `function` | 投影累加器创建 |
|
|
81
|
+
| `startPersistenced` | `function` | 独立存储服务启动 |
|
|
82
|
+
| `eventBus` | `instance` | 进程内 EventBus 单例 |
|
|
83
|
+
| `EventBus` | `class` | 事件总线类 |
|
|
84
|
+
|
|
85
|
+
## 目录概览
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
src/
|
|
89
|
+
coding-service.ts # 核心编排
|
|
90
|
+
create-app.ts # Hono 应用组装
|
|
91
|
+
websocket-manager.ts # WebSocket 连接管理
|
|
92
|
+
event-bridge.ts # 事件桥接
|
|
93
|
+
event-bus.ts # 进程内事件总线
|
|
94
|
+
trace-bridge.ts # trace tail → WS
|
|
95
|
+
debug-bridge.ts # 调试桥接
|
|
96
|
+
debug-event-router.ts # devtools 事件 → WS
|
|
97
|
+
inbound-router.ts # 入站消息分发
|
|
98
|
+
session-event-wire.ts # 会话事件 → 中性 SessionEvent（脱敏+封装）
|
|
99
|
+
message-serializer.ts # 消息序列化
|
|
100
|
+
persistenced-app.ts # 独立存储服务
|
|
101
|
+
types.ts # 核心类型
|
|
102
|
+
routes/ # 路由实现（chat/sessions/setting/storage/debugger/devtools/logs/catalog 等）
|
|
103
|
+
middleware/ # 中间件（request-id / access-log / rate-limit / storage-auth）
|
|
104
|
+
index.ts
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## 开发命令
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
pnpm --filter @x-otto/service build
|
|
111
|
+
pnpm --filter @x-otto/service typecheck
|
|
112
|
+
pnpm --filter @x-otto/service clean
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## 关联包
|
|
116
|
+
|
|
117
|
+
`@x-otto/agent`、`@x-otto/ai`、`@x-otto/coding`、`@x-otto/schedule`、`@x-otto/devtools`、`@x-otto/otel`、
|
|
118
|
+
`@x-otto/hooks`、`@x-otto/persistence`、`@x-otto/session-contract`、`@x-otto/shared`、`@x-otto/trace-view`、
|
|
119
|
+
`@x-otto/workspace`；外部依赖 `hono`、`@hono/node-server`、`ws`
|