# @eduwork/dsh-artifact-services 中文文档

规范地址：https://npmcn.com/package/%40eduwork/dsh-artifact-services/

版本：0\.3\.4
npm 元数据更新时间：2026-11-12T07:47:08.221Z
中文译文更新时间：2026-11-13T07:36:31.179Z
软件包许可：MulanPSL-2\.0 AND MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40eduwork/dsh-artifact-services
原文对照：https://npmcn.com/package/%40eduwork/dsh-artifact-services/?lang=original
项目主页：https://github.com/ECNU/EduWork/tree/main/packages/dsh-knowledge-studio/packages/artifact-services#readme
源码仓库：https://github.com/ECNU/EduWork

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：7.3 MB，126 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24\.18\.0
- 运行依赖：8 个
- peer 依赖：@deepseek-ai/cordis \>=4\.0\.5 \<4\.1\.0 \|\| 4\.1\.0，@deepseek-ai/dsh-skill \>=0\.2\.1-rc\.2 \<0\.3\.0-0 \|\| \>=0\.2\.2-rc\.1 \<0\.2\.3-0，@deepseek-ai/dsh-tools \>=0\.2\.1-rc\.2 \<0\.3\.0-0 \|\| \>=0\.2\.2-rc\.1 \<0\.2\.3-0
- 首次发布：2026-09-06T09:28:28.950Z
- 最新版本发布：2026-11-12T07:47:07.861Z
- 近 30 天下载量：2837（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

共享应用程序和DSH工具的办公室、语音和媒体服务

## 安装

```sh
npm install @eduwork/dsh-artifact-services
```

也可以使用：`pnpm add @eduwork/dsh-artifact-services`、`yarn add @eduwork/dsh-artifact-services`、`bun add @eduwork/dsh-artifact-services`

## README

# 共享成果服务

[English](https://npmcn.com/package/%40eduwork/dsh-artifact-services/README_EN.md)

为应用和 DSH 对话工具提供 Office 生成与预览、TTS/ASR Provider 及媒体渲染。Studio 使用同一组组件；本包不依赖 Studio、其索引、机构登录或桌面壳。

Word、Excel、PowerPoint 可复用宿主的官方 Office 技能、结构校验和 LibreOffice Kit，支持旧 DOC/XLS/PPT 读取及转换、Excel 公式重算。Studio 的 Office PDF 导出使用同一转换器，原文件保留。宿主要求和格式边界见[官方 Office 工作流](https://npmcn.com/package/%40eduwork/dsh-artifact-services/docs/OFFICE_PROCESSING.md)。

版本为 `@eduwork/dsh-artifact-services@0.3.0`，与 Studio `0.6.0` 配套。DSH 集成目标严格为 `0.2.1-rc.2`；底层应用 API 要求 Node 24.18+，以及所用能力的运行环境。插件的稳定版本号不代表上游 DSH 已脱离 rc。

DSH 集成要求完整且版本一致的官方 0.2.1-rc.2 宿主，或兼容的 0.2.x 正式版。不要使用 `--force` 或 `--legacy-peer-deps` 绕过依赖冲突。

## 安装与配置

在 Node 项目中安装精确版本 `@eduwork/dsh-artifact-services@0.3.0`。本地验证也可安装已检查的压缩包：

```sh
npm install ./eduwork-dsh-artifact-services-0.3.0.tgz
```

使用 Studio 时，在同一命令中安装配套 Studio 包，只启用 Studio bundle，由其注册一次 Shared。见[源码构建与 Profile 激活](https://github.com/ecnu/EduWork/blob/main/packages/dsh-knowledge-studio/docs/USAGE.md)。普通 Node 应用直接调用下述 API；DSH Host 还需加载一次 `/dsh` 适配器。

Office 要求 Python 3.12+ 与本包 `python/requirements.txt` 中的依赖，`DSH_OFFICE_PYTHON` 指向解释器绝对路径。安装 npm 包不会安装 Python 库、ASR 模型或浏览器。TTS 的 `system` Provider 在 Windows 使用 System.Speech，在 macOS 使用系统 `say`；两者枚举已安装音色并输出 WAV，不需要 API Key。Mac 中文配音需要先在系统设置中安装中文语音，见[平台要求](https://npmcn.com/package/%40eduwork/dsh-artifact-services/docs/PLATFORMS.md#speech-synthesis)。其他平台需要 Provider。端侧 ASR 要求宿主提供 whisper.cpp 可执行程序和模型，见[转写说明](https://npmcn.com/package/%40eduwork/dsh-artifact-services/docs/TRANSCRIPTION.md)。

源码另提供可选的 `createDshTranscriptionProvider`，用于把 DSH 0.1.7 的本地 `speechToText` 服务接到现有文件转写接口；需由宿主显式注册，尚未替换桌面默认引擎。它支持分段处理长音频，但不提供时间戳；需要时间戳时仍使用原 Provider。TTS 保持独立，Mac 当前未内置系统语音适配器。选项、准备步骤和能力限制见[转写说明](https://npmcn.com/package/%40eduwork/dsh-artifact-services/docs/TRANSCRIPTION.md#optional-dsh-017-local-adapter)。

共享预览解析真实 DOCX/XLSX/PPTX 文件，保留 PPTX 固定页面坐标并使用内容哈希元数据。控件跟随宿主主题，文档内容保留原色。Studio 与对话附件使用同一[预览契约](https://npmcn.com/package/%40eduwork/dsh-artifact-services/docs/OFFICE_PREVIEW.md)；原生全屏和普通文档预览由宿主管理，对话最终文件可用时交给官方 `present`。预览保真度仍需用原生 Office 独立核对。

PDF/视频应用可从 `@eduwork/dsh-artifact-services/runtime` 导入 `createMediaRuntime` 并使用其 `browserExecutable`。固定部署应同时提供 `DSH_MEDIA_NODE_ENV` / `DSH_MEDIA_BROWSER`，兼容旧 `ECNU_AGENT_NODE_ENV` / `ECNU_AGENT_REMOTION_BROWSER`。已配置时不调用 `ensureBrowser`；未配置时实际渲染可准备本包浏览器，只读就绪检查不会下载。

运行时锁定 Remotion 4.0.520、mediabunny 1.55.5、React/React DOM 18.3.1，各调用方应解析到同一份 mediabunny。同入口的 `getMediaFFmpegPath` 从选定依赖所属环境解析 FFmpeg，不准备浏览器；可通过 `{runtime}` 传入已有运行时。

## 对话工具权限

Office 的新建、编辑、PDF 合并与提取遵守会话当前生效的文件写入权限。已有工作区写入权限时不重复确认；只读模式仍需本次审批。自定义权限预设以实际 sandbox policy 为准。项目相对路径、真实路径边界和禁止覆盖已有文件的约束仍生效，Full Access 也不会扩大 Office 工具的路径范围。

生图、TTS、ASR、固定模板音视频渲染及视频项目文件操作同样复用工作区写入权限，包括调用已配置的远程提供方。远程服务仍可能上传请求内容并消耗额度，但不会仅因此逐次要求确认。功能开关、服务可用性、凭据及工作区路径检查继续生效；权限检查本身不会请求音色接口或调用生成服务。只读模式仍需审批，运行可编辑视频项目代码也保留独立审批。其他宿主权限钩子继续执行。

## 应用接口（v1）

```js
import {mkdtemp} from 'node:fs/promises'
import {tmpdir} from 'node:os'
import {join} from 'node:path'
import {SpeechService, createSystemSpeechProvider} from '@eduwork/dsh-artifact-services/speech'
if (!['win32', 'darwin'].includes(process.platform)) throw new Error('This example requires Windows or macOS system speech')
const directory = await mkdtemp(join(tmpdir(), 'shared-speech-example-'))
const speech = new SpeechService()
const dispose = speech.register(createSystemSpeechProvider())
const system = (await speech.list()).find(provider => provider.id === 'system')
if (!system?.available || !system.voices.length) throw new Error('Install an OS voice first')
try {
  const file = await speech.synthesize({
    provider: 'system', voice: system.voices[0].id, text: 'Hello.', speed: 1,
    directory, name: 'preview-1', signal: new AbortController().signal,
  })
  console.log(file.path) // Actual WAV; measured duration is also returned.
} finally { dispose() }
```

完整示例分别保存为 `.mjs`，在已安装本包的项目内运行。下列扩展示例是适配器模板，`host*`、工作区、执行上下文和取消信号由宿主提供。所有语音 Provider 使用统一的 `voices()` 与 `synthesize(request)`：

```js
speech.register({
  id: 'my-tts', title: 'My speech service', local: false,
  voices: async () => [{id: 'narrator', title: 'Narrator', language: 'zh-CN'}],
  async synthesize({text, voice, speed, directory, name, signal, execution}) {
    // Obtain credentials/permission through your host adapter. Use the exact
    // text, observe cancellation, save a real WAV in an authorized location.
    return hostSpeechAdapter.synthesize({text, voice, speed, directory, name, signal, execution})
  },
})
```

`execution` 是可选、短期有效的宿主上下文，不得序列化或发给浏览器。音色与 Provider 错误直接返回，不自动改用其他音色、本机引擎或厂商。时长从实际 WAV 字节测量，不采信厂商估计。当前 Provider 边界要求 WAV，其他原生格式由适配器转换；字幕按实际合成片段同步，不承诺逐词时间戳。

DSH 扩展通过 `ctx.artifactServices.registerSpeechProvider(provider)` 使用同一注册表，Studio 与 `speech_synthesize` 都从这里调用。HTTP、凭据、机构音色目录属于 Provider 适配器，`speech_synthesize` 是共享工具权限边界。直接调用 Provider 的应用必须保留宿主执行上下文和权限策略。

图像生成采用相同分层：

```js
import {ImageService} from '@eduwork/dsh-artifact-services/images'
const images = new ImageService()
const unregister = images.register({
  id: 'my-images', title: 'My image service', local: false,
  available: async () => hostImageAdapter.isConfigured(),
  capabilities: {nativeSizes: ['1024x1024'], customSize: true,
    fitModes: ['crop', 'pad'], formats: ['image/png']},
  generate: request => hostImageAdapter.generate(request),
})
const catalog = await images.list()
const image = await images.generate({provider: 'my-images', prompt: 'A landscape illustration',
  size: '1920x1080', fit: 'pad', projectPath: workspaceDirectory, signal, execution})
unregister()
```

Provider 接收 `prompt`、可选 `size`/`fit`、绝对 `projectPath`、短期 `execution`、`sessionId` 和 `signal`，返回真实工作区 PNG/JPEG/WebP/GIF/AVIF 的绝对 `path`；可附带 `mime`、`size`、`requestedSize`、`generationSize`、`sourceRelativePath`、`sourceSize`、`resized`、`resizeWarning`。

服务校验文件签名与工作区边界，规范化公开结果并移除其他字段；凭据留在宿主。原生尺寸选择和缩放由选定 Provider 负责，共享服务不强制某家厂商的尺寸列表。缩放失败应保留原图，报告实际尺寸与警告。

`images.list()` 返回 `{id,title,local,available,capabilities}`。没有可用 Provider 时报错，多个可用时要求明确选择，不自动回退。DSH 使用 `ctx.artifactServices.registerImageProvider(provider)`；注册/注销触发 `artifact-services/images-changed`，凭据或配置变化后适配器调用 `ctx.artifactServices.refreshImageProviders()`，更新内置 `artifact-images` 技能可用性。采用 `{skills:false}` 的装配须自行维护相应能力过滤。

```js
import {mkdtemp} from 'node:fs/promises'
import {tmpdir} from 'node:os'
import {join} from 'node:path'
import {runOffice, normalizeOfficeRequest} from '@eduwork/dsh-artifact-services/office'
if (!process.env.DSH_OFFICE_PYTHON) throw new Error('Configure the Python runtime first')
const projectPath = await mkdtemp(join(tmpdir(), 'shared-office-example-'))
const result = await runOffice({projectPath, signal: new AbortController().signal,
  environment: process.env,
  request: normalizeOfficeRequest('document', {
    action: 'create', output_path: 'report.docx',
    spec: {blocks:[{type:'paragraph',text:'Hello.'}]},
  }),
})
console.log(projectPath, result)
```

Office 支持文档和电子表格编辑、检查/验证、演示文稿布局、PDF 创建/合并/提取及 HTML 预览。演示文稿接受 `speaker_notes`；表格创建/编辑/追加支持 `{type:'text',value:'=literal'}` 与 `{type:'formula',value:'=SUM(A1:A2)'}`。普通字符串保留已有公式行为；公式验证不计算数值。`renderOfficePreview()` 提供有界结构化 HTML 预览，并非像素级 Office 渲染。

通过 `DSH_OFFICE_PYTHON` 指定已安装 `python/requirements.txt` 的解释器，仍接受旧 `CHATECNU_WORK_OFFICE_PYTHON`。隔离解释器运行本包内的 Python 源码，不运行另外维护的已安装 `ecnu_agent_*` 脚本。依赖准备是显式部署步骤，生成请求不会安装软件；机构素材可用 `DSH_OFFICE_BRAND_ASSETS` 注入，本包不内置。

```js
import {mkdtemp} from 'node:fs/promises'
import {tmpdir} from 'node:os'
import {join} from 'node:path'
import {renderMedia} from '@eduwork/dsh-artifact-services/media'
import {createMediaProviders} from '@eduwork/dsh-artifact-services/providers'
import {loadMusicCatalog} from '@eduwork/dsh-artifact-services/music'
const directory = await mkdtemp(join(tmpdir(), 'shared-video-example-'))
const providers = createMediaProviders()
const disposeMusic = await loadMusicCatalog(providers)
try {
  const file = await renderMedia({id:'overview',kind:'video',title:'Overview',
    segments:[{heading:'One idea',bullets:['A short point'],narration:''}],
    options:{narration:false,subtitles:false,sceneSeconds:3,aspect:'16:9',bgm:'quiet-explanation'},
  }, directory, new AbortController().signal, console.log, providers)
  console.log(file.path) // A real MP4 with BGM, without narration or subtitles.
} finally { disposeMusic() }
```

结构化音视频与可编辑 Remotion 项目使用 `lib/remotion.js`。可编辑运行器保留源码编辑、暂存、完整性绑定的语音任务、完整验证、封面和质量检查帧。`runVideoCommand(command, options, runtime)` 是调用入口；`createMediaRuntime()` 解析组件自身依赖，也可注入校验过的托管运行时。旧 CLI 环境检查仍为兼容启动器保留。

## DSH 装配

只加载一次 `@eduwork/dsh-artifact-services/dsh`。它提供 `artifactServices`、六个通用技能，以及启用且可用时的 `artifact-images`；默认十个工具，另有三个可选图像工具：

| 工具 | 职责 |
| --- | --- |
| `office_document`、`office_spreadsheet`、`office_presentation`、`office_pdf` | Office 操作，使用工作区相对路径 |
| `speech_voices`、`speech_synthesize` | Provider、音色、配乐发现及语音合成 |
| `image_providers`、`image_generate`、`image_edit` | 配置 `images.enabled:true` 后提供图像发现/生成 |
| `speech_transcription_providers`、`speech_transcribe` | 音频文件转写服务发现和转写 |
| `media_render` | 结构化音视频生成 |
| `video_project` | 可编辑项目初始化、暂存、语音任务、验证与渲染 |

不要同时注册旧 `tool-office`。权限、凭据和成果发布留在 DSH；工具将取消信号和原始执行上下文传给嵌套厂商工具。`{skills:false}` 允许产品自行管理通用技能；`{bgmRoot}` 可选择其他校验过的目录，默认使用随包六首配乐。

## 素材、构建与兼容性

-   六首器乐配乐包含乐谱 JSON、确定性合成代码、192 kbps MP3 以及哈希、音量、循环元数据，见[配乐使用与许可](https://npmcn.com/package/%40eduwork/dsh-artifact-services/media/BGM-USAGE.md)。
-   `templates/structured` 是结构化视频源码，`templates/editable` 是可修改起始项目；它们共用渲染器。
-   不含第三方音频采样或机构 Logo。Remotion 遵循自身许可证。
-   Office 能力限定于已支持的 OOXML/PDF 特性，不支持宏、修订记录、动画编辑或公式计算。
-   测试需配置 Python；父仓覆盖 Office 编辑/预览/验证、Provider 契约、配乐完整性、视频运行器与浏览器检查。

## 图像与平台配置

DSH 服务默认关闭生图。部署方须在 ArtifactServices 插件配置中显式设置 `images: { enabled: true }`，统一开启工具、技能与 Provider 调用。Office 和视频中的本地图片不受影响，语音与视频能力也独立于此选项。

内置系统 TTS 支持 Windows。其他平台需要注册语音 Provider 并提供兼容的原生资源，见[平台要求](https://npmcn.com/package/%40eduwork/dsh-artifact-services/docs/PLATFORMS.md)。

图像 Provider 可选实现 `edit(request)`，沿用 `generate` 的工作区、取消信号与结果契约；输入为 `images` 路径数组及可选 `mask`，通过 `images.edit(request)` / `image_edit` 调用。目录仅对实现编辑的 Provider 声明 `capabilities.edit:true`；不自动回退到生成。输入与输出均限制在工作区，结果须另存，复用工作区写入权限。

### DSH 内部工具调用

`@eduwork/dsh-artifact-services/tool-execution` 导出 `executeGovernedTool(ctx, input)`，供服务发起单个内部工具调用。0.2.2-rc.1 使用官方 `ToolExecutionPipeline`，旧宿主使用单调用接口；调用者应原样传递 `agent`、`signal`、`toolSet`、`rootCallId` 和 `parent`（如有）。模型产生的整批工具调用仍交给 DSH 执行器管理，不能用这个入口替换批次调度。

## 常见问题

### @eduwork/dsh-artifact-services 是什么？

共享应用程序和DSH工具的办公室、语音和媒体服务

### 如何安装 @eduwork/dsh-artifact-services？

在项目目录运行 npm install @eduwork/dsh-artifact-services，或使用 pnpm add / yarn add / bun add。

### @eduwork/dsh-artifact-services 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/eduwork\_\_dsh-artifact-services 是否存在。

### @eduwork/dsh-artifact-services 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @eduwork/dsh-artifact-services 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.18\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @eduwork/dsh-artifact-services 可以商用吗？

@eduwork/dsh-artifact-services 使用 MulanPSL-2\.0 AND MIT 许可。声明的许可为 MulanPSL-2\.0 AND MIT，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @eduwork/dsh-artifact-services 的下载量有多少？

根据 npm 官方下载统计，@eduwork/dsh-artifact-services 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,837 次，日均约 95 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @eduwork/dsh-artifact-services 还在维护吗？

最新版本 0\.3\.4 发布于 2026/11/12（1 天前）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/09/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。