文档优先阅读器bill9109/dsh-101

dsh-101 — DSH 文档优先阅读器 profile bundle

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

安装： bash / 下的一个目录 —— 仓库的
profile/ 就是可直接使用的 profile 内容。

推荐：一键脚本（把 profile/ 放到 ~/.dsh/profiles/dsh-101/ 并安装 bundle）：

从 GitHub 安装（建议 pin 到 tag/commit）：
bash  不要装进 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+）：
sh
dsh --profile dsh-101 --port 8080

改 profile 配置（持久化默认端口）：
yaml
~/.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 重跑一键脚本：
sh
bash

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

卸载
sh
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 ，或在 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  ）
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。
sh
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）：
sh
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：
sh
node scripts/upgrade.mjs --checkout /path/to/upgraded-dsh

脚本会：把 101 各包的源码复制到 src/ → 将内部 import 改写为相对路径 → 重新生成
语料 → 重建。之后审查 diff、提交、升版本号并打 tag：
sh
git add -A && git commit -m "sync with DSH "
git tag v0.2.0 && git push origin main --tags

开发与验证
sh
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。

社区与关于

- 可复现的 bug、聚焦的功能请求和使用问题，走 GitHub Issues。
- 提变更前先读 CONTRIBUTING.md；安全问题通过 SECURITY.md 私有上报。
- 版本与兼容性说明见 CHANGELOG.md。

License

BSD-3-Clause