dsh-geometry-knowledge

几何论（共扼谱几何 CSG）知识库插件 for DeepSeek Harness（DSH） —— 标准 DSH bundle，dsh plugin add 一条命令装好。

包内自带导出好的离线索引（data/），无需任何配置即可检索；同一套内核也可通过 mcp/server.mjs 作为 MCP 服务供 Codex++ 等客户端复用。

纯离线 BM25 检索：251 篇文章全文 + 4204 个分块 + 869 条有效真理（887 条历史快照），不依赖任何外部 API、嵌入模型或网络，安装即用。articles/ 根目录的 Markdown 是唯一内容真源，增删改后由本地程序自动原子重建派生索引、主张依赖图并运行一致性审计。检索、阅读、写入、本地状态、服务内主库与文件工具零运行时依赖；公式验证可选使用本机 Python + SymPy 做严格符号证明，geo_git_* 仅要求本机已装 git，geo_chat_* 走 Node 内置 node:sqlite（Node ≥ 22.5）或系统 sqlite3 命令，只有 geo_web_search 需要外网，geo_shell_execute 需本机可执行命令。

几何论是什么

几何论（共扼谱几何，Conjugate Spectral Geometry）是一套尝试通过少量而合理的实验数据锚定，正确描述这个物理世界的几何理论体系。它不宣称能从少量公理和假设必然地推导出整个物理世界。

公理起点：零之动（非平凡自映射 δ 持续产生区分）+ 总作用量为零（S_total = 0）
推导主干：δ → Clifford 代数 → Bott 周期（δ⁸ = 2π Berry 相位）→ E₈ 偶幺模格 → 结构常数 {2,3,5} → 乘子序列 → Born 法则代数导出 → M₅ Birkhoff 矩阵不动点 → α⁻¹ ≈ 137.036 → 三扇区物理（ℳ物质 / 𝒞因果 / ℐ信息）→ 标准模型重建 → 引力与宇宙学 → 预言检验
11 卷 251 篇根目录文章，覆盖从量子力学数学结构、夸克质量谱、中微子 Majorana 本质，到暗物质替代、黑洞信息悖论、CMB、量子纠错码等主题

本插件把整套知识库做成 31 个 DSH 原生工具（ctx.tools.register，非 MCP 转接），让 Agent 在会话中直接检索原文与已验证定理，并强制标注文章编号与章节引用。

提供的工具（31 个）

检索与阅读（5）

工具	说明
`geo_list`	文章清单（编号、标题、文件名、分块数），可按系列过滤（如 `series="10."` 只看应用篇）
`geo_search`	BM25 语义检索：`scope=articles` 检索 4204 个文章分块；`scope=truth` 检索 869 条有效真理
`geo_read`	读取文章：默认结构摘要视图（元信息+章节目录+核心结论速览），`section` 关键词精确定位章节，`whole=true` 整篇；带翻页防护（顺序翻页警告 + 单篇 25000 字符上限）
`geo_calc`	精确数学计算（纯 JS 安全求值，零依赖）：四则/幂/三角/对数/开方，多行赋值，会话内中间变量跨调用保留
`geo_truth`	当前有效真理层检索（含永久编号 #N、公式名、证明摘要；superseded 条目自动排除）

深度推理与审计（4）

工具	说明
`geo_claim`	查询程序生成的类型化主张依赖图。主张身份为“属地文章 + 声明类型 + 编号”，支持定义、公理、定理、命题、引理、推论、性质、注记、猜想、验证、观察、机制、结论、对应命题与开放问题；跨文章复述标为 `restatement`，边区分 `depends_on` / `mentions` / `equivalent_to`
`geo_verify`	验证 `lhs = rhs`。优先用本机 SymPy 严格符号化简；无法判定时可按确定性数值抽样检查，但会明确标注“数值一致（非证明）”。支持常见 LaTeX（`\frac`、`\sqrt`、希腊字母等）。SymPy 是可选增强；缺少 Python/SymPy 时明确报错，不会把未验证公式报成通过
`geo_sector_assign`	求解 3.23 的简单谱三扇区有限指派：输入 n×3 权重矩阵与 `[n_M,n_C,n_I]`，返回最优/次优本征模指派、扇区偏移成本、选择间隙和唯一性判据
`geo_audit`	一致性审计：定义身份冲突、悬空/歧义引用、强依赖环、真理层重复编号/名称、真理编号缺少文章定义、数据库是否落后于文章真源。普通 `mentions` 环不算逻辑错误。`scope=graph / truth / index / all`

写入与整理（3）

工具	说明
`geo_edit_article`	精确锚点局部替换。`replacements` 传 `[{old_text,new_text}]` 或 JSON 字符串；锚点必须唯一命中，重复/区间重叠/仅空白差异一律失败即报错、整篇不落盘（`replace_all=true` 才全量替换，`dry_run=true` 只校验）。覆盖前自动备份到 `articles/archive/`；写后同步本会话索引，并检查主张关系网：同类型声明改号默认自动更新全库精确引用，正文语义变更列出关联文章等待复核
`geo_write_article`	写入/追加知识库文章。覆盖前自动备份到 `articles/archive/<原名>_<时间戳>.md`；新内容不足原文件 30% 触发截断保护并中止。写后同样执行主张关系网检查与同类型改号引用同步
`geo_manage_articles`	`action ∈ archive / list_archive / create_dir / move / rename / delete`；`filename` 接受文章编号前缀（如 `"0.10"`）或文件名

工作区文件（3）

工具	说明
`geo_file_list`	glob 列目录（`` `?` `*` `[...]`），自动跳过 `.git`、`node_modules`、`__pycache__`、`.venv`、`chroma_db` 等噪声目录
`geo_file_read`	读工作区任意项目文件，`offset`/`limit` 分页，单文件上限 2.5MB
`geo_file_write`	写入/追加工作区文件（自动建父目录），覆盖且新内容不足原文件 30% 时触发截断保护

服务内主库与联网（5，P3）

工具	说明
`geo_master_status`	服务内主库状态：真理有效/总条数、superseded 数、提交队列、事件日志与实际落盘路径
`geo_master_truth`	直接读取 `truth.jsonl` 并归并 `truth_events.jsonl`：支持 `#N` 精确取与 BM25；`include_superseded=true` 可审计旧结论
`geo_submit_formula`	提交候选公式到服务内待审队列（先本地校验必填项与 `topology_class ∈ {A0,A1}`；不伪造自动证明）
`geo_submissions`	本地队列 `action ∈ list / check / withdraw / supersede`（撤回仅限本人且未入库；supersede 只追加审计事件，不改原文）
`geo_web_search`	互联网搜索（Serper/Google）：查实验数据与外部文献；结果只作外部实验锚定输入，不得写入真理层

本地状态（8）

工具	说明
`geo_time`	当前日期时间（中文契约：`YYYY年MM月DD日 HH:MM:SS 星期X`，`Asia/Shanghai`，附 `YYMMDD`）——写文章版本号日期前先确认
`geo_personal_read`	读取个人库（性格、想法、记忆、情绪等）
`geo_personal_write`	写入个人库指定分类/子字段（子字段不存在时自动创建；已存在且非数组时中止写入，防误覆盖）
`geo_teach_correction`	记录"被纠正的错误表述 → 正确表述"（含原因、上下文、信任度）
`geo_teach_antipattern`	记录禁止出现的表述模式（severity: high/medium/low）
`geo_teach_patch`	记录补丁（主题 + 内容 + 来源）
`geo_git_commit`	提交当前改动（留空 message 则自动生成）
`geo_git_history`	查看提交/文件历史

会话数据与命令执行（3，P4）

工具	说明
`geo_chat_history`	Open WebUI 历史对话列表（只读 `webui.db`；`keyword` 按标题模糊过滤），拿 id 后交给 `geo_chat_read`
`geo_chat_read`	读取指定历史对话全文（按对话树正向遍历；`chat_id` 可只给前几位，多命中时列候选）
`geo_shell_execute`	在项目根内执行命令（编译 / 测试 / git / 部署）：区分推导与编程任务各自配额，命中高危黑名单或试图读 `.md` 文章一律拒执行；`allowShell=false` 整体禁用

独立仓库

本服务从 conjugate-spectral-geometry （主项目仓库）拆分为独立仓库发布，便于通过 npm / tarball / git 三种方式分发。

安装

DeepSeek Harness（DSH）

# 从 npm 安装
dsh plugin add dsh-geometry-knowledge

# 或直接从 GitHub 安装
dsh plugin add github:sdoygb/dsh-geometry-knowledge

dsh plugin add 会自动把本包追加进该 profile 的 dsh.profile.bundles；本包自带的配置层 cordis.patch.yml 随即把 geometry-knowledge 插件行插入 loader，31 个 geo_* 工具立即可用。

指定 profile：dsh plugin --profile web add dsh-geometry-knowledge。

默认零配置 —— 插件直接读取包内 data/ 索引。要改用自己的文章库，在该 profile 的 cordis.patch.yml 里按 id 覆盖配置（profile 层在本包层之后应用）：

- id: geometry-knowledge
  config:
    dataDir: /absolute/path/to/codex++-data
    sourceArticlesDir: /absolute/path/to/app/articles
    stateDir: /absolute/path/to/.geometry-knowledge
    allowShell: false

Codex++ / 其他 MCP 客户端

同一内核也可作为 stdio MCP 服务运行：

python3 mcp/install_codex.py
python3 mcp/install_codex.py --check
node mcp/smoke.mjs

从源码构建

npm install
npm run build     # tsc → dist/
npm run check     # build + 单元测试 + 冒烟测试

使用示例

geo_list series="7."          → 标准模型重建卷的全部文章清单
geo_search "弱混合角"         → 检索弱混合角相关分块
geo_search "谱刚性" scope=truth → 检索当前有效真理
geo_read "10.8" section="Strouhal" → 读取 10.8 的 Strouhal 数推导章节
geo_read "7.5"                → 7.5 的结构摘要视图（默认，省 token）
geo_calc "57.93+26.16+5.91"   → 90（精确计算）
geo_calc "D=10/7821; D*2"     → 0.00256（会话内变量保留）
geo_read "7.5" whole=true     → 读取整篇 7.5 弱混合角
geo_claim number="10.17.7.02" depth=2 direction="dependencies" → 展开该主张显式引用的前置依据
geo_verify lhs="sin(x)^2+cos(x)^2" rhs="1" variables='["x"]' → 严格符号验证通过
geo_audit scope="graph" limit=20 → 列定义冲突、悬空/歧义引用与强依赖环
geo_time                      → 2026年09月10日 14:03:21 星期四（Asia/Shanghai）
geo_file_list pattern="**/*.py" → 列出工作区 Python 脚本
geo_write_article filename="10.41_xxx_CN_260910.md" content="..." → 写入并立即参与本会话检索
geo_edit_article filename="10.8" replacements='[{"old_text":"旧句。","new_text":"新句。"}]' → 精确替换（锚点不唯一会拒绝）
geo_manage_articles action="archive" filename="0.10" → 归档 0.10 并从本会话检索中移除
geo_git_commit message="10.41 补充 X 节" → 提交改动
geo_master_truth "#88"        → 服务内真理层按永久编号精确取
geo_master_truth query="半群强收敛" include_superseded=true → 连旧结论一起审计
geo_master_status             → 服务内主库状态 + 实际数据路径
geo_submissions action="supersede" permanent_number=427 reason="原论证不成立" → 追加取代事件
geo_chat_history limit=5      → 最近 5 条历史对话（取 id）
geo_chat_read chat_id="0ae3"  → 读取该对话全文
geo_shell_execute command="npm test" → 在项目根跑测试（编译/测试类任务配额更宽）

检索提示：先提取文章中的精确术语（如 θ_M、N_dec、η_K、Strouhal、谱刚性、弱混合角、Kolmogorov）效果最佳。

文章真源与索引同步

app/articles/*.md 是唯一内容真源；articles.jsonl、articles_toc.json、claims.jsonl、claim_graph.json、claim_repair.json 和 manifest.json 都是随时可重建的派生数据。整个同步过程只做本地扫描、分块、类型化依赖图解析、修复工作单生成和原子替换，不调用大模型，也不需要网络。

truth.jsonl 是真理条目快照，truth_events.jsonl 是不可变状态日志，master_submissions.jsonl 是本地提交与撤回的追加式队列。文章同步不会覆盖这三个文件；supersede 也不会改写 truth.jsonl 原行，而是由查询层归并事件得到最新状态。

geo_write_article、geo_edit_article、geo_manage_articles 修改文章后，程序立即重建磁盘索引；当前会话和后续重启都能检索到新内容
MCP 服务运行期间默认监听文章目录，其他 AI 或编辑器写入 .md 后会去抖重建；fs.watch 漏事件时由周期校对兜底
下一次 geo_* 工具调用发现 manifest.json 的 generation 变化后，会自动重载 BM25 索引，无需重启 MCP 服务
同名文章被多个写入方同时修改时，不做文本合并；以磁盘稳定后的最终内容为准。文章仍在写入时同步会重试，不会把半截内容写进索引
只读取 articles/ 根目录下的 .md；archive/ 等所有子目录、隐藏文件和常见临时文件都不参与索引

仓库内可直接使用独立同步器：

# 单次重建
node mcp/indexer.mjs sync

# 对比文章与 manifest 的 generation；不同则退出码为 1
node mcp/indexer.mjs status

# 常驻监听（Codex 关闭时也可运行，适合其他 AI 持续写文章的场景）
node mcp/indexer.mjs watch

GEO_ARTICLES_DIR 指定文章真源，GEO_DATA_DIR 指定插件数据库目录。当前开发工作区使用：

数据库：<仓库根>/codex++-data/
文章真源：<仓库根>/app/articles/

数据目录与来源优先级

派生索引的数据来源按以下顺序解析：

插件配置 dataDir
环境变量 GEO_DATA_DIR
包内自带索引 <包根>/data/（发布包默认，零配置开箱即用）
开发工作区 <仓库根>/codex++-data/

文章真源由 sourceArticlesDir / GEO_ARTICLES_DIR 单独指定（缺省为 <dataDir>/articles），可与派生索引目录分离。主库真理、事件与提交队列都位于同一个 dataDir，不需要 masterUrl 或 masterToken。插件不会读取其他 AI 使用的 geo-data/。

本地状态目录

个人库与教学日志默认落在知识库数据目录（可用插件配置 stateDir 单独指定；启动日志会打印确切路径）：

personal.json —— geo_personal_* 读写
teaching.jsonl —— geo_teach_* 追加

可选能力与降级

P3 / P4 的可选能力都可单独关闭，关闭后其余工具不受影响：

联网闸门：配置 offline=true（或环境变量 GEO_OFFLINE=1）时只禁用 geo_web_search。geo_master_* 与 geo_submissions 是本地文件能力，离线时仍全部可用
命令执行：配置 allowShell=false（或 GEO_ALLOW_SHELL=0）可关掉 geo_shell_execute；开启时仍受三层约束——推导类与编程类任务各自配额（用尽即拒绝）、高危命令黑名单、以及 .md 文章读取拦截（读文章请走 geo_read）
历史对话：对话库路径按 chatDbPath 配置 → 环境变量 → 常见候选路径依次解析；后端 chatDbBackend ∈ auto / node / cli（默认 auto：先 Node 内置 node:sqlite，失败回退 sqlite3 命令）。读不到 chat 表时明确报「请确认这是 Open WebUI 的 webui.db」，不静默失败
公式验证：geo_verify 默认调用 python3 与本机 SymPy；可通过 GEO_PYTHON 指定解释器。缺少 Python/SymPy 或表达式不受支持时返回明确错误或“无法判定”，不会降级成虚假的验证成功
密钥：geo_web_search 密钥按插件配置 serperApiKey → SERPER_API_KEY / GEO_SERPER_API_KEY 解析；未配置时返回三种配置方式而非报错堆栈

数据与构建

app/articles/*.md 是唯一内容真源；codex++-data/articles.jsonl、codex++-data/articles_toc.json、codex++-data/claims.jsonl、codex++-data/claim_graph.json、codex++-data/claim_repair.json、codex++-data/manifest.json 由 node mcp/indexer.mjs sync 程序化重建
codex++-data/truth.jsonl、codex++-data/truth_events.jsonl、codex++-data/master_submissions.jsonl 由服务内主库直接读写，不需要 Flask、ChromaDB、端口 5001 或常驻验证服务
codex++-data/claim_repair.json 是修复工作单：每条问题包含当前站点、候选定义、建议动作与理由；它本身只提出修正方案，不自动改文章
geo_edit_article / geo_write_article 会额外执行确定性关系网同步：同一文章内“同一声明类型 + 同一标题”的编号变化，默认更新全库同类精确引用；关联文章改写前先备份，任一写入失败则回滚本次已替换文件。sync_references=false 可关闭自动引用同步
正文含义变化不做无约束自动改写：插件会列出所有强依赖与提及来源，返回需要语义复核的文章；这类跨文章修正仍需调用方逐篇读取、改写并重新审计
服务运行时不读取 ChromaDB，也不启动 Flask 或常驻主库服务；派生索引统一由 node mcp/indexer.mjs sync 从文章真源重建
dist/ 由 TypeScript 编译：npm run build
单元测试：npm test（先 tsc 再跑 tests/unit/*.test.mjs）
冒烟测试：npm run smoke

引用规范

所有检索结果必须标注文章编号（article_id/fname）与章节；真理层条目优先引用永久编号 #N。

许可证

MIT

dsh-geometry-knowledge

Installer

README