@jsbot-tellus/core 2.2.0 → 2.4.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.
Files changed (116) hide show
  1. package/README.md +19 -0
  2. package/bot.config.example.json +3 -0
  3. package/dist/app.js +215 -98
  4. package/dist/app.js.map +1 -1
  5. package/dist/core/client.d.ts +1 -0
  6. package/dist/core/client.d.ts.map +1 -1
  7. package/dist/core/client.js +3 -0
  8. package/dist/core/client.js.map +1 -1
  9. package/dist/core/config/schema.d.ts +19 -0
  10. package/dist/core/config/schema.d.ts.map +1 -1
  11. package/dist/core/config/schema.js +37 -0
  12. package/dist/core/config/schema.js.map +1 -1
  13. package/dist/core/dispatch/router.d.ts +3 -0
  14. package/dist/core/dispatch/router.d.ts.map +1 -1
  15. package/dist/core/dispatch/router.js +13 -0
  16. package/dist/core/dispatch/router.js.map +1 -1
  17. package/dist/core/index.d.ts +2 -2
  18. package/dist/core/index.d.ts.map +1 -1
  19. package/dist/core/index.js.map +1 -1
  20. package/dist/core/kernel.d.ts +8 -0
  21. package/dist/core/kernel.d.ts.map +1 -1
  22. package/dist/core/kernel.js +17 -0
  23. package/dist/core/kernel.js.map +1 -1
  24. package/dist/core/logging/log-buffer.d.ts +27 -0
  25. package/dist/core/logging/log-buffer.d.ts.map +1 -0
  26. package/dist/core/logging/log-buffer.js +71 -0
  27. package/dist/core/logging/log-buffer.js.map +1 -0
  28. package/dist/core/logging/logger.d.ts +3 -0
  29. package/dist/core/logging/logger.d.ts.map +1 -1
  30. package/dist/core/logging/logger.js +6 -3
  31. package/dist/core/logging/logger.js.map +1 -1
  32. package/dist/core/plugin/command-params.d.ts +2 -2
  33. package/dist/core/plugin/command-params.d.ts.map +1 -1
  34. package/dist/core/plugin/command-params.js +35 -0
  35. package/dist/core/plugin/command-params.js.map +1 -1
  36. package/dist/core/storage/session.d.ts +15 -0
  37. package/dist/core/storage/session.d.ts.map +1 -1
  38. package/dist/core/storage/session.js +55 -0
  39. package/dist/core/storage/session.js.map +1 -1
  40. package/dist/core/web/api.d.ts +16 -0
  41. package/dist/core/web/api.d.ts.map +1 -0
  42. package/dist/core/web/api.js +617 -0
  43. package/dist/core/web/api.js.map +1 -0
  44. package/dist/core/web/auth.d.ts +43 -0
  45. package/dist/core/web/auth.d.ts.map +1 -0
  46. package/dist/core/web/auth.js +161 -0
  47. package/dist/core/web/auth.js.map +1 -0
  48. package/dist/core/web/config-store.d.ts +30 -0
  49. package/dist/core/web/config-store.d.ts.map +1 -0
  50. package/dist/core/web/config-store.js +216 -0
  51. package/dist/core/web/config-store.js.map +1 -0
  52. package/dist/core/web/event-feed.d.ts +26 -0
  53. package/dist/core/web/event-feed.d.ts.map +1 -0
  54. package/dist/core/web/event-feed.js +107 -0
  55. package/dist/core/web/event-feed.js.map +1 -0
  56. package/dist/core/web/http.d.ts +39 -0
  57. package/dist/core/web/http.d.ts.map +1 -0
  58. package/dist/core/web/http.js +233 -0
  59. package/dist/core/web/http.js.map +1 -0
  60. package/dist/core/web/index.d.ts +11 -0
  61. package/dist/core/web/index.d.ts.map +1 -0
  62. package/dist/core/web/index.js +6 -0
  63. package/dist/core/web/index.js.map +1 -0
  64. package/dist/core/web/server.d.ts +30 -0
  65. package/dist/core/web/server.d.ts.map +1 -0
  66. package/dist/core/web/server.js +437 -0
  67. package/dist/core/web/server.js.map +1 -0
  68. package/dist/core/web/types.d.ts +84 -0
  69. package/dist/core/web/types.d.ts.map +1 -0
  70. package/dist/core/web/types.js +2 -0
  71. package/dist/core/web/types.js.map +1 -0
  72. package/dist/webui/assets/ActionsView-BDuXBWG1.js +1 -0
  73. package/dist/webui/assets/ActionsView-Ciib5lC6.css +1 -0
  74. package/dist/webui/assets/ConfigView-B3Gv2uRG.js +1 -0
  75. package/dist/webui/assets/ConfigView-CrEpss2y.css +1 -0
  76. package/dist/webui/assets/DashboardView-DR6yCaqs.css +1 -0
  77. package/dist/webui/assets/DashboardView-n9LGPmQL.js +1 -0
  78. package/dist/webui/assets/EventsView-DhO8twWb.js +1 -0
  79. package/dist/webui/assets/EventsView-PMkYKxZ-.css +1 -0
  80. package/dist/webui/assets/KvView-BCz_dOVC.js +1 -0
  81. package/dist/webui/assets/KvView-CaMvbxUz.css +1 -0
  82. package/dist/webui/assets/LoginView-BVnFkwSW.css +1 -0
  83. package/dist/webui/assets/LoginView-Br3_AC5z.js +1 -0
  84. package/dist/webui/assets/LogsView-Ba_12frI.js +1 -0
  85. package/dist/webui/assets/LogsView-NR4L1-XY.css +1 -0
  86. package/dist/webui/assets/MainLayout-D2LTc57u.js +1 -0
  87. package/dist/webui/assets/MainLayout-glfVNbMz.css +1 -0
  88. package/dist/webui/assets/PluginsView-DL9OxGph.css +1 -0
  89. package/dist/webui/assets/PluginsView-vQKBSCU8.js +1 -0
  90. package/dist/webui/assets/SessionsView-DSl37qpo.js +1 -0
  91. package/dist/webui/assets/SessionsView-p-u3JGTV.css +1 -0
  92. package/dist/webui/assets/api-CNzxhTWe.js +3 -0
  93. package/dist/webui/assets/index-CUvpnClx.js +50 -0
  94. package/dist/webui/assets/index-CePlRZX6.css +1 -0
  95. package/dist/webui/index.html +110 -0
  96. package/docs/plugin-api.md +1 -0
  97. package/docs/webui.md +142 -0
  98. package/package.json +14 -3
  99. package/src/app.ts +286 -118
  100. package/src/core/client.ts +4 -0
  101. package/src/core/config/schema.ts +40 -0
  102. package/src/core/dispatch/router.ts +15 -0
  103. package/src/core/index.ts +3 -0
  104. package/src/core/kernel.ts +25 -1
  105. package/src/core/logging/log-buffer.ts +109 -0
  106. package/src/core/logging/logger.ts +7 -3
  107. package/src/core/plugin/command-params.ts +48 -2
  108. package/src/core/storage/session.ts +95 -0
  109. package/src/core/web/api.ts +932 -0
  110. package/src/core/web/auth.ts +245 -0
  111. package/src/core/web/config-store.ts +333 -0
  112. package/src/core/web/event-feed.ts +163 -0
  113. package/src/core/web/http.ts +340 -0
  114. package/src/core/web/index.ts +25 -0
  115. package/src/core/web/server.ts +621 -0
  116. package/src/core/web/types.ts +100 -0
package/dist/webui/index.html ADDED
@@ -0,0 +1,110 @@
1
+ <!doctype html>
2
+ <html lang="zh-CN" class="dark">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta
6
+ name="viewport"
7
+ content="width=device-width, initial-scale=1.0, viewport-fit=cover"
8
+ />
9
+ <meta name="theme-color" content="#0a0f1a" />
10
+ <!-- WebUI is an admin surface; tell compliant crawlers to skip it. -->
11
+ <meta name="robots" content="noindex, nofollow, noarchive, nosnippet" />
12
+ <title>JsBot WebUI</title>
13
+ <!--
14
+ Pre-paint appearance bootstrap: applies the cached appearance to
15
+ <html> before the bundle mounts, so mode / dark intensity / density
16
+ / scale / radius never flash from the defaults. Defensive: never
17
+ breaks page load. CSP (script-src 'self' + its sha256 hash)
18
+ authorizes this exact block; the bundle re-applies authoritatively.
19
+ -->
20
+ <script>
21
+ ;(function () {
22
+ try {
23
+ var raw = localStorage.getItem('jsbot-webui-appearance')
24
+ var a = raw ? JSON.parse(raw) : {}
25
+ if (!a || typeof a !== 'object') a = {}
26
+ var root = document.documentElement
27
+ var mode = a.mode
28
+ var prefersDark =
29
+ window.matchMedia &&
30
+ window.matchMedia('(prefers-color-scheme: dark)')
31
+ .matches
32
+ var resolved =
33
+ mode === 'light' || mode === 'dark'
34
+ ? mode
35
+ : prefersDark
36
+ ? 'dark'
37
+ : 'light'
38
+ root.classList.remove('light', 'dark')
39
+ root.classList.add(resolved)
40
+ root.setAttribute('data-theme', resolved)
41
+ root.style.colorScheme = resolved
42
+ var themeMeta = document.querySelector(
43
+ 'meta[name="theme-color"]'
44
+ )
45
+ if (themeMeta)
46
+ themeMeta.setAttribute(
47
+ 'content',
48
+ resolved === 'dark' ? '#0a0f1a' : '#f4f7fb'
49
+ )
50
+ if (
51
+ resolved === 'dark' &&
52
+ (a.darkIntensity === 'black' ||
53
+ a.darkIntensity === 'soft')
54
+ ) {
55
+ root.setAttribute(
56
+ 'data-dark-intensity',
57
+ a.darkIntensity
58
+ )
59
+ }
60
+ if (a.density === 'compact' || a.density === 'cozy')
61
+ root.setAttribute('data-density', a.density)
62
+ if (
63
+ a.sidebarStyle === 'follow' ||
64
+ a.sidebarStyle === 'panel' ||
65
+ a.sidebarStyle === 'accent'
66
+ ) {
67
+ root.setAttribute('data-sidebar-style', a.sidebarStyle)
68
+ }
69
+ root.setAttribute(
70
+ 'data-contrast',
71
+ a.highContrast ? 'high' : 'normal'
72
+ )
73
+ var systemReduce =
74
+ window.matchMedia &&
75
+ window.matchMedia('(prefers-reduced-motion: reduce)')
76
+ .matches
77
+ root.setAttribute(
78
+ 'data-reduce-motion',
79
+ a.reduceMotion || systemReduce ? '1' : '0'
80
+ )
81
+ if (a.disableMotion)
82
+ root.setAttribute('data-no-motion', '1')
83
+ if (
84
+ typeof a.radius === 'number' &&
85
+ a.radius >= 0 &&
86
+ a.radius <= 2
87
+ ) {
88
+ root.style.setProperty('--app-radius', a.radius + 'rem')
89
+ }
90
+ if (
91
+ typeof a.uiScale === 'number' &&
92
+ a.uiScale >= 0.5 &&
93
+ a.uiScale <= 2
94
+ ) {
95
+ root.style.fontSize =
96
+ Math.round(16 * a.uiScale * 100) / 100 + 'px'
97
+ }
98
+ } catch (e) {
99
+ /* ignore — fall back to the default theme */
100
+ }
101
+ })()
102
+ </script>
103
+ <script type="module" crossorigin src="/assets/index-CUvpnClx.js"></script>
104
+ <link rel="modulepreload" crossorigin href="/assets/api-CNzxhTWe.js">
105
+ <link rel="stylesheet" crossorigin href="/assets/index-CePlRZX6.css">
106
+ </head>
107
+ <body>
108
+ <div id="app"></div>
109
+ </body>
110
+ </html>
package/docs/plugin-api.md CHANGED
@@ -256,6 +256,7 @@ ctx.commands.register(
256
256
  - `number`：有限数字，包括小数。
257
257
  - `integer`：整数。
258
258
  - `boolean`：`true/false`、`1/0`、`yes/no`、`y/n`、`on/off`，大小写不敏感。
259
+ - `at`：@ 提及或 QQ 号，解析为数字。支持 `[CQ:at,qq=123456]`（可带 `name` 等附加参数）和纯数字 `123456`；`@全体成员` 和普通文本会报类型错误，且不能声明默认值。
259
260
  - `[...rest]`：把剩余 token 依次收集为字符串；只能放在最后，且没有必填形式。
260
261
 
261
262
  固定参数可以用双引号或单引号包裹，例如 `/ask "hello world" 2` 会把 `hello world` 作为一个 token；引号内的反斜杠用于转义。
package/docs/webui.md ADDED
@@ -0,0 +1,142 @@
1
+ # WebUI
2
+
3
+ WebUI 是 JsBot-Tellus 的可选管理后台，默认关闭。它提供运行状态、会话、插件、配置、KV、日志、事件和原始 OneBot action 的管理能力。
4
+
5
+ WebUI 是**完全特权**接口：登录后可以修改机器人配置、安装插件、发送消息和调用任意 OneBot action。默认只监听 `127.0.0.1`；如果需要远程访问，请放在 HTTPS 反向代理后面，不要直接暴露到公网。
6
+
7
+ ## 启用
8
+
9
+ 在 `bot.config.json` 顶层增加：
10
+
11
+ ```json
12
+ {
13
+ "webui": {
14
+ "enabled": true,
15
+ "host": "127.0.0.1",
16
+ "port": 8787,
17
+ "username": "admin",
18
+ "password": "至少 8 位",
19
+ "sessionTtlHours": 12,
20
+ "trustProxy": false
21
+ }
22
+ }
23
+ ```
24
+
25
+ `enabled: true` 时 `username` 和 `password` 必填，密码至少 8 位。启动后访问：
26
+
27
+ ```text
28
+ http://127.0.0.1:8787
29
+ ```
30
+
31
+ 默认账号密码就是你写在配置里的值。修改 `username`/`password` 后保存配置，运行时会重启并清空已有登录会话；`enabled`、`host`、`port` 修改后需要重启进程才会重新绑定端口。
32
+
33
+ ## 配置项
34
+
35
+ | 字段 | 默认值 | 说明 |
36
+ | ----------------- | ----------- | -------------------------------------------------------------- |
37
+ | `enabled` | `false` | 是否启动 WebUI |
38
+ | `host` | `127.0.0.1` | 监听地址；非回环地址会在日志中给出安全警告 |
39
+ | `port` | `8787` | 监听端口 |
40
+ | `username` | 无 | 登录用户名，启用时必填 |
41
+ | `password` | 无 | 登录密码，启用时必填，至少 8 位 |
42
+ | `sessionTtlHours` | `12` | 登录会话有效期，单位小时 |
43
+ | `trustProxy` | `false` | 是否信任 `X-Forwarded-For` / `X-Forwarded-Proto`（反向代理时） |
44
+
45
+ ## 功能
46
+
47
+ - **概览**：连接状态、Bot 账号、运行时长、插件/会话数量、最近事件和日志。
48
+ - **会话**：浏览 Session、搜索、发送 QQ 消息、追加 LLM 消息、编辑 provider/model/persona、清空和删除。
49
+ - **插件**：查看插件状态、启用/私聊/群组 gating、编辑插件配置、安装/更新/卸载 npm 插件包。
50
+ - **配置**：常用设置表单 + 完整 JSON 编辑器，支持校验、保存、自动重启和失败回滚。
51
+ - **KV**：按插件查看、编辑、删除 `plugin_kv` 数据。
52
+ - **日志**：按级别/scope/关键字过滤，SSE 实时推送。
53
+ - **事件**：实时消息、通知、请求和 meta 事件流。
54
+ - **调试**：直接调用 OneBot action。
55
+
56
+ 插件安装、配置保存和手动重启都会重启运行时，机器人会短暂断线；WebUI 本身会保持在线。
57
+
58
+ ### 配置保存
59
+
60
+ 配置页保存时：
61
+
62
+ 1. 用 `appConfigSchema` 和每个已加载插件的 `configSchema` 校验；
63
+ 2. 检查配置文件 hash，防止覆盖外部修改；
64
+ 3. 备份当前文件到 `bot.config.json.bak`；
65
+ 4. 原子写入新配置；
66
+ 5. 重启运行时；
67
+ 6. 如果启动失败，自动恢复旧配置并再次重启。
68
+
69
+ `accessToken` 和 `webui.password` 在页面中始终脱敏显示，留空表示保持原值。
70
+
71
+ ### 启动失败
72
+
73
+ 当 `webui.enabled=true` 且 Kernel 启动失败（WebSocket 连不上、插件 setup 失败等）时，进程会保留 WebUI 在线，页面显示错误。可以在配置页修正问题后直接重启运行时，不需要手动改文件。
74
+
75
+ 如果配置文件本身 JSON 或 schema 错误，进程仍会在启动前退出，此时 WebUI 无法启动。
76
+
77
+ ## 安全
78
+
79
+ - 密码使用 `scrypt` 哈希后比较，配置文件中的密码是明文（和 `accessToken` 一样，请限制文件权限）。
80
+ - 登录失败按 IP 限流（15 分钟 5 次）。
81
+ - 会话使用随机 token、`HttpOnly`、`SameSite=Strict` Cookie；默认 12 小时过期。
82
+ - 修改类请求要求 `X-Requested-With: jsbot-webui` 并校验 `Origin`。
83
+ - 静态资源路径穿越、请求体大小、SSE 连接数都有上限。
84
+ - 响应带 CSP、`X-Frame-Options: DENY`、`nosniff`、`Referrer-Policy` 等安全头。
85
+
86
+ ### 反向代理
87
+
88
+ 推荐使用 Nginx/Caddy 终止 TLS，并只允许可信网络访问：
89
+
90
+ ```nginx
91
+ location / {
92
+ proxy_pass http://127.0.0.1:8787;
93
+ proxy_set_header Host $host;
94
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
95
+ proxy_set_header X-Forwarded-Proto $scheme;
96
+ proxy_buffering off; # SSE
97
+ }
98
+ ```
99
+
100
+ 同时设置 `webui.trustProxy: true`，让服务端正确识别客户端 IP 和 HTTPS Cookie。注意反向代理必须保留原始 `Host`，否则写请求的 `Origin` 校验会失败。
101
+
102
+ ## 开发
103
+
104
+ ```bash
105
+ npm run dev:webui # Vite 开发服务器，/api 代理到 127.0.0.1:8787
106
+ npm run check:webui # vue-tsc 类型检查
107
+ npm run build:webui # 构建到 dist/webui
108
+ ```
109
+
110
+ 后端仍用：
111
+
112
+ ```bash
113
+ npm run start:source
114
+ # 或
115
+ npm run dev
116
+ ```
117
+
118
+ Vite 页面地址默认是 `http://127.0.0.1:5173`。生产构建后由 `node dist/app.js` 直接提供 `dist/webui` 静态资源。
119
+
120
+ ## API
121
+
122
+ 所有接口返回 `{ "data": ... }` 或 `{ "error": { "message": "...", "details": ... } }`。除 `/api/health` 和登录接口外都需要登录 Cookie。
123
+
124
+ | 分类 | 接口 |
125
+ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
126
+ | 认证 | `POST /api/auth/login`、`POST /api/auth/logout`、`GET /api/auth/me` |
127
+ | 状态 | `GET /api/status`、`GET /api/commands`、`POST /api/runtime/restart`、`POST /api/runtime/pause`、`POST /api/runtime/resume` |
128
+ | 日志 | `GET /api/logs`、`GET /api/logs/stream`（SSE） |
129
+ | 事件 | `GET /api/events`、`GET /api/events/stream`（SSE） |
130
+ | 会话 | `GET /api/sessions`、`GET /api/sessions/:id`、`PUT /api/sessions/:id`、`POST /api/sessions/:id/messages`、`POST /api/sessions/:id/send`、`DELETE /api/sessions/:id` |
131
+ | 插件 | `GET /api/plugins`、`PUT /api/plugins/:id/config`、`POST /api/plugins/install`、`POST /api/plugins/update`、`POST /api/plugins/remove` |
132
+ | 配置 | `GET /api/config`、`POST /api/config/validate`、`PUT /api/config` |
133
+ | KV | `GET /api/kv/plugins`、`GET /api/kv`、`PUT /api/kv`、`DELETE /api/kv` |
134
+ | 调试 | `POST /api/actions` |
135
+
136
+ ## 故障排查
137
+
138
+ - **页面空白/提示缺少静态资源**：先执行 `npm run build`，确认 `dist/webui/index.html` 存在。
139
+ - **端口被占用**：修改 `webui.port` 后重启进程；如果 WebUI 已启用但绑定失败，日志会记录错误，机器人仍会继续启动。
140
+ - **登录后一直 401**：检查浏览器是否禁用 Cookie；反向代理是否改写 `Host`/`Origin`；`trustProxy` 是否配置正确。
141
+ - **保存配置返回 409**：配置文件被外部修改，刷新页面后重新编辑。
142
+ - **保存后机器人断线**：保存配置会重启运行时，连接恢复后自动上线。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jsbot-tellus/core",
3
- "version": "2.2.0",
3
+ "version": "2.4.0",
4
4
  "engines": {
5
5
  "node": "^24.22.1 || >=26.12.1"
6
6
  },
@@ -47,12 +47,15 @@
47
47
  "test": "vitest run",
48
48
  "check": "tsc --noEmit",
49
49
  "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
50
- "build": "npm run clean && tsc -p tsconfig.build.json && node -e \"require('node:fs').chmodSync('dist/app.js', 0o755)\"",
50
+ "build": "npm run clean && npm run build:webui && tsc -p tsconfig.build.json && node -e \"require('node:fs').chmodSync('dist/app.js', 0o755)\"",
51
51
  "prepack": "npm run build",
52
52
  "prepublishOnly": "npm run check && npm test",
53
53
  "build:local": "npm run build --prefix plugins/poke && npm run build --prefix plugins/llm",
54
54
  "check:local": "npm run check --prefix plugins/poke && npm run check --prefix plugins/llm",
55
55
  "plugin:gen": "tsx scripts/plugin-gen.ts",
56
+ "dev:webui": "vite --config webui/vite.config.ts",
57
+ "check:webui": "node scripts/webui-check.cjs",
58
+ "build:webui": "vite build --config webui/vite.config.ts",
56
59
  "start": "node dist/app.js",
57
60
  "start:build": "npm run build && node dist/app.js",
58
61
  "start:source": "tsx src/app.ts",
@@ -69,10 +72,18 @@
69
72
  "zod": "^4.6.7"
70
73
  },
71
74
  "devDependencies": {
75
+ "@element-plus/icons-vue": "^2.3.2",
72
76
  "@types/node": "^24.6.4",
77
+ "@vitejs/plugin-vue": "^6.0.10",
78
+ "element-plus": "^2.14.7",
73
79
  "prettier": "^3.9.10",
74
80
  "tsx": "^4.23.15",
75
81
  "typescript": "^7.0.2",
76
- "vitest": "^5.0.4"
82
+ "typescript5": "npm:typescript@5.9.3",
83
+ "vite": "^8.3.5",
84
+ "vitest": "^5.0.4",
85
+ "vue": "^3.5.44",
86
+ "vue-router": "^5.4.0",
87
+ "vue-tsc": "^3.3.13"
77
88
  }
78
89
  }