dsh-artifact-index：DeepSeek Harness 侧边栏的缺失后端

前置要求¶

此插件仅提供后端能力，需要配合前端组件使用。

DSH 版本：需安装 DSH >= 0.1.5-rc.1。
依赖组件：必须先安装 dsh-better-sidebar 和 dsh-artifacts。本插件不替代它们，而是补全数据链路。

核心功能¶

dsh-artifact-index 是 dsh-artifacts 侧边栏标签页所需的缺失后端。它运行在 DSH 的 web server 上，负责提供 artifact 的索引 JSON 和文件字节流。

服务索引：通过 GET /report/ 返回 artifact 列表 JSON。
服务文件：通过 GET /report/<name> 返回指定 artifact 的二进制内容。
零依赖：无第三方运行时依赖，无网络外联，无遥测。
可配置：支持配置根目录、最大条目数、单文件大小上限及内容安全策略（CSP）。
安全防护：内置路径安全校验，仅允许 loopback 访问，禁止路径穿越。

安装与启用¶

使用官方安装命令添加插件。

dsh plugin --profile desktop add dsh-artifact-index

安装完成后，必须重启 DSH Desktop。插件与工具列表是会话创建时的快照，重启后才会加载新插件。

验证安装¶

重启后，检查日志目录（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 目录>

配置项¶

配置写入 profile 的 cordis.patch.yml 中挂载行的 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`	内容安全策略。`sandbox` 禁止脚本/表单；`sandbox-scripts` 允许脚本；`none` 不下发。
`trustedHosts`	`[]`	额外允许的 Host，仅在 DSH 不跑在 loopback 上时使用。

环境变量 DSH_ARTIFACT_INDEX_ROOT 可用于覆盖 root 配置。

接口契约¶

`GET /report/` (索引列表)¶

返回 JSON 格式的索引数据。items 按 mtime 降序排列，同刻按 name 升序。

{
  "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
    }
  ]
}

注意：
* url 字段会被上游直接用作 iframe 的 src，因此是根相对且已编码。
* mtime 单位为秒。
* 响应中不包含 mine 字段（v0.1 的设计选择，详见下文）。
* 若无法读取目录，返回 200 状态码及 { count: 0, items: [], error: "..." }。

`GET /report/<name>` (文件字节)¶

返回指定文件的二进制流。Content-Type 根据扩展名自动映射。对于 HTML/SVG/XML，会附加 CSP 头。仅允许单段文件名，不接受子路径。

设计与限制¶

关于 `mine` 字段¶

mine 是 dsh-artifacts 客户端约定的字段，用于标记 artifact 是否属于当前会话。本插件 v0.1 版本故意不返回此字段。原因是在 v0.1 中，准确还原会话归属过于复杂，且容易产生误判。当前版本提供的是一份诚实的扁平列表，而非可能撒谎的归属信息。

安全特性¶

路径安全：对请求路径进行双重校验（字符串校验 + realpath），防止符号链接指向外部目录或路径穿越。
访问控制：仅允许 loopback 访问。Sec-Fetch-Site: cross-site 请求会被直接拒绝。
操作限制：仅支持 GET/HEAD，无写入、删除或认证功能。

总结¶

dsh-artifact-index 解决了 dsh-artifacts 侧边栏因缺少后端而导致显示 “Could not read the artifact index” 的问题。它是一个轻量级的中间件，用于将本地文件系统映射为 DSH 的 HTTP 服务，适合需要在侧边栏查看本地生成的报告或文档的开发者。

仓库：https://github.com/Huuuuung/dsh-artifact-index
许可证：MIT