soulbridge 0.0.3 → 0.0.5

package/README.md

@@ -3,7 +3,7 @@
 > **给任何 agent 装上一个人格层。**
 > A personality layer for any agent — continuity, forgetting, and growth across tools.
 
-**状态：v0.0.1 骨架 · 未发布 · 接口随时会变**
+**状态：v0.0.4 · 已发布 npm · 接口仍在演进**
 
 ---
 
@@ -25,6 +25,18 @@ soulbridge 是它们之间那层**不属于任何一家**的记忆与人格：
 | 云端服务 | 默认全本地，数据不出机器 |
 | “更像人”的叙事营销 | 只承诺可观测的事 |
 
+## 什么时候别用我们
+
+诚实地说：**如果你只用一种 agent 工具、只在一个仓库工作、并且愿意手动维护 `AGENTS.md`，那它比我们更好。**
+
+| 你的情况 | 建议 |
+|---|---|
+| 单工具 + 单仓库 + 愿意手动维护 | 用 `AGENTS.md` / `CLAUDE.md`，别装我们 |
+| 团队共享约定 | 用仓库里的 `AGENTS.md`，我们不抢 |
+| 多工具 / 多仓库 + 有个人偏好 | 我们是唯一能跨工具携带的那一层 |
+
+我们只做三件 steering 文件结构上做不到的事：**跨工具携带、自动维护（抽取/遗忘/取代）、注入选择**。详见 [ADR 0019](docs/adr/0019-steering-files.md)。
+
 ## 四个动词
 
 宿主只需要在四个时机调用，就完成了接入：
@@ -32,7 +44,7 @@ soulbridge 是它们之间那层**不属于任何一家**的记忆与人格：
 | 动词 | 时机 | 作用 |
 |---|---|---|
 | `context()` | 会话开始 | 注入：身份 + 画像 + 相关记忆 + 表达风格 |
-| `observe(turn)` | 每轮结束 | 观察：写入经历、更新情绪 |
+| `observe(turn)` | 每轮结束 | 观察：写入经历、分析用户情绪、更新自己的情绪 |
 | `recall(q)` | 需要时 | 召回：按相关性/新旧/重要度/唤醒次数排序 |
 | `reflect(session)` | 会话结束 | 反思：把经历固化成策略与认知 |
 
@@ -46,6 +58,8 @@ soulbridge 是它们之间那层**不属于任何一家**的记忆与人格：
 npx soulbridge init
 npx soulbridge remember --type strategy "提交前先跑 make check，能省一轮 CI"
 npx soulbridge context --query "要不要先跑测试"
+npx soulbridge affect "我不太开心，这个方案又被拒了"
+npx soulbridge import --from AGENTS.md      # 把已有的项目约定导进来
 npx soulbridge demo          # 起一个 soul，跑完整 context→observe→reflect→context
 ```
 
@@ -75,16 +89,31 @@ SQLite（默认） / Postgres（可选）
 
 详见 [docs/architecture.md](docs/architecture.md)。
 
+## 接入宿主
+
+| 宿主 | 方式 | 位置 |
+|---|---|---|
+| DSH | 把 skill 放进 skills 目录 | [`adapters/dsh/SKILL.md`](adapters/dsh/SKILL.md) |
+| Claude Code / Pi / Cursor | 同理：把同一份 `SKILL.md` 当作指令文件 | v0.5+ |
+
+接上之后，宿主在会话开始运行 `soulbridge context`、每轮运行 `soulbridge observe`、结束时运行 `soulbridge ingest`。**拿不到会话转写也不影响使用**：`observe` 已经逐轮记录了观察。
+
 ## 设计文档
 
 | 文档 | 内容 |
 |---|---|
 | [thesis](docs/thesis.md) | 核心命题、三条可证伪预测、四臂实验、放弃条件 |
 | [RFC 0001](docs/rfcs/0001-foundations.md) | 定位、用户、非目标、成功指标、四个动词、接入阶梯 |
-| [ADR 索引](docs/rfcs/README.md) | 11 条已生效的架构决定（定位/语言/存储/依赖/协议/许可/接入/范围/评估/质量） |
+| [RFC 0002](docs/rfcs/0002-affect.md) | 输入侧情感层：两套情绪的边界、数据流、已知局限 |
+| [ADR 索引](docs/rfcs/README.md) | 23 条已生效的架构决定 |
 | [protocol.v0](docs/spec/protocol.v0.md) | 四个动词的完整契约：字段、错误码、降级、测试映射 |
+| [affect.v0](docs/spec/affect.v0.md) | 词库格式、8 条规则、置信度公式、黄金集与消融 |
+| [storage.v0](docs/spec/storage.v0.md) | 路径、身份、迁移、并发、导出格式 |
+| [sync.v0](docs/spec/sync.v0.md) | 跨设备合并语义（v0.5 实现） |
+| [transcript.v1](docs/spec/transcript.v1.md) | 可移植会话转写格式（ingest 的输入） |
 | [quality](docs/quality.md) | 质量模型、九条门禁、五条评审清单 |
 | [references](docs/references.md) | 外部资料的去留与过期判断 |
+| [runbook](docs/runbook.md) | 发版流程、维护操作、已知待办 |
 
 **规则**：架构级改动必须先有 RFC 或 ADR；聊天里达成的不算决定。
 
@@ -98,6 +127,8 @@ SQLite（默认） / Postgres（可选）
 - 默认 SQLite，落在 `~/.soulbridge/soul.db`
 - 零遥测、零上报
 - 记忆可导出、可删除、可迁移
+- 情绪采样只存**词条与计数**，不存原句；30 天自动清理
+- 默认不联网；只有显式启用 LLM 分析器时，才会把**当前这一条** user 文本发给你配置的端点
 
 ## License
 

package/adapters/dsh/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: soulbridge
+description: "跨工具的人格与记忆层。会话开始时注入记忆与情绪，每轮后记录观察，会话结束时反思。当用户提到「记得我 / 上次 / 之前 / 我的习惯」，或需要跨会话连续性时使用。"
+---
+
+# soulbridge
+
+你在一个有 `soulbridge` CLI 的机器上工作。它保存了这个用户跨工具的偏好、被纠正过的错、以及最近的表达状态。
+
+## 会话开始
+
+运行一次，把输出**原样**放到你的系统提示最前面（不要改写、不要总结）：
+
+```bash
+soulbridge context --query "<用户这次的第一句话>"
+```
+
+输出通常是 `<soul>…</soul>`、`<style>…</style>`、`<affect>…</affect>`、`<memories>…</memories>` 几段。
+
+## 每轮结束
+
+只对**用户的**消息运行：
+
+```bash
+soulbridge observe "<用户这条消息的原文>"
+```
+
+## 会话结束（可选）
+
+如果你能拿到一份 `transcript.v1.jsonl`（见 `docs/spec/transcript.v1.md`），运行：
+
+```bash
+soulbridge ingest --file <transcript.jsonl>
+```
+
+拿不到就不要强行导出：`observe` 已经记录了每轮观察，`reflect` 可以下次再补。
+
+## 规则（重要）
+
+1. **不要向用户转述注入内容**。不要说"我记得你说过……"，除非它确实与当前任务相关。
+2. **注入只影响措辞，不影响事实判断**。`<affect>` 里的建议是语气提示，不是改变结论的理由。
+3. **`soulbridge` 失败不阻塞**。命令报错时忽略它，继续正常回答。
+4. **不要猜测记忆内容**。没有注入的记忆就是没有，不要编造"以前聊过"。
+5. **不要把它写进项目文件**。个人记忆属于本机 `~/.soulbridge/soul.db`，不是仓库的一部分。
+
+## 边界
+
+- 不要修改 `~/.soulbridge/` 下的文件
+- 不要 `export` 并把内容贴到聊天里（导出是给用户备份用的）
+- 不确定时运行 `soulbridge --help`

package/dist/packages/cli/src/cli.js

@@ -3,14 +3,17 @@
  * Minimal CLI. No framework, no dependencies.
  *
  *   soulbridge init
- *   soulbridge remember "以后提交前先跑 make check" --type strategy --importance 8
+ *   soulbridge remember "以后提交前先跑 make check" --type strategy
  *   soulbridge context --query "提交前要做什么"
- *   soulbridge recall "测试"
- *   soulbridge reflect --text "..."      (or --file transcript.txt)
+ *   soulbridge observe "我不太开心"
+ *   soulbridge affect "我不太开心"
+ *   soulbridge reflect --text "..."
+ *   soulbridge export --out soulbridge.jsonl
+ *   soulbridge import --in soulbridge.jsonl
  *   soulbridge stats
  *   soulbridge demo
  */
-import { mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 // node:sqlite prints an ExperimentalWarning the moment it loads. Replace the default
 // printer with a filter: the CLI's own output stays clean, other warnings still show.
@@ -21,7 +24,8 @@ process.on('warning', (warning) => {
         return;
     process.stderr.write(`${warning.name}: ${warning.message}\n`);
 });
-const { openSqlite, Soul } = await import('../../core/src/index.js');
+const { openSqlite, Soul, ensureConfig, resolveDbPath, analyzeAffect, validateLexicon, parseSteering, normalizeForDedupe, parseTranscriptJsonl, } = await import('../../core/src/index.js');
+const { llmAnalyzerFromEnv } = await import('./llm-analyzer.js');
 function parse(argv) {
     const [cmd = 'help', ...rest] = argv;
     const positional = [];
@@ -44,22 +48,40 @@ function parse(argv) {
     }
     return { cmd, positional, flags };
 }
-function dbFile() {
-    const file = process.env.SOULBRIDGE_DB ?? resolve(process.cwd(), '.soulbridge', 'soul.db');
-    mkdirSync(dirname(file), { recursive: true });
-    return file;
+function lexiconAnalyzerFrom(path) {
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    const errors = validateLexicon(raw);
+    if (errors.length > 0)
+        throw new Error(`invalid lexicon (${path}): ${errors.slice(0, 3).join('; ')}`);
+    const lexicon = raw;
+    return { id: 'lexicon', analyze: (text) => analyzeAffect(text, { lexicon }) };
 }
-function open(file, createdAt) {
-    const target = file ?? dbFile();
-    const store = openSqlite(target);
+function pickAnalyzer(flags) {
+    let analyzer;
+    if (flags.lexicon)
+        analyzer = lexiconAnalyzerFrom(flags.lexicon);
+    if (flags.analyzer === 'llm') {
+        const llm = llmAnalyzerFromEnv();
+        if (llm)
+            analyzer = llm;
+        else
+            process.stderr.write('soulbridge: SOULBRIDGE_AFFECT_LLM_URL not set; using the lexicon analyzer\n');
+    }
+    return analyzer;
+}
+function open(flags) {
+    const config = ensureConfig();
+    const dbPath = resolveDbPath(flags.db);
+    mkdirSync(dirname(dbPath), { recursive: true });
     const soul = new Soul({
-        store,
-        soulId: process.env.SOULBRIDGE_SOUL ?? 'xiaoling',
-        userId: process.env.SOULBRIDGE_USER ?? 'local',
-        name: process.env.SOULBRIDGE_NAME ?? '小灵',
-        createdAt,
+        store: openSqlite(dbPath),
+        soulId: config.soulId,
+        userId: config.userId,
+        name: config.name,
+        deviceId: config.deviceId,
+        analyzer: pickAnalyzer(flags),
     });
-    return { soul, file: target };
+    return { soul, dbPath, deviceId: config.deviceId };
 }
 function out(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
@@ -70,7 +92,6 @@ async function demo() {
     const file = resolve(dir, 'demo.db');
     for (const suffix of ['', '-wal', '-shm'])
         rmSync(`${file}${suffix}`, { force: true });
-    // Backdate the birthday so the demo shows a relationship that has time in it.
     const seed = openSqlite(file);
     seed.ensureSoul({ soulId: 'xiaoling', name: '小灵', createdAt: Date.now() - 3 * 86_400_000 });
     seed.close();
@@ -85,27 +106,55 @@ async function demo() {
         { role: 'user', content: '不对，这个方案是错的' },
     ]);
     process.stdout.write(`写入 ${result.memories} 条记忆，情绪 ${JSON.stringify(result.emotion)}\n\n`);
-    process.stdout.write('=== 第 2 次会话：开场（无查询，按重要度注入全部）===\n');
-    process.stdout.write(`${soul.context().text}\n\n`);
-    process.stdout.write('=== 同一会话中，用户问「提交前要做什么」（有查询，只注入相关的）===\n');
+    process.stdout.write('=== 用户说了一句带情绪的话（observe）===\n');
+    const observed = await soul.observe({ role: 'user', content: '我特别难过，这个方案又被拒了' });
+    process.stdout.write(`affect: ${observed.affect.dominant ?? 'none'} / 强度 ${observed.affect.intensity} / 置信 ${observed.affect.confidence}\n\n`);
+    process.stdout.write('=== 第 2 次会话：开场（含情绪段）===\n');
     process.stdout.write(`${soul.context({ query: '提交前要做什么' }).text}\n\n`);
     process.stdout.write('=== stats ===\n');
     out(soul.stats());
     process.stdout.write(`\n数据库：${file}\n`);
 }
+function exportJsonl(soul, deviceId) {
+    const lines = [
+        JSON.stringify({
+            type: 'header',
+            version: 1,
+            soulId: soul.soulId,
+            userId: soul.userId,
+            deviceId,
+            exportedAt: Date.now(),
+        }),
+    ];
+    const memories = soul.store.query({
+        soulId: soul.soulId,
+        userId: soul.userId,
+        status: ['active', 'superseded', 'archived'],
+        limit: 100_000,
+    });
+    for (const memory of memories)
+        lines.push(JSON.stringify({ type: 'memory', memory }));
+    const samples = soul.store.recentAffect(soul.soulId, soul.userId, 0);
+    for (const sample of samples) {
+        const withAt = sample;
+        lines.push(JSON.stringify({ type: 'affect', at: withAt.at ?? 0, signal: sample }));
+    }
+    return `${lines.join('\n')}\n`;
+}
 async function main() {
     const { cmd, positional, flags } = parse(process.argv.slice(2));
     switch (cmd) {
         case 'init': {
-            const { soul, file } = open();
-            out({ ok: true, db: file, ...soul.stats() });
+            const config = ensureConfig();
+            const { dbPath } = open(flags);
+            out({ ok: true, db: dbPath, config });
             return;
         }
         case 'remember': {
             const content = positional.join(' ').trim();
             if (!content)
                 throw new Error('usage: soulbridge remember "内容" [--type T] [--importance N]');
-            const { soul } = open();
+            const { soul } = open(flags);
             const id = soul.remember(content, {
                 type: flags.type ?? 'fact',
                 importance: flags.importance ? Number(flags.importance) : undefined,
@@ -114,7 +163,7 @@ async function main() {
             return;
         }
         case 'context': {
-            const { soul } = open();
+            const { soul } = open(flags);
             const result = soul.context({
                 query: flags.query,
                 maxChars: flags.max ? Number(flags.max) : undefined,
@@ -126,17 +175,30 @@ async function main() {
             const query = positional.join(' ').trim();
             if (!query)
                 throw new Error('usage: soulbridge recall "查询" [--limit N]');
-            const { soul } = open();
+            const { soul } = open(flags);
             const hits = soul.recall(query, flags.limit ? Number(flags.limit) : 5);
-            out(hits.map((h) => ({ id: h.memory.id, type: h.memory.type, content: h.memory.content, score: Number(h.score.toFixed(3)) })));
+            out(hits.map((h) => ({
+                id: h.memory.id,
+                type: h.memory.type,
+                content: h.memory.content,
+                score: Number(h.score.toFixed(3)),
+            })));
             return;
         }
         case 'observe': {
             const content = positional.join(' ').trim();
             if (!content)
                 throw new Error('usage: soulbridge observe "一句话"');
-            const { soul } = open();
-            out(soul.observe({ role: 'user', content }));
+            const { soul } = open(flags);
+            out(await soul.observe({ role: 'user', content }));
+            return;
+        }
+        case 'affect': {
+            const text = positional.join(' ').trim();
+            if (!text)
+                throw new Error('usage: soulbridge affect "文本" [--analyzer lexicon|llm] [--lexicon path]');
+            const analyzer = pickAnalyzer(flags);
+            out(analyzer ? await analyzer.analyze(text) : analyzeAffect(text));
             return;
         }
         case 'reflect': {
@@ -154,13 +216,96 @@ async function main() {
                 const role = /^(assistant|助手)$/i.test(match[1]) ? 'assistant' : 'user';
                 return { role, content: match[2] };
             });
-            const { soul } = open();
+            const { soul } = open(flags);
             out(await soul.reflect(turns));
             return;
         }
+        case 'export': {
+            const file = flags.out;
+            if (!file)
+                throw new Error('usage: soulbridge export --out soulbridge.jsonl');
+            const { soul, deviceId } = open(flags);
+            const body = exportJsonl(soul, deviceId);
+            const target = resolve(file);
+            writeFileSync(target, body, 'utf8');
+            out({ ok: true, file: target, lines: body.trimEnd().split('\n').length });
+            return;
+        }
+        case 'import': {
+            // Steering file (AGENTS.md / CLAUDE.md) → memories (ADR 0022).
+            if (flags.from) {
+                const file = resolve(flags.from);
+                const drafts = parseSteering(readFileSync(file, 'utf8'));
+                const { soul } = open(flags);
+                const dryRun = flags['dry-run'] === 'true';
+                const existing = new Set(soul.store
+                    .query({ soulId: soul.soulId, userId: soul.userId, limit: 100_000 })
+                    .map((m) => normalizeForDedupe(m.content)));
+                let written = 0;
+                let skipped = 0;
+                for (const draft of drafts) {
+                    const key = normalizeForDedupe(draft.text);
+                    if (!key || existing.has(key)) {
+                        skipped += 1;
+                        continue;
+                    }
+                    existing.add(key);
+                    if (!dryRun)
+                        soul.remember(draft.text, { type: draft.type, importance: draft.importance });
+                    written += 1;
+                }
+                out({ ok: true, source: file, kind: 'steering', parsed: drafts.length, written, skipped, dryRun });
+                return;
+            }
+            const file = flags.in;
+            if (!file)
+                throw new Error('usage: soulbridge import --from <steering.md> | --in <export.jsonl>');
+            const { soul, deviceId } = open(flags);
+            let memories = 0;
+            let affects = 0;
+            for (const line of readFileSync(resolve(file), 'utf8').split(/\r?\n/)) {
+                if (!line.trim())
+                    continue;
+                const record = JSON.parse(line);
+                if (record.type === 'memory' && record.memory) {
+                    soul.store.put(record.memory);
+                    memories += 1;
+                }
+                else if (record.type === 'affect' && record.signal) {
+                    soul.store.saveAffect(soul.soulId, soul.userId, record.signal, Number(record.at ?? 0), deviceId);
+                    affects += 1;
+                }
+            }
+            out({ ok: true, kind: 'jsonl', memories, affects });
+            return;
+        }
+        case 'ingest': {
+            const file = flags.file;
+            if (!file)
+                throw new Error('usage: soulbridge ingest --file transcript.jsonl [--dry-run]');
+            const { turns, skipped } = parseTranscriptJsonl(readFileSync(resolve(file), 'utf8'));
+            const { soul } = open(flags);
+            const dryRun = flags['dry-run'] === 'true';
+            if (!dryRun) {
+                for (const turn of turns) {
+                    if (turn.role !== 'user')
+                        continue;
+                    const signal = await soul.analyze(turn.content);
+                    try {
+                        soul.store.saveAffect(soul.soulId, soul.userId, signal, turn.at ?? Date.now(), soul.deviceId);
+                    }
+                    catch {
+                        // Evaluation data is best-effort; ingestion must still complete.
+                    }
+                }
+            }
+            const reflected = dryRun ? null : await soul.reflect(turns);
+            out({ ok: true, file: resolve(file), turns: turns.length, skipped, reflected, dryRun });
+            return;
+        }
         case 'stats': {
-            const { soul, file } = open();
-            out({ db: file, ...soul.stats() });
+            const { soul, dbPath } = open(flags);
+            out({ db: dbPath, ...soul.stats() });
             return;
         }
         case 'demo':
@@ -171,16 +316,22 @@ async function main() {
                 'soulbridge — 给任何 agent 装上一个人格层',
                 '',
                 'commands:',
-                '  init                            初始化数据库',
+                '  init                            初始化配置与数据库',
                 '  remember <text> [--type T]      显式记住一条',
                 '  context [--query Q] [--max N]   生成注入文本',
+                '  observe <text>                  观察一轮（含情绪分析）',
+                '  affect <text> [--analyzer llm]  只做情绪分析',
                 '  recall <q> [--limit N]          召回',
-                '  observe <text>                  观察一轮',
                 '  reflect --text|--file           会话反思',
+                '  export --out <file>             导出 JSONL',
+                '  import --in <file>              导入 JSONL',
+                '  import --from <steering.md>     导入 AGENTS.md / CLAUDE.md',
+                '  ingest --file <transcript.jsonl> 会话转写 → 记忆与情绪采样',
                 '  stats                           看状态',
                 '  demo                            端到端演示（无需模型）',
                 '',
-                'env: SOULBRIDGE_DB, SOULBRIDGE_SOUL, SOULBRIDGE_USER, SOULBRIDGE_NAME',
+                'env: SOULBRIDGE_DB, SOULBRIDGE_SOUL, SOULBRIDGE_USER, SOULBRIDGE_NAME,',
+                '     SOULBRIDGE_AFFECT_LLM_URL / _MODEL / _KEY / _TIMEOUT',
                 '',
             ].join('\n'));
     }

package/dist/packages/cli/src/llm-analyzer.js

@@ -0,0 +1,82 @@
+import { emptyAffect } from '../../core/src/index.js';
+const CATEGORIES = ['joy', 'anger', 'sadness', 'fear', 'disgust', 'surprise'];
+const SYSTEM_PROMPT = [
+    '你是情感分类器。只输出 JSON，不要解释。',
+    'JSON 结构：{"dominant":"joy|anger|sadness|fear|disgust|surprise|null","intensity":0-9,"valence":-1..1,"arousal":0..1,"confidence":0..1}',
+    '规则：只根据用户这句话判断；没有明显情绪时 dominant 为 null、confidence <= 0.3；不要猜测对方的人格。',
+].join('\n');
+const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
+function parseJsonBlock(content) {
+    const trimmed = content.trim().replace(/^```(?:json)?/i, '').replace(/```$/, '').trim();
+    const start = trimmed.indexOf('{');
+    const end = trimmed.lastIndexOf('}');
+    if (start < 0 || end < start)
+        throw new Error('model did not return JSON');
+    return JSON.parse(trimmed.slice(start, end + 1));
+}
+export function createLlmAnalyzer(options) {
+    const timeoutMs = options.timeoutMs ?? 3000;
+    const maxConfidence = options.maxConfidence ?? 0.85;
+    const endpoint = `${options.url.replace(/\/$/, '')}/chat/completions`;
+    return {
+        id: 'llm',
+        async analyze(text) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const response = await fetch(endpoint, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        ...(options.apiKey ? { authorization: `Bearer ${options.apiKey}` } : {}),
+                    },
+                    body: JSON.stringify({
+                        model: options.model,
+                        temperature: 0,
+                        messages: [
+                            { role: 'system', content: SYSTEM_PROMPT },
+                            { role: 'user', content: text.slice(0, 2000) },
+                        ],
+                    }),
+                    signal: controller.signal,
+                });
+                if (!response.ok)
+                    throw new Error(`llm analyze failed: HTTP ${response.status}`);
+                const payload = (await response.json());
+                const content = payload.choices?.[0]?.message?.content;
+                if (!content)
+                    throw new Error('llm analyze returned empty content');
+                const parsed = parseJsonBlock(content);
+                const dominant = typeof parsed.dominant === 'string' && CATEGORIES.includes(parsed.dominant)
+                    ? parsed.dominant
+                    : null;
+                const intensity = clamp(Number(parsed.intensity ?? 0), 0, 9);
+                const confidence = clamp(Number(parsed.confidence ?? 0), 0, maxConfidence);
+                const signal = emptyAffect('llm');
+                return {
+                    ...signal,
+                    dominant,
+                    intensity,
+                    valence: clamp(Number(parsed.valence ?? 0), -1, 1),
+                    arousal: clamp(Number(parsed.arousal ?? 0), 0, 1),
+                    confidence: dominant ? confidence : Math.min(confidence, 0.3),
+                };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}
+/** Build the analyzer from env vars, or null when not configured. */
+export function llmAnalyzerFromEnv() {
+    const url = process.env.SOULBRIDGE_AFFECT_LLM_URL;
+    if (!url)
+        return null;
+    return createLlmAnalyzer({
+        url,
+        model: process.env.SOULBRIDGE_AFFECT_LLM_MODEL ?? 'qwen3:1.7b',
+        apiKey: process.env.SOULBRIDGE_AFFECT_LLM_KEY,
+        timeoutMs: Number(process.env.SOULBRIDGE_AFFECT_LLM_TIMEOUT ?? 3000),
+    });
+}