dsh-chat-tide 0.0.0-stage → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+## 0.2.2
+
+### Fixed
+
+- The session picker rendered once per settings group instead of once, because
+  its condition was global. It now renders only in the scope group.
+
+### Changed
+
+- Scope is the first section on the settings page, before the switches.
+
+## 0.2.1
+
+### Fixed
+
+- The published package now includes CONTRIBUTING.md and RELEASE.md, so the
+  advertised `npm test` runs after install instead of failing on missing docs.
+- Probe 28 skips its wake assertion when sqlite-vec's platform package is
+  absent, instead of reporting a failure for an environment it cannot control.
+
+### Changed
+
+- README states the installation weight honestly: about 300MB of dependencies
+  (onnxruntime and friends) before the model itself is downloaded.
+
+## 0.2.0
+
+### Added
+
+- Scope is selectable on the plugin page: follow dsh-qqbot (default), a specific
+  workspace, specific sessions picked from a list, or off.
+- `/tide/api/sessions` lists recent sessions (title, workspace, time) for that picker.
+- Attention labels are normalised on write: leading subjects and instruction
+  clauses are stripped, descriptions are kept, nothing is truncated.
+- `scripts/attention-doctor.mjs` reports labels needing rework, missing vectors,
+  orphan vectors and duplicate labels; `--fix` applies the repairs.
+- CI runs every probe plus the naming, dead-config and docs checks on Node 22 and 24.
+
+### Changed
+
+- Waking only screens group chats; private and local sessions pass through.
+- Routing scores the current human message alone instead of every block in the
+  step payload, which used to drag one-word messages across the threshold.
+- Attention thresholds recalibrated from measurements: 0.48 hit, 0.03 gap.
+- Extraction is told who is speaking, so a group member's words are no longer
+  written as the owner's facts.
+- The embedding model stays bge-small-zh; bge-base measured 0.01 AUC better at
+  three times the latency.
+
+### Fixed
+
+- Image-only messages are rejected instead of merely logged, and QQ's `[图片]`
+  placeholder no longer counts as text.
+- `routing.uncertainPolicy` now decides the action instead of only naming it.
+- Re-extraction records the source scope instead of leaving facts as `unknown`.
+- The status route registers through `ctx.inject(['webServer'])`, so a restart or
+  a web-service rebuild no longer leaves it 404.
+- The package ships `probes/`, so the advertised `npm test` works after install.
+
+## 0.1.1
+
+First repository snapshot.

package/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+Thanks for looking. Tide is small on purpose — please keep it that way.
+
+## Shape of the codebase
+
+- `lib/` — the engine. Host half (`index.js`) plus the browser half (`client.js`) that renders the
+  plugin's configuration page. `db.js` owns the schema; every migration is append-only.
+  `const.js` is the single source for the row id, route, data directory, log names and style prefix.
+- `presets/` — content, not code: rules, attention seeds, recommended configs. Generic presets ship;
+  `presets/private.json` never does.
+- `probes/` — numbered regression suites. Each one builds its own throwaway database and asserts
+  behaviour. They are the test suite; there is no separate framework.
+- `scripts/` — operator tooling: packaging, seeding, health, metrics and consistency checks.
+
+## Before opening a pull request
+
+```bash
+npm install
+npm test          # 等价于 node scripts/run-checks.mjs --skip-model
+# 想连模型探针一起跑：node scripts/run-checks.mjs
+```
+
+All suites and the three consistency checks must pass. `check-docs` fails when the README drifts
+from the code; `check-dead-config` fails when a declared configuration key is never read.
+
+If you change the schema, add a migration to `lib/db.js` and a probe that covers it — do not edit
+an existing migration, since someone's database may already be past it.
+
+## Behaviour rules for contributions
+
+- Memory is data, never instructions. Anything injected into a prompt must be fenced as data.
+- Prefer deciding with local signals (FTS, vectors) before spending a model call.
+- Every deletion is soft, auditable and explainable. Never hard-delete user content.
+- Anything that leaves the machine must be visible in the configuration. No silent network calls.
+- No personal identifiers in code, tests, docs, or presets. Use placeholders and environment
+  variables (`CM_OWNER`, `CM_PEER`).
+
+## Commit style
+
+One change per commit, imperative summary, body explains the why rather than restating the diff.
+
+## Local install
+
+Data lives in `~/.dsh/tide/memory.db`; the read-only page is `/tide` on the host port.
+
+When linking this repository into a profile for development, add `dsh-chat-tide` to the profile's `dsh.profile.bundles`. Without that entry the package is installed but never loaded, and the plugin page shows nothing.
+
+## Tooling
+
+| Command | Purpose |
+|---|---|
+| `npm test` | every probe plus the three consistency checks |
+| `node scripts/doctor.mjs` | read-only health check of an existing database |
+| `node scripts/metrics.mjs` | data, routing, injection and recent episodes snapshot |
+| `node scripts/curate-report.mjs` | memory quality: duplicates, fragments, expiry, scope violations |
+| `node scripts/check-naming.mjs` | route, directory, log and style consistency |
+| `node scripts/check-dead-config.mjs` | every declared configuration key is actually read |
+| `node scripts/check-docs.mjs` | the README matches the code |
+| `node scripts/seed.mjs` | import presets (idempotent) |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FakerKonzo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,68 @@
+# Tide — chat memory with selective waking
+
+> A chat-memory plugin for DSH: conversations settle into facts and episodes, and the agent speaks only when it should.
+> 中文：[README.md](./README.md)
+
+## The problem
+
+Chat agents usually fail in one of two ways: they forget, or they answer everything.
+
+Tide lets the agent remember what people said and speak only when it should — group chatter is not answered line by line, but when a topic it cares about comes up, it joins in. What it remembers can be browsed, edited, and deleted with a record.
+
+## Compatibility
+
+| Item | Requirement |
+|---|---|
+| DSH | `>=0.2.2-rc.1 <0.3.0`, tested on 0.2.2-rc.1 and 0.2.2-rc.3 |
+| Node | `>=22.5` (uses the built-in `node:sqlite`) |
+| QQ adapter | Optional, tested with `@tencent-connect/dsh-qqbot@0.5.5`; without it memory still works for local sessions, group waking just never fires |
+
+Everything else is installed with the package. The first run downloads a local embedding model of about 25–30MB.
+
+## How it works
+
+1. **Remember first**: incoming chat is recorded; nothing answers anyone at this stage.
+2. **Then decide**: for a group message it checks whether it is being addressed, then whether the topic is something it cares about. If so it speaks; otherwise it rolls a small probability and the model decides whether to join.
+3. **Speak with memory**: only when it does speak are the relevant rules, facts and recent episodes brought into the turn. The rest of the time they stay out of the context.
+4. **Settle afterwards**: at the end of a turn, facts, episodes and interests worth keeping are extracted.
+5. **Clean up over time**: duplicates merge, stale entries retire, one-off claims get corrected.
+
+Memory is kept per person: in a group, what each member said stays under their name. What was said in a private chat does not appear in groups by default.
+
+## Install
+
+Package `dsh-chat-tide`, Loader row id `tide`.
+
+1. Install `dsh-chat-tide` with the DSH plugin manager (or `link:` a local checkout while developing).
+2. Add `dsh-chat-tide` to `dsh.profile.bundles` in the profile's `package.json`. Skipping this installs the package without loading it.
+3. Open the plugin page and confirm which conversations it should manage under "Scope".
+4. On first run keep the waking route off, confirm ingestion and injection work, then enable routing.
+
+Data lives in `~/.dsh/tide/memory.db`.
+
+## Configuration
+
+Most switches and numbers live on the plugin page; changes apply within five seconds without a restart. The ones people touch most:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `routing.attentionThreshold` | 0.48 | Attention hit threshold; higher is pickier |
+| `routing.attentionMargin` | 0.03 | How far ahead of the runner-up a hit must be |
+| `routing.ambientReplyProbability` | 0.1 | Chance of a tentative reply outside attention |
+| `routing.l2Threshold` | 0.45 | How close a single fact must be to count as relevant |
+| `routing.maxWakesPerDay` | 20 | Daily cap on spontaneous replies per conversation |
+| `routing.minWakeIntervalMinutes` | 10 | Minimum gap between two wake-ups |
+| `scope.mode` | follow | Which conversations it manages: follow dsh-qqbot / a workspace / specific sessions / off |
+| `context.unifySessions` | false | Whether private and group chats share one memory |
+| `context.groupExcludePrivate` | true | Whether groups are shielded from private sources |
+
+## Known limits
+
+- The default exploration chance is a starting guess; tune it for your group
+- Interests grow from real conversations, so an empty memory stays silent
+- An image-only message never wakes it; when an image carries text, whether to look is the model's call
+- The embedding model downloads on first use, so cold start is slow
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# Tide — 聊天记忆与选择性接茬
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 给 DSH 的聊天记忆插件：把对话沉淀成事实与经历，在合适的时候才开口。
+> English: [README.en.md](./README.en.md)
+
+## 它解决什么
+
+聊天机器人常见两种坏状态：记不住，或者什么都接。
+
+Tide 让机器人记住你们聊过的事，并且只在真正该说话的时候开口——群里的闲聊不会句句都接，但聊到它在意的话题，它会主动搭话。记住的东西可以翻、可以改，删掉也有记录。
+
+## 兼容与依赖
+
+| 项 | 要求 |
+|---|---|
+| DSH | `>=0.2.2-rc.1 <0.3.0`，在 0.2.2-rc.1 与 0.2.2-rc.3 上实机跑过 |
+| Node | `>=22.5`（用到内置 `node:sqlite`） |
+| QQ 适配器 | 可选，实测 `@tencent-connect/dsh-qqbot@0.5.5`；没有它也能记本地会话，只是群聊接茬不会触发 |
+
+其余依赖随包安装，不需要手动处理。首次使用会下载一个约 25–30MB 的本地向量模型。
+
+## 它怎么工作
+
+1. **先记住**：聊天内容先落成原始记录，这时候还不会回复任何人。
+2. **再判断**：群消息来了，先看是不是在找它，再看这件事是不是它在意的。在意就直接接；不在意就按一个小概率试探，是否开口由模型自己决定。
+3. **带着记忆说话**：真要开口时，才把相关的规矩、事实和近期经历带进这一轮。平时不占上下文。
+4. **说完再沉淀**：一轮结束，从对话里提炼值得留下的事实、经历和关注点。
+5. **定期清理**：重复的合并、过期的退休、只在当时成立的改掉。
+
+记忆按人分开：群里谁说的记在谁名下，不会混成一个人的事。私聊里说的默认不会出现在群里。
+
+## 安装
+
+包名 `dsh-chat-tide`，插件行 id 是 `tide`。
+
+1. 在 DSH 插件管理器里安装 `dsh-chat-tide`（开发时也可以 `link:` 本地目录）。
+2. 把 `dsh-chat-tide` 加进 profile 的 `package.json` → `dsh.profile.bundles`。漏了会「装了但不加载」。
+3. 打开插件详情页，在「作用域」里确认它该管哪些会话。
+4. 首次只开入站镜像与注入，确认没问题再开路由。
+
+数据默认存在 `~/.dsh/tide/memory.db`。
+
+## 配置
+
+大部分开关和数值在插件详情页里调，改完最多 5 秒生效，不用重启。常用的几项：
+
+| 键 | 默认 | 含义 |
+|---|---|---|
+| `routing.attentionThreshold` | 0.48 | 关注点命中阈值，越高越挑 |
+| `routing.attentionMargin` | 0.03 | 命中还要跟第二名拉开多少 |
+| `routing.ambientReplyProbability` | 0.1 | 不在关注点内时，试探接话的概率 |
+| `routing.l2Threshold` | 0.45 | 单看事实够不够近就能判相关 |
+| `routing.maxWakesPerDay` | 20 | 每个会话每天最多主动开口几次 |
+| `routing.minWakeIntervalMinutes` | 10 | 两次开口至少隔多久 |
+| `scope.mode` | follow | 哪些会话归它管：跟随 dsh-qqbot / 指定工作区 / 指定会话 / 关闭 |
+| `context.unifySessions` | false | 私聊和群聊是否共用一份记忆 |
+| `context.groupExcludePrivate` | true | 群里是否屏蔽私聊里说过的事 |
+
+## 已知边界
+
+- 试探概率的默认值只是起点，得按自己的群调
+- 关注点靠真实对话长出来，空库时它不会主动说话
+- 纯图片消息不会唤醒它；图片里带文字时，看不看由模型自己判断
+- 第一次用要下载向量模型，会慢一点
+
+## 许可
+
+MIT，见 [LICENSE](./LICENSE)。

package/RELEASE.md

@@ -0,0 +1,55 @@
+# Release checklist
+
+Run through this before tagging a public release. Nothing here touches a live deployment.
+
+## 1. Code and checks
+
+- [ ] `for f in probes/*.mjs; do node "$f"; done` — all suites pass (probe 14 prints `SKIP` when
+      the embedding model is not cached; set `MODEL_CACHE_DIR` to reuse an existing download)
+- [ ] `node scripts/check-naming.mjs` — route, directory, log names and style prefix agree
+- [ ] `node scripts/check-dead-config.mjs` — every declared configuration key is actually read
+- [ ] `node scripts/check-docs.mjs` — the README matches the code
+- [ ] `node scripts/doctor.mjs` against a copy of a real database — no `fail`
+- [ ] CI is green on both Node majors for the release commit
+- [ ] `node --check` every file under `lib/` (the exporter does this too)
+
+## 2. Sanitisation
+
+- [ ] No real openids, account ids, host paths, or `appSecret` anywhere in the publishable tree
+- [ ] `presets/private.json` is absent from the export (gitignored, removed by the exporter)
+- [ ] `cordis.patch.yml` uses placeholders only
+- [ ] `node scripts/export-repo.mjs` prints `敏感标识检查： 通过`
+
+## 3. Package metadata
+
+- [ ] `name` is `dsh-chat-tide`, `version` follows semver (bump when behaviour changes)
+- [ ] `license` is MIT and `LICENSE` is present
+- [ ] `icon` points to an existing file; `files` lists `lib`, `assets`, `presets`, docs
+- [ ] `dsh.engines.dsh` matches the Harness versions actually tested
+
+## 4. Documentation claims
+
+- [ ] Every feature described in the README exists and is reachable from configuration
+- [ ] Known limits are stated, not hidden (README "Known limits" section)
+- [ ] Anything that leaves the machine is documented (model calls, optional model download)
+- [ ] No links to files that are not shipped
+
+## 5. Repository
+
+- [ ] `node scripts/export-repo.mjs <target>` produces the tree
+- [ ] `git init`, first commit, remote added, pushed
+- [ ] Tag the release (`vX.Y.Z`)
+- [ ] `CONTRIBUTING.md` present; issue templates optional
+
+## 6. Optional npm publish
+
+- [ ] `npm pack --dry-run` shows only intended files (no `presets/private.json`, no `.db`)
+- [ ] Publish, then install from the registry into a clean profile
+- [ ] **Add `dsh-chat-tide` to that profile's `dsh.profile.bundles`**, otherwise the package
+      installs but never loads
+
+## 7. After release
+
+- [ ] Install from the published artifact, run one real conversation, confirm the config page and
+      `/tide` respond
+- [ ] Record the schema version shipped; note the migration path for existing databases

package/cordis.patch.yml

@@ -0,0 +1,35 @@
+# Tide bundle patch — copy and edit before installing.
+# The row id and the package name must match: <package>#<row id> keys the plugin's config page.
+- insert:
+    - id: tide
+      name: 'dsh-chat-tide'
+      config:
+        enabled: true
+        scope:
+          # off | all | qq | allowlist | workspace | preset | sessions
+          mode: 'allowlist'
+          peers:
+            - '<your-peer-openid-1>'
+            - '<your-peer-openid-2>'
+        embedding:
+          enabled: true
+          model: 'Xenova/bge-small-zh-v1.5'
+          dtype: 'q8'
+          cacheDir: ''
+          remoteHost: 'https://hf-mirror.com'
+        features:
+          ingest: true
+          writePipeline: true
+          egressGate: false
+          contextInject: true
+          routing: true
+          tools: true
+          writeTools: false
+        extract:
+          provider: '<your-llm-provider>'
+          model: '<your-llm-model>'
+          minChars: 6
+        context:
+          enabled: true
+          maxChars: 1200
+          eventLimit: 5

package/lib/ambient.js

@@ -0,0 +1,44 @@
+// 接茬概率：只在「灰区兜底判相关 且 L2 初筛命中」之后掷骰子。
+// 未命中 L2 的绝不经手；direct / command 永不经过这里。
+
+/**
+ * L2 初筛：拿当前消息去比对已有 active 事实，判断是否有主题重叠。
+ * @param {number[]} queryVec 归一化后的查询向量
+ * @param {Array<{factId:string, vec:Float32Array}>} factVectors 归一化事实向量
+ * @returns {{hit:boolean, score:number, factId:string|null}}
+ */
+export function screenAgainstL2(queryVec, factVectors, threshold = 0.45) {
+  if (!queryVec || !factVectors?.length) return { hit: false, score: 0, factId: null };
+  let best = 0;
+  let bestId = null;
+  for (const f of factVectors) {
+    let dot = 0;
+    const n = Math.min(queryVec.length, f.vec.length);
+    for (let i = 0; i < n; i++) dot += queryVec[i] * f.vec[i];
+    if (dot > best) {
+      best = dot;
+      bestId = f.factId;
+    }
+  }
+  return { hit: best >= threshold, score: best, factId: bestId };
+}
+
+/**
+ * L2 初筛通过后掷骰子。返回是否应该接茬，以及原因（写审计用）。
+ * 只对 ambient 生效；direct / command 直接放行。
+ */
+export function shouldReplyToAmbient({
+  label,
+  l2 = { hit: false, score: 0 },
+  probability = 0.1,
+  random = Math.random,
+}) {
+  if (label !== 'ambient' && label !== 'relevant_ambient' && label !== 'uncertain') {
+    return { reply: true, reason: 'not-ambient' };
+  }
+  if (probability <= 0) return { reply: false, reason: 'probability-off' };
+  if (!l2.hit) return { reply: false, reason: 'no-l2-overlap', score: l2.score };
+  if (probability >= 1) return { reply: true, reason: 'probability-always', score: l2.score };
+  const hit = random() < probability;
+  return { reply: hit, reason: hit ? 'probability-hit' : 'probability-miss', score: l2.score };
+}

package/lib/api.js

@@ -0,0 +1,199 @@
+// 插件设置页的 JSON API（只认本机）：给客户端插件读/写设置与概览
+import { effectiveView, setOverride, clearOverride } from './settings.js';
+import { GROUPS } from './schema.js';
+import { createStatusHandler } from './status-page.js';
+import { listRecentSessions } from './sessions.js';
+import { ROUTE, API_BASE, apiUrl, dataDir, LOG_CLIENT_LOAD } from './const.js';
+
+const json = (res, status, body) => {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+  res.end(JSON.stringify(body));
+};
+
+function count(db, sql, ...args) {
+  try {
+    return db.prepare(sql).get(...args)?.c ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+export function createApiHandler(db, { cfg = {} } = {}) {
+  return async (req, res) => {
+    const host = String(req.headers?.host ?? '');
+    const name = host.split(':')[0].toLowerCase();
+    if (!(name === '127.0.0.1' || name === 'localhost' || name === '[::1]' || name === '::1')) {
+      return json(res, 403, { ok: false, error: 'forbidden' });
+    }
+    const url = new URL(req.url ?? '/', 'http://localhost');
+
+    // 客户端加载自检：浏览器端 apply 跑过就会打一条，用来确认前端那一半有没有起来
+    if (req.method === 'POST' && url.pathname === apiUrl('/client-loaded')) {
+      const chunks = [];
+      for await (const chunk of req) chunks.push(chunk);
+      let body = {};
+      try {
+        body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+      } catch {
+        /* 空体也可以 */
+      }
+      try {
+        const { appendFileSync, mkdirSync } = await import('node:fs');
+        const { join } = await import('node:path');
+        const dir = dataDir();
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(
+          join(dir, LOG_CLIENT_LOAD),
+          `${new Date().toISOString()}\t${String(body.key ?? '')}\t${String(body.id ?? '')}\t${String(body.version ?? '')}\n`,
+        );
+      } catch {
+        /* 记不下来不影响响应 */
+      }
+      return json(res, 200, { ok: true });
+    }
+
+    // 最近会话（供作用域选择用；只读标题、工作区与时间）
+    if (req.method === 'GET' && url.pathname === apiUrl('/sessions')) {
+      const limit = Math.min(Number(url.searchParams.get('limit') ?? 60), 200);
+      const sessions = listRecentSessions(limit);
+      return json(res, 200, { ok: true, rows: sessions });
+    }
+
+    // 概览
+    if (req.method === 'GET' && url.pathname === apiUrl('/overview')) {
+      return json(res, 200, {
+        ok: true,
+        schema: (() => {
+          try {
+            return db.prepare('PRAGMA user_version').get()?.user_version ?? 0;
+          } catch {
+            return 0;
+          }
+        })(),
+        facts: count(db, "SELECT count(*) c FROM fact WHERE status='active'"),
+        rules: count(db, "SELECT count(*) c FROM fact WHERE status='active' AND subtype='rule'"),
+        events: count(db, "SELECT count(*) c FROM event WHERE status='active' AND event_type='observation'"),
+        attention: count(db, "SELECT count(*) c FROM attention WHERE status='active'"),
+        pendingVectors: count(db, 'SELECT count(*) c FROM fact_version WHERE embedding_pending=1'),
+      });
+    }
+
+    // 读设置（含分组清单：页面按它渲染，不硬编码键名）
+    if (req.method === 'GET' && url.pathname === apiUrl('/settings')) {
+      return json(res, 200, { ok: true, groups: GROUPS, fields: effectiveView(db, cfg) });
+    }
+
+    // 写设置：{ values: { key: value } } 或 { clear: [key] }
+    if (req.method === 'POST' && url.pathname === apiUrl('/settings')) {
+      const chunks = [];
+      for await (const chunk of req) chunks.push(chunk);
+      let body;
+      try {
+        body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+      } catch {
+        return json(res, 400, { ok: false, error: 'invalid-json' });
+      }
+      const applied = [];
+      for (const [k, v] of Object.entries(body.values ?? {})) {
+        const r = setOverride(db, k, v);
+        if (!r.ok) return json(res, 400, { ok: false, error: `${k}:${r.error}` });
+        applied.push({ key: k, value: r.value });
+      }
+      for (const k of body.clear ?? []) {
+        clearOverride(db, String(k));
+        applied.push({ key: String(k), cleared: true });
+      }
+      return json(res, 200, { ok: true, applied });
+    }
+
+    // 事实列表（可按关键词过滤）
+    if (req.method === 'GET' && url.pathname === apiUrl('/facts')) {
+      const limit = Math.min(Number(url.searchParams.get('limit') ?? 30), 200);
+      const q = (url.searchParams.get('q') ?? '').trim();
+      const rows = q
+        ? db
+            .prepare(
+              `SELECT f.canonical_key AS key, f.subtype, f.scope, f.provenance_tier AS tier,
+                      v.value, f.updated_at AS updatedAt
+                 FROM fact f JOIN fact_version v ON v.fact_id=f.fact_id AND v.version=f.current_version
+                WHERE f.status='active' AND (f.canonical_key LIKE ? OR v.value LIKE ?)
+                ORDER BY f.updated_at DESC LIMIT ?`,
+            )
+            .all(`%${q}%`, `%${q}%`, limit)
+        : db
+            .prepare(
+              `SELECT f.canonical_key AS key, f.subtype, f.scope, f.provenance_tier AS tier,
+                      v.value, f.updated_at AS updatedAt
+                 FROM fact f JOIN fact_version v ON v.fact_id=f.fact_id AND v.version=f.current_version
+                WHERE f.status='active' ORDER BY f.updated_at DESC LIMIT ?`,
+            )
+            .all(limit);
+      return json(res, 200, { ok: true, rows });
+    }
+
+    // 经历列表
+    if (req.method === 'GET' && url.pathname === apiUrl('/events')) {
+      const limit = Math.min(Number(url.searchParams.get('limit') ?? 30), 200);
+      const rows = db
+        .prepare(
+          `SELECT content, speaker_name AS speaker, scope, occurred_at AS occurredAt
+             FROM event WHERE status='active' AND event_type='observation'
+            ORDER BY occurred_at DESC LIMIT ?`,
+        )
+        .all(limit);
+      return json(res, 200, { ok: true, rows });
+    }
+
+    // 关注点列表
+    if (req.method === 'GET' && url.pathname === apiUrl('/attention')) {
+      const rows = db
+        .prepare(
+          `SELECT attention_id AS id, label, note, weight, hits, last_hit_at AS lastHitAt
+             FROM attention WHERE status='active' ORDER BY weight DESC, created_at DESC LIMIT 200`,
+        )
+        .all();
+      return json(res, 200, { ok: true, rows });
+    }
+
+    // 退休一个关注点
+    if (req.method === 'POST' && url.pathname === apiUrl('/attention/retire')) {
+      const chunks = [];
+      for await (const chunk of req) chunks.push(chunk);
+      let body = {};
+      try {
+        body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+      } catch {
+        return json(res, 400, { ok: false, error: 'invalid-json' });
+      }
+      const id = String(body.id ?? '');
+      if (!id) return json(res, 400, { ok: false, error: 'missing-id' });
+      db.prepare("UPDATE attention SET status='retired' WHERE attention_id=?").run(id);
+      try {
+        db.prepare('DELETE FROM attention_fts WHERE attention_id=?').run(id);
+        db.prepare('DELETE FROM vec_attention WHERE rowid = (SELECT rowid FROM attention WHERE attention_id=?)').run(id);
+      } catch {
+        /* 向量表缺失忽略 */
+      }
+      return json(res, 200, { ok: true, retired: id });
+    }
+
+    return json(res, 404, { ok: false, error: 'not-found' });
+  };
+}
+
+/** 单一路由：/tide 与 /tide/api/* 共用一个前缀处理器。 */
+export function createPluginHandler(db, { dbFile, cfg } = {}) {
+  const api = createApiHandler(db, { cfg });
+  const page = createStatusHandler(db, { dbFile, cfg });
+  return async (req, res) => {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (url.pathname === API_BASE || url.pathname.startsWith(API_BASE + '/')) {
+      return api(req, res);
+    }
+    if (url.pathname === ROUTE || url.pathname === ROUTE + '/') {
+      return page(req, res);
+    }
+    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end('not found');
+  };
+}