dsh-artifact-index
DeepSeek Harness Web GUI 的 Artifact 索引端点：提供 JSON 索引契约以及 dsh-artifacts 侧边栏标签页读取的文件字节。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add dsh-artifact-index@0.1.0Artifact Index 以 dsh-artifact-index 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
为 DSH 的 dsh-artifacts 侧边栏标签页提供它所需的 artifact 索引端点。
零依赖、只读、约 600 行（含注释与测试）。无遥测，无网络外联，无 install 脚本。
dsh-artifacts 是一个纯前端 viewer：它只管渲染，不负责提供数据。它的 host 半
（lib/index.js）是一个刻意的空实现，客户端加载后就去轮询一个外部端点：
// dsh-artifacts/lib/client.js:32
var DEFAULT_LIST_URL = "/report/?list=1";
所以装完之后，侧边栏会稳定地显示：
Could not read the artifact index. HTTP 404 from /report/?list=1&session=…
这不是 bug，是缺了一半。 上游把「索引从哪来」留给了使用者。本插件就是那一半：
在 DSH 的 web server 上把 /report 这条路挂起来，返回上游约定的 JSON 形状，并把
artifact 的字节流发给它塞进 iframe。
需要 DSH ≥ 0.1.5-rc.1，且 dsh-better-sidebar 与 dsh-artifacts 已先安装
（本插件只补后端，不替代它们）。
从 npm 安装：
dsh plugin --profile desktop add dsh-artifact-index
从源码安装（本仓库根目录）：
# 符号链接：改代码后重启 DSH Desktop 即可生效
dsh plugin --profile desktop add "link:<本仓库的绝对路径>"
# 或冻结一份副本
dsh plugin --profile desktop add "file:<本仓库的绝对路径>"
重启 DSH Desktop，确认挂载行存在：
dsh --profile desktop --dump-config | grep artifact-index
改动插件后必须新开一个会话 —— DSH 的插件与工具列表是会话创建时的快照。
插件启动时会往日志里写一行（日志在 DSH Desktop 的 logs 目录，
Windows 下是 %APPDATA%\DSH Desktop\logs\dsh-<日期>.log）：
[dsh-artifact-index] artifact root = <artifact 目录> (maxItems=500, ...)
dsh.profile.bundles 里是否有
dsh-artifact-index，以及日志中有无 failed to apply loader entry …。注意 DSH 的 web server 会拒绝非浏览器发起的请求，因此 curl 之类的命令行工具
无法用来验证路由。要对真实目录做端到端检查，用仓库里的脚本：
node scripts/smoke.mjs <artifact 目录>
它直接驱动 handler，对目录逐项回取校验。（该脚本只监听 loopback 并把请求发回自己。）
配置写在 profile 的 cordis.patch.yml 里那条 mount row 的 config 下，
或者用环境变量。优先级：config > 环境变量 > 默认值。
- id: dsh-artifact-index
name: 'dsh-artifact-index'
config:
root: <artifact 目录>
maxItems: 500
maxFileBytes: 26214400
csp: sandbox
| 键 | 默认值 | 说明 |
|---|---|---|
root | $DSH_HOME/artifacts | 要索引的目录。不递归，只扫这一层。 |
maxItems | 500 | 返回条目数上限，超出部分丢弃并在日志里记一条警告。 |
maxFileBytes | 26214400（25 MB） | 单文件上限，超过返回 413。 |
csp | sandbox | 给 HTML/SVG/XML 响应加的 Content-Security-Policy。见下。 |
trustedHosts | [] | 额外允许的 Host。仅当 DSH 不跑在 loopback 上时才需要。 |
$DSH_HOME 指 DSH 的数据目录（Windows 下可用 echo $env:DSH_HOME 查看，
或从 dsh --profile desktop --dump-config 里找）。
环境变量：DSH_ARTIFACT_INDEX_ROOT 覆盖 root（当 config 未提供时）。
csp 三个取值：
| 值 | 实际下发的头 | 适用 |
|---|---|---|
sandbox（默认） | sandbox | artifact 内的脚本、表单、弹窗、同源访问全部失效。 |
sandbox-scripts | sandbox allow-scripts | 需要看 JS 渲染的 HTML artifact（如自绘图表）。 |
none | 不下发 | 只在明确理解风险时使用。 |
GET /report/（也接受 /report、?list=1&session=<id>）{
"count": 2,
"items": [
{ "name": "report.html", "url": "/report/report.html", "ext": "html", "size": 5120, "mtime": 1757000000 },
{ "name": "data.json", "url": "/report/data.json", "ext": "json", "size": 2048, "mtime": 1756990000 }
]
}
items 按 mtime 降序（新→旧），同刻按 name 升序。url 被上游原样当作 iframe 的 src，因此是根相对且已百分号编码的。mtime 单位是秒。mine 字段，这是故意的：上游在 mine 缺席时会隐藏
「This chat / All」切换器，而 v0.1 还做不了按会话归属。详见下方「关于 mine」。200 + { count: 0, items: [], error: "…" }，
由客户端把 error 内联显示出来。GET /report/<name>返回该 artifact 的字节。Content-Type 按扩展名映射；HTML/SVG/XML 会带上 CSP。
只允许单段文件名，不接受子路径。
minemine 是 dsh-artifacts 客户端约定的一个可选字段，不是本插件发明的。
它的语义是「这个 artifact 是不是当前这次会话产出的」。客户端据此渲染一个 This chat / All 切换器，让使用者在一堆历史产物里只看本轮的结果。
本插件 v0.1 故意不下发 mine，因为算不对它比不算更糟：要做对，必须从会话记录里
把本轮的 artifact 路径还原出来，而会话记录里并没有现成的「产物清单」。可行的做法是
解析 tool-call 的参数（比如写文件工具的 path 参数），而不是拿正则去扫原始文本——
后者只要对话里提到一个文件名就会误判。
所以 v0.1 的选择是：给一份诚实的、扁平的「全部产物」列表，而不是一份会撒谎的归属
信息。?session=<id> 参数会被解析但忽略，留给 v0.2 使用。
这是本机文件读取接口，所以按不可信输入对待。详见 SECURITY.md。
做的：
root 内，再对两端都做 realpath，
因此指向外部目录的符号链接会被拒（只看字符串是拦不住的）。%2F、..%2F、..\\ 等在解码前后各拦一次。404。. 开头）与符号链接。GET/HEAD 之外一律 405。trustedHosts），Sec-Fetch-Site: cross-site
直接 403——用于挡住「网页读取本机端口」这一类请求。stat 一次并核对大小上限，避免「先 stat 再读」的时间差被换文件放大。不做的（明确的非目标）：
root 里的白名单文件。防线是 profile 的
networkExposure: loopback，不要把 DSH 暴露到公网。mine）。root 内部。node --test # 64 个测试：契约、路径穿越、信任判断、装配一致性
两个核心测试文件：
test/contract.test.mjs —— 起一个真的 HTTP server 打真的临时目录，
逐字断言上游契约（字段集合、排序、mine 缺席、CSP、413、403）。契约不匹配的表现
是界面上只显示一行错误，因此不看测试很难发现。test/safe-path.test.mjs —— 路径穿越矩阵，包括「前缀相同的兄弟目录」
和「符号链接指向 root 外部」这两个字符串检查拦不住的用例。代码结构：
lib/index.js Cordis 宿主半：路由、信任闸门、CSP、流式发送
lib/scan.js 目录扫描 + 契约映射（fs 可注入，纯逻辑可单测）
lib/safe-path.js 路径安全（双重校验）
lib/trust.js 请求信任判断（Host / Sec-Fetch-Site / Origin）
没有任何第三方运行期依赖，也不需要安装期脚本：package.json 的 scripts 里没有
preinstall / install / postinstall，因此装这个包不会执行任何代码。
需要核对网络行为时，只有两处：
lib/index.js 与其余 lib/*.js 的 import —— 全部是 node: 内置模块。scripts/smoke.mjs —— 只监听 loopback、只请求自己的端口，不向外部地址发送数据。v0.2 — 按会话归属（mine）
需要从会话事件流里把本轮的 artifact 路径还原出来。实现时必须解析 tool-call 的
参数（write 的 path），而不是正则扫描原始文本——否则对话内容里提到一个文件名
就会误判。契约上表现为 mine: true/false，侧栏随之出现 This chat / All 开关。
v0.2 — 分页与搜索
maxItems 目前是硬截断。超过几百个 artifact 之后需要 ?offset= 或按名字过滤。
v0.3 — 缩略图
图片现在走原图。大量截图时侧边栏会明显变慢。
docs/DESIGN.md 记录了设计推理与取舍（为什么用单条 prefix
路由而不是 exact + prefix、为什么不注入 ctx.webRuntime、风险登记表等）。
MIT