天机阁算法天书 MengXingXiaoMing/dsh-tianjige

天机阁 · Algorithm Codex

English · · Español · Português · हिन्दी

插件只是接口，codex 本体放在上一层的 algo-hub 仓库里（data/algorithms.json + data/taxonomy.json）。独立安装包自带一份种子快照（seed/），首次运行时把种子写入 ~/.dsh/tianjige，所以没有仓库也能用同一个包。

功能

- 搜索 —— tianji_search 按自然语言或关键词查找算法，可按领域、功能键、成熟度、「是否已有现成实现」筛选。先严格匹配，匹配不到再退回部分匹配，结果里给出可点击的仓库/包链接。
- 档案 —— tianji_get 返回一条完整条目：原理、取舍、复杂度、论文、实现、同一功能下的其他变体、注意事项。
- 提问 —— tianji_ask 让模型先查 codex 来回答设计问题，也可以选择联网搜索 codex 之外的算法（findNew: true）。
- 扫描 —— tianji_sweep 联网搜索新算法，转成候选草稿放到 data/pending/，还能按天定时运行（action=status|start|config）。
- 策展 —— tianji_stage / tianji_update / tianji_review / tianji_review_mark / tianji_stats / tianji_usage 负责新增、编辑、审核、审计和 token 统计。
- 界面 —— 左侧边栏有一行入口，点开是整页视图，含四个标签页（Codex / Arena / Sweep / Ask），同一页面也能以右侧边栏标签页打开。

安装

包就是 tianjige-plugin/ 目录。把它装进 DSH 配置档并启用：

from the GitHub release (no npm account needed)
dsh plugin --profile desktop add https://github.com/MengXingXiaoMing/dsh-tianjige/releases/download/v1.3.0/dsh-tianjige-1.3.0.tgz

from npm, once the package is published
dsh plugin --profile desktop add dsh-tianjige

from a local checkout (development): add the directory itself
dsh plugin --profile desktop add C:\path\to\algo-hub\tianjige-plugin

如果你跑的是别的配置档，把 desktop 换成你自己的名字。装完重启 DSH：宿主那一半只在启动时导入一次，刷新页面不会重新加载。重启之前可以先跑 node --check host.js 和 node --check lib/.mjs 快速检查源码。

配置

插件通过 cordis.patch.yml 插入一行（id: tianjige）。两个键都可选：

| 键 | 默认值 | 含义 |
| dataDir | 本包的上级目录（= 仓库根目录） | codex 根目录，含 data/ 和 server/ai.mjs |
| defaultLimit | 8 | tianji_search 默认返回的行数 |

- insert:
- id: tianjige
name: dsh-tianjige
config:
dataDir: D:\wherever\algo-hub # optional, derived by default
defaultLimit: 8

数据布局

algo-hub/
data/
algorithms.json # 合并后的典籍库（219 条） taxonomy.json # 13 个领域 review.json # 审校记录 coverage.json # 扫描覆盖矩阵（扫描跑过一次后写入） staging/ # 各智能体提交的素材，等待合并 pending/ # AI 草稿，等待人工审校 runs/ # 每次扫描运行一份记录 logs/ # 页面错误报告（client-YYYY-MM-DD.log） server/ai.mjs # 旧网页版的 AI 逻辑（插件用的是 lib/ai.mjs） tools/algohub.py # 命令行：validate / merge / export / stats / coverage / record-run / snapshot …

从 npm 安装插件时，插件周围没有仓库，所以首次运行会把内置的起步库（seed/algorithms.json、seed/taxonomy.json）复制到 ~/.dsh/tianjige，之后所有写入都落在这里。设置 dataDir（或 DSH_TIANJIGE_DATA_DIR）可以覆盖这个位置；链接安装 / 开发安装仍然使用仓库根目录。

兼容性

- DSH >=0.2.1-rc.2（dsh.engines.dsh），Node ^22.19.0 || >=24.0.0
- 完全不依赖 @deepseek-ai/：宿主入口没有任何 import，数据层和 AI 层都通过动态 import 加载，所以配置档里的副本永远不会遮蔽运行时版本。
- AI 工具（ask / sweep / AI 辅助审校）需要 DEEPSEEK_API_KEY：环境变量，或 ~/.dsh/.credentials.yaml 里的 DEEPSEEK_API_KEY: 行。没有 key 时其他工具照常工作，AI 工具返回 AI_NO_KEY。
- 唯一的 peer 依赖是 react（客户端部分，由 harness 提供）。

工具

| 工具 | 用途 |
| tianji_search | 搜索条目（query，可选 domain / functionKey / maturity / hasImpl / limit） |
| tianji_get | 按 id 取完整档案 |
| tianji_ask | 自然语言设计问题（task，可选 findNew 联网搜索） |
| tianji_sweep | 扫描：action=status / start / config（每日自动扫描开关与间隔） |
| tianji_stage | 暂存新候选（写入 data/staging/，等待人工合并） |
| tianji_update | 原地编辑已有条目（自动备份） |
| tianji_review / tianji_review_mark | 审校队列：列出条目 / 记录结论 |
| tianji_stats | 典籍库审计：条目数、领域分布、实现覆盖率、审校进度 |
| tianji_usage | AI token 记录（读取 / 删除 / 清空 / 保留期） |

界面入口

插件注册三个位置：

- sidebar.panellist —— 左侧边栏一行「天机阁」（order: 120）
- main —— 从这一行打开的整页视图（标签页：Codex / Arena / Sweep / Ask）
- sidebar.right.pane.tab —— 同一页面作为右侧边栏标签页

页面数据走宿主路由 /api/tianjige/{library,meta,sweep,ask,review,usage,write,log}，只接受回环请求。没有 webServer 服务时，插件降级为「只有工具，没有页面」。

故障排查

- 安装后什么都没出现 — 先重启 DSH；再检查 plugin_manager 返回的 application 字段。
- 页面提示「sweep status unavailable」 — 通常是某个依赖模块加载失败（比如缺少 lib/ai.mjs）；路由会把错误写进 /api/tianjige/meta 的 500 响应。用 node --check lib/sweep.mjs 检查。
- tianji_ask 报 AI_NO_KEY — 按「兼容性」一节的说明配置密钥。
- 数据校验 — 运行 python tools/algohub.py validate（预期 0 个错误、0 个警告），再用 doctor 做引用检查。

开发

- 宿主端：host.js（入口，工具 + 路由）、lib/sweep.mjs（sweep / review / ask）、lib/ai.mjs（AI 调用与提示词）、lib/usage.mjs（token 账本）、lib/entries.mjs（条目读写辅助函数）。
- 客户端：lib/client.js（React，单文件 bundle，注册进一个 slot）。
- 测试：npm test 运行 node --test test/smoke.test.mjs — 离线、零依赖，针对 test/fixtures/；不碰真实数据，也不需要先安装插件。
- 静态检查：dsh-plugin-dev check --strict（来自 dsh-plugin-guide 技能包），以及对每个入口跑 node --check。

发布

有两条分发渠道；两条都是可选的，GitHub 始终是事实来源。

打一个 release（维护者）。 提升 version，跑 npm test 和 dsh-plugin-dev check --strict，然后打包 tarball 并挂到 GitHub release 上：

npm pack
gh release create v<version> dsh-tianjige-<version>.tgz --title "v<version>" --notes "..."

npm（可选）。 npm login 之后运行 npm publish --access public。用户随后用 dsh plugin --profile desktop add dsh-tianjige 安装。上架市场不要求发布到 npm。

DSH 市场。 注册信息放在 awesome-dsh-plugin/awesome-dsh-plugin：每个插件一个文件，路径为 data/plugins/<owner>__<repo>.yml，内含 url、name、category、可选的 tarball，以及 description.en（能写就再加 description.zh）。要求是：仓库公开；package.json 里有 dsh.bundle.patch，根目录有 cordis.patch.yml；带 dsh-plugin topic；描述与代码相符；仓库至少创建满一天 — 最后这条会自动检查，用来过滤掉提 PR 前几分钟才建的仓库。从你的 fork 开 PR；合并后，市场列出的就是这条注册信息。

精选列表（可选）。 DshMarketPlace/awesome-dsh-plugin 维护 data/curated.yml。往那里提 PR 属于推荐，不是注册，所以等注册信息合并之后再提。

许可证

MIT — 见 LICENSE。