dsh-agents-viewer
在 DSH（DeepSeek Harness）右侧栏的原生 tab 里查看和编辑 AGENTS.md 指令链 —— 聊天头部还有一个一键打开的按钮，外加一个 /agents 命令。
需要带 ctx.sidebarRightTabs 的 DSH。0.2.2-rc.1（Electron 44.7.0）已验证；engines.dsh 只保留下限 >=0.2.2-rc.1，dsh.client.inject 为空，服务全部在运行时探测。这样 DSH 小版本更新不需要改清单；真改了 API，最坏是少一个 tab，DSH 仍能启动。
功能
-
右侧栏原生 tab：在右侧栏的「添加」菜单 / 引导页里打开 AGENTS.md。用 DSH 自己的 tab、分栏、全屏、拖拽和收起，不再有浮动抽屉、遮罩、requestAnimationFrame 跟随，也不会出现「等 30 秒兜底按钮」。
-
聊天头部按钮：文件/侧栏按钮那一簇的左边有一个 AGENTS.md 图标，点一下打开原生 tab；右侧栏已展开且当前就是 AGENTS.md 时，再点一次收起侧栏。默认显示；/agents c / /agents o 把状态写入持久化文件，下次启动 DSH 后按新状态显示/隐藏。
-
完整指令链：全局 ~/.dsh/AGENTS.md、共享 ~/.agents/AGENTS.md，以及项目根到会话 cwd 的每一层目录下的 AGENTS.md / CLAUDE.md / AGENTS.local.md / CLAUDE.local.md。面板与 /agents 命令现在同一口径，子目录里的文件也能直接改。
-
精确项目：tab 正文从标准 props 拿到 sessionId / useSessions，宿主按 session id 反查 workspace；不再用「最近更新的工作区」猜。
-
原地编辑保存：列表点选 → 编辑 → Ctrl+S 或「保存」；不存在的文件写内容保存即创建。
-
/agents 命令（不依赖界面，任何情况可用）：
/agents 列出所有 AGENTS.md
/agents <序号> 看全文
/agents all 看全部
/agents w <序号> 用外部编辑器打开
/agents n 新建（项目级）
/agents n global 新建全局
/agents n shared 新建共享
/agents o 记录“显示按钮”（下次启动生效）
/agents c 记录“隐藏按钮”（下次启动生效）
/agents help 用法
安装（给别人用）
这个包是标准的 DSH dual-face bundle：宿主半在 index.js，客户端半在 runtime/client.js，由 package.json 的 dsh.client 声明。装进某个 profile：
$profile = "$env:USERPROFILE\.dsh\profiles\desktop"
$name = "dsh-agents-viewer"
# 1) 把包目录复制进去（要包含 runtime/）
Copy-Item -Recurse -Force "<这个包的路径>" "$profile\node_modules\$name"
# 2) 在 profile 的 package.json 里登记：
# dependencies 里加 "dsh-agents-viewer": "file:<这个包的绝对路径>"
# dsh.profile.bundles 末尾追加 "dsh-agents-viewer"
# 注意：bundles 才是“启用”开关；只在 dependencies 里是“装了但没启用”。
# 3) 重启 DSH（客户端 tab 的类型注册发生在启动时）
更推荐直接用 DSH 的插件页安装这个包（会自动处理依赖和 bundles），或在本 checkout 里跑 npm run adapt:install。改之前建议先备份 profile 的 package.json 和 cordis.patch.yml。
自动适配
0.7.0 起，插件不再把 DSH 版本写死：
dsh.client.inject 为空：客户端只 require("react")（基座模块），不依赖任何 @deepseek-ai/dsh-client-* 包名；engines.dsh 只留下限，不设上限；- 客户端只 Cordis-inject
slots；sidebarRightTabs / sidebarRight 在 apply 里用 ctx.inject 按需等待。DSH 改名或删掉其中一个，只会少对应的入口，不会让插件永远 pending 或拖垮界面；
- 宿主对
webServer.register / commands.register / workingDirectory.ensure 先判类型，缺了只打 warning；
webserver/index-inject 全包 try/catch，任何异常都不会把 index 变成 500。
升级 DSH 后：
npm run adapt # 只检查：版本、engines、profile 副本是否一致
# 退出 DSH 后，需要把本 checkout 同步进 profile 时：
npm run adapt:install
adapt:install 会在 DSH 运行时拒绝执行，因为运行中替换插件文件可能触发客户端热重载、打断当前窗口；它同时会把旧的 panel.js、嵌套的 runtime/runtime/ 等残留清掉。
升级 DSH 后（手动检查）
node scripts/check-compat.mjs
# 或指定安装位置
node scripts/check-compat.mjs --asar "D:/Program Files/DeepSeek Harness/resources/app.asar"
它会拿当前安装的 app.asar 核对 dsh.client.inject 里的每个包是否存在、engines.dsh 是否接受当前版本、客户端 bundle 是否还按 window.__ModuleLoader__.load 注册。DSH 改了模块名时，这里会先报 FAIL，而不是等 DSH 打不开才发现。
DSH 打不开时，先分清是谁的问题
desktop welcome: Web authentication failed 这类启动失败不是插件造成的：
- 崩溃报告在
%APPDATA%\@deepseek-ai\dsh-desktop\logs\crash-*-host.log。如果 --- error --- 是 desktop welcome: Web authentication failed，失败发生在桌面壳向自己刚启动的 Host 换 cookie/取 index 的那一步，插件还没参与。
- 崩溃对话框里的「禁用第三方插件」会备份
cordis.patch.yml 并把 dsh.profile.bundles 重置为官方组合。如果点完还继续崩，就证明与插件无关——继续反复点、反复启动只会拉长故障时间。
- 插件本身出问题时的表现完全不同：Host 仍会启动，日志里是
dsh: warning: N entry did not activate，界面只是少了这个 tab/按钮。宿主半和客户端半都做了兜底，单个注册失败不会影响 DSH 启动。
真正需要检查的：是否有残留的 DSH 进程、更新下载后是否卡在安装交接（%LOCALAPPDATA%\@deepseek-aidsh-desktop-updater\pending）、以及本机的 dsh-auth-* cookie 是否已经堆到 16 KB。一次只启动一个实例，别在更新安装期间反复双击图标。
另一种 Web authentication failed：cookie 431
DSH Desktop 的 Host 每次用随机端口启动，而登录 cookie 名是 dsh-auth- + hash(host:port)。端口变一次就多一条 cookie，名字不复用；Chromium 又把 127.0.0.1 的所有 dsh-auth-* 一起塞进同一个 Cookie 头。约 70 次启动后请求头超过 Node 默认的 16 KB，Host 直接返回 431，桌面壳就报 desktop welcome: Web authentication failed。
自查（先退出 DSH，cookie 库运行时被独占锁住）：
$db = "$env:APPDATA\@deepseek-ai\dsh-desktop\Network\Cookies"
python -c "import sqlite3,sys;c=sqlite3.connect(sys.argv[1]);print(c.execute(\"select count(*) from cookies where name like 'dsh-auth-%'\").fetchone()[0])" $db
≥ 70 就要清。清理只删 dsh-auth-*、先备份，参考 dsh-cookie-431。长期方案是在 profile patch 里把 @deepseek-ai/dsh-client-connection 的 cookieMaxAgeDays 从默认 30 改成 3（本机 profile 已经加上，见下面「改 profile」）。
改 profile 必须退出 DSH
桌面 profile 开着 HMR。运行中改 cordis.patch.yml（尤其 connection）或 package.json 的 bundles，会立即重载对应节点：当前浏览器连接被换掉，进行中的会话会以 turn/end: aborted / disposed 结束，窗口看起来就是「挂掉」。改 profile 的 bundles、connection 或任何启动项前，先完整退出 DSH，改完再启动；只改插件工作目录里的代码则可以热重载。
文件
index.js 宿主：HTTP 路由（/list /read /write /ui）+ /agents 命令
runtime/client.js 客户端：sidebarRightTabs 注册 + tab 正文 + 头部按钮（手写 bundle，无构建）
runtime/override.css 宿主每次 index 请求注入的 CSS 覆盖层（改完刷新即可）
cordis.patch.yml bundle 补丁：插入 dsh-agents-viewer 一行
scripts/adapt-dsh.mjs 自动适配：检查运行时 / 版本 / profile 副本，可一键同步安装
scripts/check-compat.mjs 清单核对（inject 包 / engines / client 入口）
scripts/lib/dsh-runtime.mjs asar 读取、semver、进程检测、profile 同步
locale/*.json 插件管理器里显示的标题与描述
icon.svg 图标
实现要点
- 客户端：
ctx.sidebarRightTabs.register({ id, kind, priority, title, guide, keepMounted }) 注册页面类型；正文通过 ctx.slots.register({ name: 'sidebar.right.pane.tab', key: id }, Body) 挂载。正文的标准 props 直接给 sessionId 和 useSessions，没有 DOM 观察、没有 URL 解析。
- 头部按钮：注册进
conversation.session.header.utilities（list 槽，order: -100），位置在文件/侧栏按钮那一簇的左边。点击时：侧栏收起 → openTab('agents')；已展开且当前 tab 是 agents → toggleExpanded() 收起；展开但是别的 tab → 切到 agents。/agents o / c 只写 ~/.dsh/storages/dsh-agents-viewer.ui.json，按钮在页面加载时读一次 /ui，所以显隐下次启动/刷新生效。
- CSS 覆盖层：
runtime/override.css 由宿主在每次 index 请求时现读并注入 <style>；编辑器换行等样式改完刷新页面即可，不用重启。
- 宿主：
webServer.register 暴露 /dsh-agents-viewer/list、/read、/write；resolveProject(hint) 从 hint 里的 session-<uuid> 反查 ~/.dsh/storages/workspace.json。拿不到会话才退回最近工作区，并在 tab 上标「推断」、保存前确认。
- 白名单：全局 / 共享 + 项目根到 cwd 的目录链；其余路径一律 403。写盘是宿主进程直接
fs.writeFileSync，白名单是唯一入口。
- 兼容性：
dsh.client.inject 为空，engines.dsh 只有下限；客户端只 inject slots，sidebarRightTabs / sidebarRight 用嵌套 ctx.inject 按需等待，宿主对三个服务先判类型。DSH 改名/删服务时，对应入口不注册、打一条 warning，DSH 仍能启动，/agents 命令在其他入口失效时也照常可用。webserver/index-inject 和所有注册都做了 try/catch，插件永远不会把 index 打成 500。
- 启动安全：宿主插件加载失败只会让 DSH 打一条
entry did not activate 警告；npm run adapt 在升级 DSH 后核对版本/清单/profile 副本，npm run adapt:install 在 DSH 运行时拒绝执行，避免热替换打断窗口。
已知限制
- 没有浮动面板：tab 只在右侧栏里；头部按钮在
conversation.session.header.utilities（文件/侧栏按钮那一簇的左边），不在 tab 条上。
/agents o / c 不是即时显隐：只改持久化状态，按钮在下次启动/刷新的页面加载时读取；当前页面运行中不会马上变。- 面板保存不触发指令热刷新：宿主是直接写盘，
dsh-agent-instructions 只会在后续一次 read / write / edit 工具调用时刷新。当前会话要立刻看到新内容，需要新开会话，或让 agent 对该文件做一次读写。
- 指令链只覆盖项目根到会话 cwd 的目录链：链外的任意子目录不会出现在列表里（与
/agents 命令一致）。
- 首次安装/升级需要重启 DSH，客户端模块图在启动时组装。
许可
MIT
