Artifact 渲染器zoahdev/dsh-artifacts

dsh-artifacts

面向 DeepSeek Harness 的 Claude-Artifacts 风格渲染。 将原始 agent
输出——Markdown + JSON——转换为精美、可分享、自包含的 HTML
文档、卡片、仪表盘和图库。一条命令。零运行时
依赖。

CI
License: MIT
npm

dashboard demo

你的 agent 整天都在生成 Markdown 和 JSON。其中大部分最终都变成了无人分享的
无样式终端文本。dsh-artifacts 解决了这个问题：同样的内容，
渲染为精致的、无依赖的 HTML artifact，你可以从磁盘打开、
附加到电子邮件，或放到任何静态主机上。

在线演示： https://zoahdev.github.io/dsh-artifacts/

已发布到 npm： dsh-artifacts

为什么

- 无需设计技能。 选择模板 + 主题，即可获得成品页面。
- 自包含。 所有 CSS 均已内联——没有外部字体、框架或
跟踪。输出可离线运行，永久有效。
- 两种使用方式。 为你提供 CLI，为 agent 本身提供 artifact_render 工具。
- 零运行时依赖。 仅需 Node ≥ 18；无需审计任何内容。

快速开始

作为独立 CLI
pnpm add -g dsh-artifacts
或：npm install -g dsh-artifacts
dsh-artifacts notes.md --title "Release notes" --theme dark --out notes.html
dsh-artifacts notes.md --serve 8080          # 实时预览

或通过 npx 免安装使用
npx dsh-artifacts notes.md --theme paper --out notes.html

作为 DeepSeek Harness 插件安装：

dsh plugin --profile web add dsh-artifacts
或直接使用上游 CLI：
pnpm dlx @deepseek-ai/dsh plugin --profile web add dsh-artifacts

然后 agent 可以在聊天中调用 artifact_render，将样式化报告写入
磁盘，并把路径返回给你。

模板

| 模板 | 用途 |
| --- | --- |
| doc | 散文、笔记、报告、README 风格内容 |
| card | 单张可分享的陈述 / 主视觉卡片 |
| dashboard | 来自 JSON 的指标、条形图和表格 |
| gallery | 图片 / 项目网格 |

全部四个模板，均使用本仓库中相同的演示输入渲染：

主题

| 主题 | 风格 |
| --- | --- |
| dark | GitHub 深色，默认 |
| light | 干净的浅色 UI |
| paper | 温暖、编辑风格的衬线字体 |
| terminal | 黑底绿字等宽字体 |
| brand | DeepSeek 蓝 |

示例

从 Markdown 生成文档：

dsh-artifacts demo/sample.md \
--title "Release notes" \
--subtitle "dsh-artifacts v0.1.0" \
--theme dark \
--out release-notes.html

document demo

从 JSON 生成仪表盘：

dsh-artifacts --data demo/metrics.json \
--title "Agent fleet dashboard" \
--template dashboard \
--theme brand \
--out dashboard.html

{
"metrics": [
{ "label": "Sessions", "value": 128, "delta": "+12" },
{ "label": "CI", "value": true }
],
"bars": [
{ "label": "Monday", "value": 8 },
{ "label": "Tuesday", "value": 14 }
],
"columns": ["tool", "calls", "median_ms"],
"rows": [["read_file", "412", "38"]]
}

从 JSON 生成画廊：

dsh-artifacts --data gallery.json --template gallery --theme light

{ "items": [ { "title": "A", "image": "https://…/a.png", "tag": "new" } ] }

Vault 导出（Obsidian / VS Code / 任意 Markdown 文件夹）

dsh-artifacts 并非仅适用于 DSH。将它指向任意包含 .md 笔记的文件夹——一个
Obsidian vault、一个 VS Code 笔记目录、博客草稿或文档——它会为每篇笔记渲染一个自包含的 HTML 页面，并生成一个带链接的 index.html：

dsh-artifacts vault ./my-notes --theme paper --out site
site/index.html + site/.html

每篇笔记的第一个 # heading 会成为其标题；第一行有意义的内容
会成为索引摘要。被忽略的文件夹包括 node_modules、.git、
.obsidian 和 .trash。使用 --no-recursive 仅处理顶层。

框架内工具

artifact_render 接受：

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| title | string | 文档标题 |
| subtitle | string | 副标题 / 署名 |
| markdown | string | Markdown 正文 |
| data | string | 用于 dashboard / gallery 的 JSON |
| template | string | doc / card / dashboard / gallery |
| theme | string | light / dark / paper / terminal / brand |
| out | string | 输出路径（默认为临时文件） |

它返回 { path, bytes, title, template, theme }。

库用法

import { renderArtifact } from 'dsh-artifacts'

const { html } = renderArtifact({
title: 'Weekly report',
markdown: '# Shipped',
template: 'doc',
theme: 'dark',
})

CI 实际验证了什么

build → unit tests → pack → install the real tarball into a fresh project →
load the packed bundle → register artifact_render via apply() →
execute the real handler → assert a real HTML file + rendered output。

在第二步中，CI 将打包好的插件安装到一个全新的 DSH_HOME
配置文件中，验证它出现在 --dump-config 中，启动真实的 dsh web
服务器，并断言 HTTP 200。

冒烟测试还会针对旧版 @deepseek-ai/dsh-tools RC 进行安装，并
断言运行时守卫会明确拒绝它（而不是在之后才失败）。

测试环境

- @deepseek-ai/dsh-tools ^0.1.0-rc.6
- @deepseek-ai/cordis ^4.0.1
- Node ≥ 18（CI 运行 Node 22）

peer 范围声明为脱字符范围（而非硬性固定）。在运行时，
如果解析出的 dsh-tools 版本超出该测试范围，插件将拒绝加载。

故障排查

安装插件时失败，报 ERESOLVE / 与较旧的 @deepseek-ai/dsh-tools RC 存在 peer 依赖冲突。

该插件针对 ^0.1.0-rc.6 进行了测试。如果你的 harness 使用的是较旧的 RC（例如 0.1.0-rc.5），请先升级宿主，然后再安装插件：

pnpm dlx @deepseek-ai/dsh --version          # 检查你的版本
pnpm dlx @deepseek-ai/dsh plugin --profile web add dsh-artifacts

如果包管理器仍将旧的 RC 解析到插件的 peer 槽位，插件会在加载时抛出错误：

dsh-artifacts: resolved @deepseek-ai/dsh-tools 0.1.0-rc.5, but this plugin is
tested with ^0.1.0-rc.6. Upgrade DeepSeek Harness to 0.1.0-rc.6 or later, then
reinstall.

将宿主环境升级到 0.1.0-rc.6（或更高版本）并重新安装；不要为了“修复”冲突而修改插件的 peer 范围，因为较旧的 RC 未经验证。

诚实的局限

- Markdown 渲染器覆盖常见子集（标题、列表、引用、代码、表格、链接、图片）。它不是完整的 CommonMark 实现。
- 仪表盘是静态 HTML/CSS；没有 JavaScript 运行时、流式传输或实时数据绑定（--serve 模式会在刷新时重新渲染）。
- 这是一个社区插件，不是 DeepSeek 官方产品。它不是安全边界，也未经过安全审计。

发布清单

- [x] pnpm install --frozen-lockfile
- [x] pnpm typecheck
- [x] pnpm build
- [x] pnpm test
- [x] pnpm pack
- [x] 打包后的插件可加载，且 artifact_render 调用成功
- [x] 双语 README

发布

推送一个 v* 标签，GitHub Actions 会自动将包发布到 npm：

npm version patch && git push --tags

NPM_TOKEN 仓库密钥是一个细粒度访问令牌，作用域限定为 dsh-artifacts（读 + 写，自动化时绕过 2FA）。

中文

给 DeepSeek Harness 的「Claude Artifacts」式渲染。 把 Agent 产出的
Markdown + JSON，一键变成漂亮、可分享、自包含的 HTML 文档、卡片、仪表盘和
画廊。零运行时依赖。

你的 Agent 整天都在输出 Markdown 和 JSON，但大多数最后都只是没人愿意分享的
终端文本。dsh-artifacts 解决这个问题：同样的内容，渲染成干净、自包含的 HTML
产物，可以直接打开、发邮件或放到任意静态站点。

特点

- 无需设计能力 — 选模板 + 主题，直接得到成品页面。
- 完全自包含 — CSS 全部内联，不依赖外部字体、框架或追踪脚本，离线永久可用。
- 两种用法 — 命令行给你用，artifact_render 工具给 Agent 用。
- 零运行时依赖 — 只需 Node ≥ 18。

快速开始

pnpm add -g dsh-artifacts
dsh-artifacts notes.md --title "发布说明" --theme dark --out notes.html
dsh-artifacts notes.md --serve 8080        # 实时预览

作为 DeepSeek Harness 插件安装：

dsh plugin --profile web add dsh-artifacts
pnpm dlx @deepseek-ai/dsh plugin --profile web add dsh-artifacts

模板

| 模板 | 用途 |
| --- | --- |
| doc | 文档、笔记、报告 |
| card | 单张可分享卡片 |
| dashboard | JSON 指标、柱状图、表格 |
| gallery | 图片 / 条目画廊 |

主题

| 主题 | 风格 |
| --- | --- |
| dark | GitHub 深色（默认） |
| light | 干净浅色 |
| paper | 暖色编辑风衬线体 |
| terminal | 绿字黑底等宽 |
| brand | DeepSeek 蓝 |
Vault 导出（Obsidian / VS Code / 任意 Markdown 文件夹）

不只用于 DSH。指向任意 .md 笔记目录（Obsidian 库、VS Code 笔记、博客草稿、文档），
每条笔记生成一个自包含 HTML 页，外加带链接的 index.html：

dsh-artifacts vault ./my-notes --theme paper --out site

已验证

- @deepseek-ai/dsh-tools ^0.1.0-rc.6
- @deepseek-ai/cordis ^4.0.1
- Node ≥ 18（CI 使用 Node 22）

排障

安装插件时因旧版 @deepseek-ai/dsh-tools RC 出现 ERESOLVE / peer 冲突。

先把宿主环境升级到 0.1.0-rc.6 或更新版本，再安装插件；不要靠放宽 peer 范围
来「修复」冲突，因为更旧的 RC 未经验证。插件在加载时若解析到不兼容版本会直接
报错并给出升级提示。

诚实边界

- Markdown 渲染覆盖常用子集（标题、列表、引用、代码、表格、链接、图片），并非
完整 CommonMark。
- 仪表盘是静态 HTML/CSS，没有 JS 运行时、流式或实时数据绑定。
- 这是社区插件，不是 DeepSeek 官方产品，未经安全审计。