dsh-artifact-index

为 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, ...)

出现这行 → 插件已激活，接下来只需看侧栏的 Artifacts 标签页。
没有这行 → 插件未激活。检查 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。只允许单段文件名，不接受子路径。

关于 `mine`

mine 是 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。
同源闸门：Host 必须是 loopback（或 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、只请求自己的端口，不向外部地址发送数据。

Roadmap

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、风险登记表等）。

License

MIT

dsh-artifact-index

为 DSH 的 dsh-artifacts 侧边栏标签页提供它所需的 artifact 索引端点。

零依赖、只读、约 600 行（含注释与测试）。无遥测，无网络外联，无 install 脚本。

它解决什么问题

// 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=…

安装

需要 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, ...)

出现这行 → 插件已激活，接下来只需看侧栏的 Artifacts 标签页。
没有这行 → 插件未激活。检查 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。只允许单段文件名，不接受子路径。

关于 `mine`

mine 是 dsh-artifacts 客户端约定的一个可选字段，不是本插件发明的。

它的语义是「这个 artifact 是不是当前这次会话产出的」。客户端据此渲染一个 This chat / All 切换器，让使用者在一堆历史产物里只看本轮的结果。

字段存在时，客户端显示该切换器。
字段缺席时，客户端把切换器整个隐藏起来。

所以 v0.1 的选择是：给一份诚实的、扁平的「全部产物」列表，而不是一份会撒谎的归属信息。?session=<id> 参数会被解析但忽略，留给 v0.2 使用。

安全

这是本机文件读取接口，所以按不可信输入对待。详见 SECURITY.md。

做的：

路径双重校验：先按解析后的前缀判断是否在 root 内，再对两端都做 realpath，因此指向外部目录的符号链接会被拒（只看字符串是拦不住的）。
只允许单段文件名；%2F、..%2F、..\\ 等在解码前后各拦一次。
扩展名白名单（文档 + 图片），非白名单返回 404。
不递归子目录，跳过隐藏文件（. 开头）与符号链接。
GET/HEAD 之外一律 405。
同源闸门：Host 必须是 loopback（或 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）

依赖与网络行为

需要核对网络行为时，只有两处：

lib/index.js 与其余 lib/*.js 的 import —— 全部是 node: 内置模块。
scripts/smoke.mjs —— 只监听 loopback、只请求自己的端口，不向外部地址发送数据。

Roadmap

v0.2 — 按会话归属（mine）

v0.2 — 分页与搜索

maxItems 目前是硬截断。超过几百个 artifact 之后需要 ?offset= 或按名字过滤。

v0.3 — 缩略图

图片现在走原图。大量截图时侧边栏会明显变慢。

设计文档

docs/DESIGN.md 记录了设计推理与取舍（为什么用单条 prefix 路由而不是 exact + prefix、为什么不注入 ctx.webRuntime、风险登记表等）。

License

MIT

Huuuuung/dsh-artifact-index

dsh-artifact-index

它解决什么问题

安装

验证安装

配置

端点契约

`GET /report/`（也接受 `/report`、`?list=1&session=<id>`）

`GET /report/<name>`

关于 `mine`

安全

开发

依赖与网络行为

Roadmap

设计文档

License

Community comments

Huuuuung/dsh-artifact-index

dsh-artifact-index

它解决什么问题

安装

验证安装

配置

端点契约

`GET /report/`（也接受 `/report`、`?list=1&session=<id>`）

`GET /report/<name>`

关于 `mine`

安全

开发

依赖与网络行为

Roadmap

设计文档

License

Community comments

Huuuuung/dsh-artifact-index

dsh-artifact-index

它解决什么问题

安装

验证安装

配置

端点契约

GET /report/（也接受 /report、?list=1&session=<id>）

GET /report/<name>

关于 mine

安全

开发

依赖与网络行为

Roadmap

设计文档

License

Community comments

Huuuuung/dsh-artifact-index

dsh-artifact-index

它解决什么问题

安装

验证安装

配置

端点契约

GET /report/（也接受 /report、?list=1&session=<id>）

GET /report/<name>

关于 mine

安全

开发

依赖与网络行为

Roadmap

设计文档

License

Community comments

`GET /report/`（也接受 `/report`、`?list=1&session=<id>`）

`GET /report/<name>`

关于 `mine`

`GET /report/`（也接受 `/report`、`?list=1&session=<id>`）

`GET /report/<name>`

关于 `mine`