UI 增强

dsh-101

bill9109/dsh-101 · ★ 6

bill9109精选

DSH 文档阅读模式。

许可证
BSD-3-Clause
收录
2026-08-13
维护状态
active
安装方式
github
查看 manifest 检查详情
manifest 状态
已声明
manifest 路径
package.json#dsh
manifest 检查
2026-08-19
生命周期脚本
未发现

manifest 静态检查只记录声明与安装脚本,不代表兼容性或安全审查。

安装

dsh plugin --profile web add github:bill9109/dsh-101

GitHub 源码安装:首次需按提示配置 allowBuilds 构建授权后重试

安装与环境配置指引、插件开发教程见 DSH 中文社区文档 ↗

项目说明

原始 README · 正文语言:中文 · 阅读英文 README

目录
  1. 为什么需要它
  2. 实现能力
  3. 使用
  4. 安装
  5. 端口
  6. 升级
  7. 卸载
  8. 故障排查
  9. 目录结构
  10. 构建
  11. 重新生成语料
  12. 从更新的 DSH 快照升级
  13. 开发与验证
  14. 社区与关于
  15. License

Release v0.1.7 License: BSD-3-Clause Node.js DSH profiles

安装: bash <(curl -fsSL https://raw.githubusercontent.com/bill9109/dsh-101/main/scripts/install.sh) github:bill9109/dsh-101#v0.1.7

DSH 101 文档阅读器 profile bundle:构建于 dsh-base + dsh-web-app 之上的文档优先阅读界面,把 DSH 自带文档整理成一份有顺序、可检索、可翻译的阅读器。

English | 中文

为什么需要它

DSH 自带大量文档,但原始形态就是一坨文件:散落在源码树各处,没有顺序、没有检索、读起来也不舒服。dsh-101 把这些文档变成 DSH 体验的一等公民——一份经过整理、有顺序、可检索、可翻译的阅读器,而不是裸文件;右侧的对话面板就在旁边,边读边问。

实现能力

  • 整理了 DSH 自带的文档,分门别类,有一定的顺序
  • 自带文档翻译能力
  • 有一个滑动式隐藏目录
  • 对话在右侧

使用

启动 profile(默认端口 3081,与 3080 的 web GUI 并存):

dsh --profile dsh-101

打开 http://127.0.0.1:3081(或你指定的端口):阅读器展示整理好的语料,带滑动式目录;搜索可以过滤文档,翻译可以切换阅读语言,右侧面板就是你熟悉的 DSH 对话。

安装

本仓库同时包含 bundle(@bill9109/dsh-101,可 dsh plugin add)和 profile/ 目录(完整的 dsh-101 profile 组合:dsh-base + dsh-web-app + 本 bundle)。DSH 官方模型是"分发 bundle、用户组合 profile",官方没有分发 profile 的命令,但 profile 本质是 $DSH_HOME/profiles/<name>/ 下的一个目录 —— 仓库的 profile/ 就是可直接使用的 profile 内容。

推荐:一键脚本(把 profile/ 放到 ~/.dsh/profiles/dsh-101/ 并安装 bundle):

# 从 GitHub 安装(建议 pin 到 tag/commit):
bash <(curl -fsSL https://raw.githubusercontent.com/bill9109/dsh-101/main/scripts/install.sh) github:bill9109/dsh-101#v0.1.7

# 或从本地 checkout 安装,并指定端口(默认 3081):
./scripts/install.sh --port 3081 .

# 启动:
dsh --profile dsh-101

脚本做的事:把 profile/ 的三个文件放进 $DSH_HOME/profiles/dsh-101/(已有则只补 缺失的 dsh-base/dsh-web-app 层),触发 DSH 模块回退(供运行时解析内置 peer), 然后 dsh plugin --profile dsh-101 add 安装本 bundle。

纯手动:

mkdir -p ~/.dsh/profiles/dsh-101
cp profile/package.json profile/pnpm-workspace.yaml ~/.dsh/profiles/dsh-101/
# 可选:端口 patch
cp profile/cordis.patch.yml ~/.dsh/profiles/dsh-101/
# 安装 bundle(会追加到 bundles 列表)
dsh plugin --profile dsh-101 add github:bill9109/dsh-101#v0.1.7
dsh --profile dsh-101

验证 bundles 列表应包含三层:

python3 -c "import json; print(json.load(open('$HOME/.dsh/profiles/dsh-101/package.json'))['dsh']['profile']['bundles'])"
# 期望:['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@bill9109/dsh-101']

不要装进 web profile。 dsh-101 的 bundle 会禁用 ui-layout(默认浏览器外壳), 装进 web-app 系 profile 会连坐搞挂 web(sidebar / conversation / app-shell 全部等待 layout 服务而 pending,web 起不来)。dsh-101 请始终作为独立 profile 使用 (dsh --profile dsh-101,默认 3081 端口,可与 3080 的 web 并存)。install.sh 已对 --profile web 直接拒绝。

端口

默认 3081(与 3080 的 web GUI 并存)。两种改法:

启动时临时指定(推荐,不改配置,dsh 0.1.0-rc.6+):

dsh --profile dsh-101 --port 8080

改 profile 配置(持久化默认端口):

# ~/.dsh/profiles/dsh-101/cordis.patch.yml
- id: webserver
  inject: [webStartup]
  config:
    host: !!js ctx.webStartup.host ?? '127.0.0.1'
    port: !!js ctx.webStartup.port ?? 8080

(启动参数优先;patch 里的值只是回退默认。)

Git 安装与构建产物。 lib/ 已提交到本仓库,所以 git 安装直接拿到构建好的 host + client bundle —— 无需构建、无需授权。若在构建前从全新 clone 安装, 先运行 node scripts/build.mjs(需要 DSH 源码 checkout,见下)。

升级

用新的 pin tag 重跑一键脚本:

bash <(curl -fsSL https://raw.githubusercontent.com/bill9109/dsh-101/main/scripts/install.sh) github:bill9109/dsh-101#v<新版本>

本地 checkout 安装则对更新后的 checkout 重跑 ./scripts/install.sh .(脚本只补缺失的 层,profile 现有状态不会丢)。DSH 发布新快照后,用 node scripts/upgrade.mjs 从升级后的 checkout 同步 bundle 源码(见「从更新的 DSH 快照升级」)。

卸载

dsh plugin --profile dsh-101 remove @bill9109/dsh-101
# 如果不再需要这个独立 profile:
rm -rf ~/.dsh/profiles/dsh-101

第一条命令在 profile 目录执行 pnpm remove 并从 dsh.profile.bundles 移除该 bundle; 第二条删除独立 profile 本身。

故障排查

症状 解决
安装 dsh-101 后 web GUI(3080)起不来 / sidebar 一直 pending dsh-101 被装进了 web profile,禁用了 ui-layout —— 把 @bill9109/dsh-101 从 web profile 移除,再用一键脚本把 dsh-101 装成独立 profile
dsh --profile dsh-101 启动失败 确认 $DSH_HOME/profiles/dsh-101/ 存在且 bundles 列表包含三层(dsh-base、dsh-web-app、@bill9109/dsh-101);缺层就重跑 install.sh
端口 3081 被占用 启动时加 --port <port>,或在 profile 的 cordis.patch.yml 里持久化别的默认端口
GitHub 安装失败或装到旧代码 把安装 pin 到 tag(github:bill9109/dsh-101#v0.1.7),或从本地 checkout 安装(./scripts/install.sh .)
文档缺失或过期 从 DSH 源码 checkout 重新生成语料:DSH_CHECKOUT=/path/to/dsh node scripts/build.mjs --corpus
DSH 发布新快照后出问题 用 node scripts/upgrade.mjs --checkout /path/to/upgraded-dsh 同步源码并重建

目录结构

src/
  app/        主机插件:语料服务 + /api/dsh101 路由(来自 dsh-101-app)
  app/invariant.ts
  core/       语料模型:加载、合并、搜索(来自 dsh-101-core)
  tutor/      主机插件:模型工具、curator 技能(来自 dsh-101-tutor)
  client/     浏览器端:阅读器外壳(来自 dsh-101-app/src/client)
  invariant.ts
assets/dsh-101/   生成的语料(corpus.json + documents/ + images/)
cordis.patch.yml  bundle 补丁:挂载 app(包根)+ tutor(./tutor 子路径)
profile/          开箱即用的 dsh-101 profile(package.json + pnpm-workspace.yaml + cordis.patch.yml)
scripts/
  install.sh            一键 profile 安装脚本(install.sh --port <port> <src>)
  build.mjs             针对 DSH checkout 构建 host + client bundle
  gen-dsh-101-corpus.ts 从 DSH 源码树重新生成语料
  upgrade.mjs           从升级后的 DSH checkout 同步源码 + 重建
  verify-i18n.mjs       双语 README 一致性检查(node scripts/verify-i18n.mjs)

构建

bundle 的 peer 依赖从 DSH 安装解析 —— 可以是源码 checkout(DSH_CHECKOUT), 也可以是运行中 DSH 的模块回退($DSH_HOME/profiles/node_modules)。工具链 (tsc、tsdown)优先取 DSH 源码 checkout。

DSH_CHECKOUT=/path/to/dsh node scripts/build.mjs
# 重新生成语料后构建:
DSH_CHECKOUT=/path/to/dsh node scripts/build.mjs --corpus

build.mjs 把 DSH 的 peer 软链进 node_modules,依次运行 tsc(类型输出到 types/)和 tsdown(host bundle + client bundle 输出到 lib/),结束后移除软链。

通常不需要构建。 lib/ 已提交,dsh plugin add(GitHub / tarball / 本地 checkout)安装的都是构建好的 bundle。只有开发本仓库或执行 upgrade 同步后才需要构建。

重新生成语料

语料是 DSH 仓库文档的快照。从任意 DSH 源码 checkout 重新生成(使用该 checkout 的 tsx):

DSH_CHECKOUT=/path/to/dsh node scripts/build.mjs --corpus
# 或显式指定:
/path/to/dsh/node_modules/.bin/tsx scripts/gen-dsh-101-corpus.ts /path/to/dsh

从更新的 DSH 快照升级

DSH 仓库发布新快照后,从升级后的 checkout 同步本 bundle:

node scripts/upgrade.mjs --checkout /path/to/upgraded-dsh

脚本会:把 101 各包的源码复制到 src/ → 将内部 import 改写为相对路径 → 重新生成 语料 → 重建。之后审查 diff、提交、升版本号并打 tag:

git add -A && git commit -m "sync with DSH <snapshot>"
git tag v0.2.0 && git push origin main --tags

开发与验证

pnpm install
pnpm run build       # tsc + tsdown -> lib/(已提交)
pnpm run gen-corpus  # 从 DSH 源码树重新生成语料(需要 DSH_CHECKOUT)
node scripts/verify-i18n.mjs   # 双语 README 一致性

pnpm run build 把 host + client bundle 生成到 lib/,lib 已提交,消费方安装无需构建。 保持双语 README 同步:改 README.md 和 README.zh.md 任一侧都要同步另一侧,然后 node scripts/verify-i18n.mjs --write 重新记录 blob hash。

社区与关于

License

BSD-3-Clause