@lendle/classroomai 0.0.0-stage → 0.5.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/config/config.json +4 -0
- package/main.js +342 -0
- package/package.json +25 -4
- package/relay/engine.js +96 -0
- package/relay/limiter.js +65 -0
- package/relay/log.js +176 -0
- package/relay/openrouter.js +92 -0
- package/relay/payload-log.js +127 -0
- package/relay/protocol.js +76 -0
- package/relay/runtime.js +66 -0
- package/relay/server.js +292 -0
- package/relay/session.js +71 -0
- package/relay/state.js +80 -0
- package/relay/template.js +158 -0
- package/relay/websocket.js +311 -0
- package/standalone.js +72 -0
- package/README.md +0 -3
|
@@ -0,0 +1,311 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Teacher WebSocket client(與 Python 版 websocket.py 對齊)。
|
|
3
|
+
*
|
|
4
|
+
* - register(帶 PIN/templateId)→ config(desired state + 加密 credential)
|
|
5
|
+
* - 收到 config 套用 state、解密 credential;沒有 credential 時載入 .conf/fallback.bin
|
|
6
|
+
* - 收到 project-template 存 pending;CLI 模式(autoTemplateDir)自動原子安裝
|
|
7
|
+
* - heartbeat:首次隨機延遲、間隔 ±20% jitter;session 統計第 1 次與每 10 次送
|
|
8
|
+
* - 斷線自動重連(backoff 1s→30s);連線前先確保 API key(fallback 可用)
|
|
9
|
+
*/
|
|
10
|
+
"use strict";
|
|
11
|
+
|
|
12
|
+
const fs = require("fs");
|
|
13
|
+
const path = require("path");
|
|
14
|
+
const { WebSocket } = require("ws");
|
|
15
|
+
const { makeRegister, makeHeartbeat, parseMessage } = require("./protocol");
|
|
16
|
+
const { deriveKey, decryptCredential, decryptFallbackBin } = require("./session");
|
|
17
|
+
const { applyTemplate, extractTemplateZip } = require("./template");
|
|
18
|
+
const { logTemplateInstalled, logTemplateFailed, relayLogger } = require("./log");
|
|
19
|
+
|
|
20
|
+
/** 嚴格模式:template 記錄寫入失敗 → 終止程式(測試可替換) */
|
|
21
|
+
const safety = {
|
|
22
|
+
fatalExit(code = 1) {
|
|
23
|
+
process.exit(code);
|
|
24
|
+
},
|
|
25
|
+
};
|
|
26
|
+
|
|
27
|
+
function sleep(ms) {
|
|
28
|
+
return new Promise((resolve) => setTimeout(resolve, ms));
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
class TeacherClient {
|
|
32
|
+
constructor(engine, host, port, studentId, pin, opts = {}) {
|
|
33
|
+
this.engine = engine;
|
|
34
|
+
this.host = host;
|
|
35
|
+
this.port = port;
|
|
36
|
+
this.studentId = studentId;
|
|
37
|
+
this.pin = pin; // 只存記憶體
|
|
38
|
+
this.heartbeatInterval = opts.heartbeatInterval ?? 10;
|
|
39
|
+
this.autoTemplateDir = opts.autoTemplateDir ?? null;
|
|
40
|
+
this.templateId = opts.templateId ?? "default";
|
|
41
|
+
|
|
42
|
+
this.connected = false;
|
|
43
|
+
this.lastError = null;
|
|
44
|
+
this._stop = false;
|
|
45
|
+
this._ws = null;
|
|
46
|
+
this._salt = "";
|
|
47
|
+
this._lastInstalledVersion = 0;
|
|
48
|
+
this._hbCount = 0;
|
|
49
|
+
this._fallbackWarned = false;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
_log() {
|
|
53
|
+
return relayLogger();
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** 主迴圈:連線 / register / heartbeat;斷線自動重連(backoff 1→30s) */
|
|
57
|
+
async run() {
|
|
58
|
+
let backoff = 1.0;
|
|
59
|
+
while (!this._stop) {
|
|
60
|
+
// 連線前先確保 API key:Teacher 連不上也能用 .conf/fallback.bin(free only)
|
|
61
|
+
this._ensureApiKey();
|
|
62
|
+
try {
|
|
63
|
+
await this._connectOnce();
|
|
64
|
+
backoff = 1.0;
|
|
65
|
+
} catch (e) {
|
|
66
|
+
this.lastError = e && e.message ? e.message : String(e);
|
|
67
|
+
this.connected = false;
|
|
68
|
+
this._ws = null;
|
|
69
|
+
if (this._stop) break;
|
|
70
|
+
await sleep((backoff + Math.random() * 0.5) * 1000);
|
|
71
|
+
backoff = Math.min(backoff * 2, 30.0);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
stop() {
|
|
77
|
+
this._stop = true;
|
|
78
|
+
if (this._ws) {
|
|
79
|
+
try {
|
|
80
|
+
this._ws.close();
|
|
81
|
+
} catch {
|
|
82
|
+
/* 忽略 */
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
_connectOnce() {
|
|
88
|
+
return new Promise((resolve, reject) => {
|
|
89
|
+
const ws = new WebSocket(`ws://${this.host}:${this.port}`);
|
|
90
|
+
let settled = false;
|
|
91
|
+
|
|
92
|
+
const finish = (err) => {
|
|
93
|
+
if (settled) return;
|
|
94
|
+
settled = true;
|
|
95
|
+
this.connected = false;
|
|
96
|
+
if (this._ws === ws) this._ws = null;
|
|
97
|
+
if (err) reject(err);
|
|
98
|
+
else resolve();
|
|
99
|
+
};
|
|
100
|
+
|
|
101
|
+
ws.on("open", () => {
|
|
102
|
+
this._ws = ws;
|
|
103
|
+
this.connected = true;
|
|
104
|
+
this.lastError = null;
|
|
105
|
+
try {
|
|
106
|
+
ws.send(
|
|
107
|
+
JSON.stringify(makeRegister(this.engine.state.relayId, this.studentId, this.pin, this.templateId))
|
|
108
|
+
);
|
|
109
|
+
} catch (e) {
|
|
110
|
+
finish(e);
|
|
111
|
+
return;
|
|
112
|
+
}
|
|
113
|
+
this._startHeartbeat(ws, () => settled);
|
|
114
|
+
});
|
|
115
|
+
|
|
116
|
+
ws.on("message", (raw) => {
|
|
117
|
+
this._onMessage(raw).catch((e) => {
|
|
118
|
+
this._log().warning(`message handler error: ${e.message}`);
|
|
119
|
+
});
|
|
120
|
+
});
|
|
121
|
+
|
|
122
|
+
ws.on("close", () => finish());
|
|
123
|
+
ws.on("error", (e) => {
|
|
124
|
+
this.lastError = e && e.message ? e.message : String(e);
|
|
125
|
+
finish(e);
|
|
126
|
+
});
|
|
127
|
+
});
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
_startHeartbeat(ws, isSettled) {
|
|
131
|
+
const loop = async () => {
|
|
132
|
+
// 首次隨機延遲 0–interval(避免全班同秒上線)
|
|
133
|
+
await sleep(Math.random() * this.heartbeatInterval * 1000);
|
|
134
|
+
while (!isSettled() && !this._stop) {
|
|
135
|
+
this._hbCount += 1;
|
|
136
|
+
const includeSession = this._hbCount === 1 || this._hbCount % 10 === 0;
|
|
137
|
+
try {
|
|
138
|
+
ws.send(JSON.stringify(makeHeartbeat(this._report(includeSession))));
|
|
139
|
+
} catch (e) {
|
|
140
|
+
this._log().warning(`heartbeat send failed: ${e.message}`);
|
|
141
|
+
return;
|
|
142
|
+
}
|
|
143
|
+
await sleep(this._nextInterval() * 1000);
|
|
144
|
+
}
|
|
145
|
+
};
|
|
146
|
+
loop().catch(() => {
|
|
147
|
+
/* 連線結束 */
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
_nextInterval() {
|
|
152
|
+
return this.heartbeatInterval * (0.8 + Math.random() * 0.4);
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
_report(includeSession) {
|
|
156
|
+
const engine = this.engine;
|
|
157
|
+
const st = engine.state;
|
|
158
|
+
return {
|
|
159
|
+
relayId: st.relayId,
|
|
160
|
+
status: st.status,
|
|
161
|
+
usage: engine.usageSnapshot(),
|
|
162
|
+
activeRequests: engine.activeRequests,
|
|
163
|
+
errorCount: engine.errorCount,
|
|
164
|
+
policyVersion: st.policyVersion,
|
|
165
|
+
templateVersion: st.templateVersion,
|
|
166
|
+
modelRoutingVersion: st.modelRoutingVersion,
|
|
167
|
+
usingFallbackKey: engine.usingFallbackKey,
|
|
168
|
+
sessionStats: () => (includeSession ? engine.sessionStats() : null),
|
|
169
|
+
};
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
async _onMessage(raw) {
|
|
173
|
+
let msg;
|
|
174
|
+
try {
|
|
175
|
+
msg = parseMessage(raw);
|
|
176
|
+
} catch {
|
|
177
|
+
return;
|
|
178
|
+
}
|
|
179
|
+
const payload = msg.payload || {};
|
|
180
|
+
if (msg.type === "config") {
|
|
181
|
+
this.engine.state.applyConfig(payload);
|
|
182
|
+
const credentialApplied = this._storeApiKey(payload);
|
|
183
|
+
this._ensureApiKey({ credentialApplied });
|
|
184
|
+
if (this.engine.usingFallbackKey) this._forceFree();
|
|
185
|
+
return;
|
|
186
|
+
}
|
|
187
|
+
if (msg.type === "project-template") {
|
|
188
|
+
const st = this.engine.state;
|
|
189
|
+
st.pendingTemplateName = payload.name !== undefined ? payload.name : st.pendingTemplateName;
|
|
190
|
+
st.pendingTemplateVersion =
|
|
191
|
+
payload.version !== undefined ? payload.version : st.pendingTemplateVersion;
|
|
192
|
+
st.pendingTemplateFiles = payload.files || {};
|
|
193
|
+
// 只採用本次訊息的 zip(缺漏時不沿用舊版)
|
|
194
|
+
st.pendingTemplateZipB64 = payload.zip && payload.zip.base64 ? payload.zip.base64 : null;
|
|
195
|
+
if (this.autoTemplateDir) await this._autoApplyTemplate();
|
|
196
|
+
return;
|
|
197
|
+
}
|
|
198
|
+
if (msg.type === "command") {
|
|
199
|
+
if (payload.command === "disable") this.engine.state.status = "disabled";
|
|
200
|
+
else if (payload.command === "enable") this.engine.state.status = "enabled";
|
|
201
|
+
return;
|
|
202
|
+
}
|
|
203
|
+
if (msg.type === "error") {
|
|
204
|
+
this.lastError = payload.message || "unknown error";
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/** 解密 credential 並存入記憶體;回傳本次是否真的套用了 Teacher credential */
|
|
209
|
+
_storeApiKey(payload) {
|
|
210
|
+
const credential = payload.credential;
|
|
211
|
+
if (!credential) return false;
|
|
212
|
+
if (payload.salt) this._salt = payload.salt;
|
|
213
|
+
try {
|
|
214
|
+
const key = deriveKey(this.pin, this._salt);
|
|
215
|
+
this.engine.apiKey = decryptCredential(key, credential);
|
|
216
|
+
return true;
|
|
217
|
+
} catch {
|
|
218
|
+
this.lastError = "credential 解密失敗";
|
|
219
|
+
return false;
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
_loadFallbackKey() {
|
|
224
|
+
const p = path.join(process.cwd(), ".conf", "fallback.bin");
|
|
225
|
+
if (!fs.existsSync(p)) return null;
|
|
226
|
+
try {
|
|
227
|
+
return decryptFallbackBin(fs.readFileSync(p));
|
|
228
|
+
} catch (e) {
|
|
229
|
+
if (!this._fallbackWarned) {
|
|
230
|
+
this._log().warning(`fallback.bin 無法使用:${e.message}`);
|
|
231
|
+
this._fallbackWarned = true;
|
|
232
|
+
}
|
|
233
|
+
return null;
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
_forceFree() {
|
|
238
|
+
this.engine.state.primaryModel = "openrouter/free";
|
|
239
|
+
this.engine.state.models = [];
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/**
|
|
243
|
+
* 取得 API key:Teacher credential 優先;沒有時才用 fallback(強制 openrouter/free)。
|
|
244
|
+
* @param {{credentialApplied?:boolean}} [opts]
|
|
245
|
+
*/
|
|
246
|
+
_ensureApiKey(opts = {}) {
|
|
247
|
+
const credentialApplied = !!opts.credentialApplied;
|
|
248
|
+
const engine = this.engine;
|
|
249
|
+
if (engine.apiKey) {
|
|
250
|
+
if (credentialApplied && engine.usingFallbackKey) {
|
|
251
|
+
engine.usingFallbackKey = false;
|
|
252
|
+
this._log().info("credential 已取得,停用 fallback key");
|
|
253
|
+
}
|
|
254
|
+
return;
|
|
255
|
+
}
|
|
256
|
+
const fallback = this._loadFallbackKey();
|
|
257
|
+
if (!fallback) return;
|
|
258
|
+
engine.apiKey = fallback;
|
|
259
|
+
engine.usingFallbackKey = true;
|
|
260
|
+
this._forceFree();
|
|
261
|
+
this._log().warning("using fallback api key(強制 openrouter/free)");
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
/** CLI 模式自動下載樣板:成功(含記錄)才前進 installed 版本 */
|
|
265
|
+
async _autoApplyTemplate() {
|
|
266
|
+
const st = this.engine.state;
|
|
267
|
+
const name = st.pendingTemplateName || st.templateName;
|
|
268
|
+
const version = st.pendingTemplateVersion;
|
|
269
|
+
const zipB64 = st.pendingTemplateZipB64;
|
|
270
|
+
const files = st.pendingTemplateFiles || {};
|
|
271
|
+
|
|
272
|
+
if (!zipB64 && Object.keys(files).length === 0) {
|
|
273
|
+
logTemplateFailed(name, version, this.autoTemplateDir, "no-content", "沒有任何樣板內容");
|
|
274
|
+
return;
|
|
275
|
+
}
|
|
276
|
+
if (version && version === this._lastInstalledVersion) return; // 同版本重送
|
|
277
|
+
|
|
278
|
+
let written;
|
|
279
|
+
try {
|
|
280
|
+
written = zipB64
|
|
281
|
+
? extractTemplateZip(Buffer.from(zipB64, "base64"), this.autoTemplateDir)
|
|
282
|
+
: applyTemplate(files, this.autoTemplateDir);
|
|
283
|
+
} catch (e) {
|
|
284
|
+
logTemplateFailed(name, version, this.autoTemplateDir, "extract", e.message);
|
|
285
|
+
console.error(
|
|
286
|
+
`[relay] 樣板安裝失敗(解壓/寫檔):${e.message};版本維持 v${st.templateVersion},等待 Teacher 重送`
|
|
287
|
+
);
|
|
288
|
+
return;
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
try {
|
|
292
|
+
logTemplateInstalled(name, version, this.autoTemplateDir, written.length, "auto");
|
|
293
|
+
} catch (e) {
|
|
294
|
+
logTemplateFailed(name, version, this.autoTemplateDir, "log", e.message);
|
|
295
|
+
console.error(
|
|
296
|
+
`[relay] 致命錯誤:template 記錄寫入失敗(${e.message});嚴格模式終止程式`
|
|
297
|
+
);
|
|
298
|
+
safety.fatalExit(1);
|
|
299
|
+
return;
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
st.templateName = name;
|
|
303
|
+
st.templateVersion = version;
|
|
304
|
+
this._lastInstalledVersion = version;
|
|
305
|
+
console.log(
|
|
306
|
+
`[relay] 樣板已下載並解壓至 ${this.autoTemplateDir}(${name} v${version},${written.length} 個檔案)`
|
|
307
|
+
);
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
module.exports = { TeacherClient, safety };
|
package/standalone.js
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Standalone Relay(不連 Teacher,單獨測試 local API server;全部預設設定)。
|
|
4
|
+
*
|
|
5
|
+
* 與 Python 版 standalone.py 對齊:
|
|
6
|
+
* - 狀態 enabled、limits 20/80/120、model routing openrouter/free(fallback 空)
|
|
7
|
+
* - API key 由 --api-key 或 OPENROUTER_API_KEY / OPENROUTER_KEY 提供(只存記憶體)
|
|
8
|
+
* - OPENROUTER_BASE_OVERRIDE 可指向假 upstream
|
|
9
|
+
* - logs 寫入 studentJS/.logs/relay/relay.log(每日輪替、保留 5 天)
|
|
10
|
+
*/
|
|
11
|
+
"use strict";
|
|
12
|
+
|
|
13
|
+
const { RelayEngine } = require("./relay/engine");
|
|
14
|
+
const { LocalApiServer } = require("./relay/server");
|
|
15
|
+
const { OpenRouterClient } = require("./relay/openrouter");
|
|
16
|
+
const { PayloadLogger } = require("./relay/payload-log");
|
|
17
|
+
const { relayLogger } = require("./relay/log");
|
|
18
|
+
|
|
19
|
+
function parseArgs(argv) {
|
|
20
|
+
const args = { port: 4141, apiKey: process.env.OPENROUTER_API_KEY || process.env.OPENROUTER_KEY || "", logPayloads: false };
|
|
21
|
+
for (let i = 0; i < argv.length; i++) {
|
|
22
|
+
if (argv[i] === "--port") args.port = Number(argv[++i]);
|
|
23
|
+
else if (argv[i] === "--api-key") args.apiKey = argv[++i] || "";
|
|
24
|
+
else if (argv[i] === "--log-payloads") args.logPayloads = true;
|
|
25
|
+
else if (argv[i] === "-h" || argv[i] === "--help") {
|
|
26
|
+
console.log("用法:node standalone.js [--port 4141] [--api-key sk-or-...] [--log-payloads]");
|
|
27
|
+
process.exit(0);
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
return args;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
async function main(argv = process.argv.slice(2)) {
|
|
34
|
+
const args = parseArgs(argv);
|
|
35
|
+
if (!args.apiKey) {
|
|
36
|
+
console.error("缺少 API Key:請設 OPENROUTER_API_KEY 環境變數或 --api-key");
|
|
37
|
+
return 2;
|
|
38
|
+
}
|
|
39
|
+
const engine = new RelayEngine("relay-standalone");
|
|
40
|
+
engine.apiKey = args.apiKey;
|
|
41
|
+
const client = new OpenRouterClient();
|
|
42
|
+
const server = new LocalApiServer(engine, {
|
|
43
|
+
port: args.port,
|
|
44
|
+
client,
|
|
45
|
+
payloadLog: new PayloadLogger(!!args.logPayloads),
|
|
46
|
+
});
|
|
47
|
+
await server.start();
|
|
48
|
+
const st = engine.state;
|
|
49
|
+
console.log(`[standalone-relay] local API : http://127.0.0.1:${server.port}/v1`);
|
|
50
|
+
console.log(`[standalone-relay] upstream : ${client.baseUrl}`);
|
|
51
|
+
console.log(`[standalone-relay] status : ${st.status}(limits ${st.requestLimit["5m"]}/${st.requestLimit["30m"]}/${st.requestLimit["60m"]})`);
|
|
52
|
+
console.log(`[standalone-relay] routing : model=${st.primaryModel} models=${JSON.stringify(st.models)}`);
|
|
53
|
+
console.log("[standalone-relay] api key : configured(不顯示內容)");
|
|
54
|
+
console.log(`[standalone-relay] logs : ${relayLogger().file}(每日輪替、保留 5 天)`);
|
|
55
|
+
|
|
56
|
+
const shutdown = async () => {
|
|
57
|
+
console.log("stopped");
|
|
58
|
+
await server.stop();
|
|
59
|
+
process.exit(0);
|
|
60
|
+
};
|
|
61
|
+
process.on("SIGINT", shutdown);
|
|
62
|
+
process.on("SIGTERM", shutdown);
|
|
63
|
+
return 0;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
if (require.main === module) {
|
|
67
|
+
main().then((code) => {
|
|
68
|
+
if (code !== 0) process.exit(code);
|
|
69
|
+
});
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
module.exports = { parseArgs, main };
|
package/README.md
DELETED