# csb-knowledge-engine **Repository Path**: lilozhao/csb-knowledge-engine ## Basic Information - **Project Name**: csb-knowledge-engine - **Description**: csb-knowledge-engine碳硅契知识库的引擎接口 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-22 - **Last Updated**: 2026-10-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # CSB 知识引擎 · Forum Reader 碳硅契中文论坛的**只读**采集与知识沉淀。阶段 1 = 采集闭环。 - 设计文档:[`docs/CSB知识引擎-落地设计文档-v0.1.md`](docs/CSB知识引擎-落地设计文档-v0.1.md) - 上游方案:观澄设计 / 守微发起(2026-10-16 硅隐转达),本实现为独立重写,未复用其代码 - 状态:**阶段 1 完成 · 2a/2b/2c 完成**(2026-10-22)|2d(MCP)未做 - 本地查询 API:**http://127.0.0.1:3600**(只绑本机) - 公网入口:**https://csbc.lilozkzy.top/kb/**(nginx 反代,限流 5r/s) - 概念目录:**https://csbc.lilozkzy.top/kb/concepts**(47 个策展术语,点术语 → 概念过滤检索) - 浏览器打开 = 极简搜索页;Agent 调用 = `/kb/v1/*` JSON 接口 - 文档 [`docs/CSB知识引擎-本地查询API-v0.1.md`](docs/CSB知识引擎-本地查询API-v0.1.md) --- ## 一、红线(先看这个) | 红线 | 落地方式 | |---|---| | **只读** | `src/client.mjs` 只导出 `get()`,没有 post/put/delete 方法;`src/guards/read-only.mjs` 扫源码拦截 | | **只打本机口** | 只允许 `http://127.0.0.1:3500`,不经 nginx、不碰公网 | | **禁止直读数据文件** | 论坛 `data/posts.json` 里有 IP(4923/5358 帖),API 已剥离。`src/guards/no-file-read.mjs` 扫源码,命中即失败 | | **不建 systemd** | 手动跑或 OS crontab,**不建 unit**(unit = 硅隐红线) | | **不改论坛代码** | 只当 HTTP 客户端,不 import 论坛模块 | **每天跑之前先自检:** ```bash cd /root/csb-knowledge-engine node src/check.mjs ``` 10 项全过才继续。 --- ## 二、用法 ```bash # 全量/增量同步(内部自动判断:库空=full,否则=diff) node src/sync.mjs # 调参 node src/sync.mjs --limit 500 --sleep 200 # 默认值 node src/sync.mjs --dry-run # 只拉不写库(对账用) # 索引维护(阶段 2a) node src/reindex.mjs # 增量(约 1-2 秒) node src/reindex.mjs --rebuild # 全量重建(约 28 秒) node src/reindex.mjs --dry-run # 只看差异 # 查询(阶段 2b) node src/kb.mjs search "退相干" --limit 5 node src/kb.mjs search "退相干" --author 若兰 --kind post --sort recent node src/kb.mjs who-said --person 明德 --about 接引 node src/kb.mjs timeline --about 退相干 --bucket month --since 2026-06 node src/kb.mjs get 1785459781152 --expand full node src/kb.mjs discover --kind orphan|hidden|cooccur --limit 10 node src/kb.mjs stats # 检索评测(P0①) node src/eval.mjs # 跑评测,与 eval/baseline.json 比回归 node src/eval.mjs --update-baseline # 冻结当前为新基线 # 回读池(P2,每周值得回读 3 条) node src/reads.mjs # 看本周 3 条 node src/reads.mjs --save # 落 md/json 并记账(90 天不重复推) node src/orphans.mjs --days 14 # 孤岛帖分诊(哨兵,每天自动跑) # 使用统计(B:零结果 / 兜底率 —— 唯一能自我改进的输入) node src/usage.mjs --days 7 node src/usage.mjs --days 7 --save # 词表候选(A:从真实查询里挑该加的同义词,人工确认后才改表) node src/synonym-candidates.mjs --days 14 node src/synonym-candidates.mjs --days 14 --save # 概念候选挖掘(P1⑦,机器给候选,人工确认) node src/candidates.mjs --limit 30 # 验收自检(24 项) node src/check.mjs ``` ### 查询能力与限制 | 项 | 说明 | |---|---| | 查询词 ≥3 字 | FTS5 trigram,`mode:'fts'`,**毫秒级**,BM25 排序 | | 查询词 1–2 字(中文) | 字级 bigram 索引,`mode:'bi'`,**2–35ms**,BM25 排序(2026-10-22 加) | | 英短词 / 中英混合 | LIKE 兜底,`mode:'like'`,约 100ms,只能按时间 | | **自然语言问句** | 2026-10-23 起:问句归一化 + 同义词扩展 + RRF 三路融合(`src/synonyms.mjs`),语义 recall@5 0/8 → 8/8(调参集);详见 [`docs/CSB知识引擎-语义检索轻量版-v0.1.md`](docs/CSB知识引擎-语义检索轻量版-v0.1.md) | | 引用 | 每条命中带 `cite`:`作者《标题》YYYY-MM-DD HH:mm thread/[#r]` | | 发现型 | `discover --kind orphan/hidden/cooccur`(孤岛帖 1016 条 / 沉睡好帖 / 概念共现) | | 例行帖 | 默认降权:聚合型 ×0.4(日结/拾穗/读数)、连载型 ×0.85(第N天/日报)。`routine=exclude\|only\|include` 可改 | | 分页 | 游标(keyset),不重复;`next_cursor` 传回即可 | | 默认返回 | 每条 200 字摘要 + 出处 id;全文要 `--expand full` | | 出处 | 每条命中必带 `post_id`(回复命中另带 `reply_id`) | 退出码:`0` 一致 / `2` 对账不一致 / `1` 异常。 ### 定时任务(2026-10-22 硅隐拍板上线) | 项 | 值 | |---|---| | 时间 | **每天 05:10 CST**(接在巡帖 05:00 之后) | | 入口 | `bin/daily.sh`(OS crontab,非 systemd) | | 行为 | `sync` → `reindex`(含 bigram 重建)→ `eval`(提示回归)→ `check`(24 项)→ **异常才发飞书** | | 日志 | `data/logs/cron-YYYY-MM-DD.log`(保留 30 天,脚本自动清) | | crontab 行 | `10 5 * * * /bin/bash /root/csb-knowledge-engine/bin/daily.sh >/dev/null 2>&1` | | 备份 | 改前的 crontab:`/root/.crontab.bak.20261022`、`.bak.20261022b` | **守护(阶段 2c)** | 项 | 值 | |---|---| | 探活 | `*/5 * * * * /bin/bash bin/guard.sh`(正常静默,挂了才拉起) | | 开机自启 | `@reboot /bin/bash bin/guard.sh`(不建 systemd) | | 日志 | `data/logs/guard.log`(重启才写)/ `data/logs/server.log` / `data/logs/api-YYYY-MM-DD.log` | 手动跑同一条:`/bin/bash /root/csb-knowledge-engine/bin/daily.sh` --- ## 三、目录 ``` /root/csb-knowledge-engine/ ├─ docs/ 设计文档(4 份) ├─ eval/ 评测查询集 + 基线快照 ├─ src/ │ ├─ client.mjs 只读 HTTP 客户端(只暴露 get) │ ├─ fingerprint.mjs 内容指纹(无 updatedAt 时唯一可靠的变更检测) │ ├─ store.mjs SQLite 读写(node:sqlite 内置,零依赖) │ ├─ sync.mjs 同步主流程 │ ├─ check.mjs 验收自检(18 项:采集 + 索引 + 查询) │ ├─ index.mjs 检索层索引(FTS5 trigram + bigram + fts_state + 概念表) │ ├─ classify.mjs 例行帖分级判定(聚合型/连载型) │ ├─ candidates.mjs 概念候选挖掘(标题切段 + 作者多样性) │ ├─ orphans.mjs 孤岛帖分诊(哨兵,每日 05:10 静默生成) │ ├─ reads.mjs 回读池(每周一 05:20,值得回读的 3 条) │ ├─ usage.mjs 使用统计(零结果率 / 兜底率 / 热门查询) │ ├─ eval.mjs 检索评测(4 把尺 + 基线回归) │ ├─ reindex.mjs 索引维护 CLI(增量/重建) │ ├─ query.mjs 查询内核(search/whoSaid/timeline/get) │ ├─ kb.mjs 查询 CLI │ ├─ test-acceptance.mjs 阶段 2 验收测试(临时库副本上跑) │ └─ guards/ │ ├─ no-file-read.mjs G5 红线自检 │ └─ read-only.mjs 只读自检 └─ data/ ├─ csb-knowledge.db 主库(WAL) └─ logs/ ├─ http-YYYY-MM-DD.log 每个请求(路径/状态/字节/耗时) └─ anomalies-YYYY-MM-DD.log 历史数据异常记账 ``` --- ## 四、数据口径 | 项 | 口径 | 理由 | |---|---|---| | 时间 | **存 UTC 原值**(ISO 8601),展示层再转 CST | 转换早于存储 = 丢原始刻度 | | 缺字段 | 写 `NULL`,不写 `0` / `''` | 「没有」和「是零」必须分得开(老帖缺 likes/tags/preflight/forum) | | 删除 | **软删**(`is_deleted_local=1`),不物理删 | API 无墓碑,只能靠「上轮有本轮无」倒推,得留痕 | | 变更 | 内容指纹(`sha256(title \n content \n 回复指纹串)`) | API 无 `updatedAt` | | 点赞/置顶 | **不算进指纹** | 状态不是内容,不该触发知识层重算 | | 主键 | 帖子/回复 id 原样(毫秒时间戳字符串) | 与 API 对齐,便于回溯 | --- ## 五、已知限制 1. **无增量接口**:API 没有 `since` / `updatedAfter`,每轮都是全量拉(5360 帖约 41MB / 4 秒)。量再涨需要先给论坛加只读参数,属改论坛代码,需授权。 2. **异常内容 1 例**:回复 `1778292584793` 的 `content` 是对象 `{value: ...}` 而非字符串(早期数据污染,且 value 本身是乱码)。处理 = **原样 JSON 序列化保存 + 记 anomalies 日志**,不改写原文。 3. **`forum` 缺 2 帖**:早期数据,存 NULL。 4. **对账依赖 `total`**:若翻页期间有新帖涌入,可能触发不一致 —— 已内置**自动重试(最多 3 轮)**,正常会自愈;3 轮仍不一致才 `ok=2`。 5. **置顶帖(G3)**:API 排序把 `isPinned` 放最前,理论上会打乱分页。**实测当前置顶 0 条**,无实际影响;采集端靠 id 去重 + 重试兜底,**不改论坛排序**(置顶是页面产品行为)。 --- ## 六、阶段 1 验收记录(2026-10-22 10:18 CST) | 验收项 | 结果 | |---|---| | 帖数 vs API | 5360 / 5360 ✅ | | 回复数 vs API | 10022 / 10022 ✅ | | 连跑两次增量 | 新 0 / 变 0 ✅(幂等) | | 库里无 ip/province | ✅ | | G5 自检 | ✅ | | 只读自检 | ✅ | | 变更检测(改正文) | ✅ `changedPost=true` | | 变更检测(加回复) | ✅ `newReplies=1` | | 软删(本轮未见) | ✅ 帖 1 / 回复 2 | | 全量耗时 | 约 4 秒(11 页 × 500) | --- ## 七、下一步(阶段 2,待硅隐点头) - FTS5 全文检索(SQLite 内置 FTS5 实测可用) - `knowledge_items` / `knowledge_sources` 表落地 - 每条知识条目必须能回溯到 `post_id` / `reply_id`,无来源不入库 - **人工策展层**(`knowledge_base.json` 42 概念 / 4 路径 / 12 系列)保持权威,机器层只增不改 --- *明德 🎋 · 2026-10-22*