@huaqiu/dsh-artifacts 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 深圳华秋智联股份有限公司
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @huaqiu/dsh-artifacts
+
+Huaqiu artifact storage plugin for DSH: persist generated KiCad files (symbols,
+footprints, schematics, project zips) and serve them back over the profile's
+`webServer` so the DSH web UI can preview/download them.
+
+## What it provides
+
+- Node service `ctx.huaqiuArtifacts` — a filesystem-backed artifact store with
+  metadata (`meta.json`), atomic writes, TTL expiry, a `maxBytes` cap, and strict
+  id validation (`^art_[0-9a-f]+$`). Filenames never affect the storage path.
+- HTTP routes under `/api/v1/huaqiu/artifacts`:
+  - `GET /api/v1/huaqiu/artifacts/<id>` — artifact metadata
+  - `GET /api/v1/huaqiu/artifacts/<id>/content` — raw content with
+    `Content-Disposition: inline` for browser preview
+- Injects `webServer` (via `cordis.patch.yml`).
+
+Port of `hq-edge`'s `DshPreviewArtifactService` with zero dependency on the HQ
+Edge monorepo (storage root defaults to `dshHomePath('artifacts')`).
+
+## Usage
+
+```ts
+// Node half (DSH plugin). Service is provided by the plugin entry:
+ctx.huaqiuArtifacts.create({ type: 'symbol', filename: 's.kicad_sym', content })
+ctx.huaqiuArtifacts.readContent(id)
+```
+
+```ts
+// Direct service use (no cordis):
+import { HuaqiuArtifactService } from '@huaqiu/dsh-artifacts/service'
+const svc = new HuaqiuArtifactService({ baseDir: '/tmp/artifacts' })
+```
+
+## Status
+
+Phase 0B — service + routes implemented and tested (10 tests). The `zip` artifact
+type already supports the system-design project zip; tool-level integration lands
+in Phases 1–3.

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# DSH bundle patch: inserts the Huaqiu artifact store + its HTTP routes.
+- insert:
+    - id: huaqiu-artifacts
+      name: '@huaqiu/dsh-artifacts'
+      inject: ['webServer']

package/lib/index.d.mts

@@ -0,0 +1,17 @@
+import { ArtifactMeta, ArtifactType, CreateArtifactInput, CreateArtifactResult, HuaqiuArtifacts } from "./service.mjs";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/index.d.ts
+declare const name = "@huaqiu/dsh-artifacts";
+declare const inject: readonly ["webServer"];
+interface HuaqiuArtifactsConfig {
+  baseDir?: string;
+  maxBytes?: number;
+}
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    huaqiuArtifacts: HuaqiuArtifacts;
+  }
+}
+declare function apply(ctx: Context, config?: HuaqiuArtifactsConfig): void;
+//#endregion
+export { type ArtifactMeta, type ArtifactType, type CreateArtifactInput, type CreateArtifactResult, type HuaqiuArtifacts, HuaqiuArtifactsConfig, apply, inject, name };

package/lib/index.mjs

@@ -0,0 +1,99 @@
+import { HuaqiuArtifactService, log } from "./service.mjs";
+//#region src/routes.ts
+const ARTIFACTS_ROUTE_PREFIX = "/api/v1/huaqiu/artifacts";
+function sendJson(res, status, body) {
+	const payload = JSON.stringify(body);
+	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+	res.end(payload);
+}
+/** Parse `<id>` or `<id>/content` off the route prefix. Returns null on bad shape. */
+function parsePath(req) {
+	const url = req.url ?? "";
+	const q = url.indexOf("?");
+	const pathname = q >= 0 ? url.slice(0, q) : url;
+	if (!pathname.startsWith("/api/v1/huaqiu/artifacts")) return null;
+	const rest = pathname.slice(24);
+	if (rest === "") return null;
+	const segs = rest.split("/").filter(Boolean);
+	if (segs.length === 1) return {
+		id: segs[0],
+		content: false
+	};
+	if (segs.length === 2 && segs[1] === "content") return {
+		id: segs[0],
+		content: true
+	};
+	return null;
+}
+function createArtifactsHandler(service) {
+	return async (req, res) => {
+		try {
+			const parsed = parsePath(req);
+			if (!parsed) {
+				sendJson(res, 404, { error: "not found" });
+				return;
+			}
+			const { id, content } = parsed;
+			if (content) {
+				const meta = await service.get(id);
+				if (!meta) {
+					sendJson(res, 404, { error: "artifact not found or expired" });
+					return;
+				}
+				const bytes = await service.readContent(id);
+				if (!bytes) {
+					sendJson(res, 404, { error: "artifact content missing" });
+					return;
+				}
+				const safeFilename = encodeURIComponent(meta.filename);
+				res.writeHead(200, {
+					"content-type": meta.mimeType || "application/octet-stream",
+					"content-length": String(bytes.byteLength),
+					"content-disposition": `inline; filename*=UTF-8''${safeFilename}`,
+					"cache-control": "no-store"
+				});
+				res.end(Buffer.from(bytes));
+				return;
+			}
+			const meta = await service.get(id);
+			if (!meta) {
+				sendJson(res, 404, { error: "artifact not found or expired" });
+				return;
+			}
+			sendJson(res, 200, {
+				id: meta.id,
+				type: meta.type,
+				filename: meta.filename,
+				mimeType: meta.mimeType,
+				size: meta.size,
+				createdAt: meta.createdAt
+			});
+		} catch (err) {
+			sendJson(res, 500, {
+				error: "internal error resolving artifact",
+				detail: String(err)
+			});
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+const name = "@huaqiu/dsh-artifacts";
+const inject = ["webServer"];
+function apply(ctx, config = {}) {
+	const service = new HuaqiuArtifactService(config);
+	ctx.effect(() => ctx.provide("huaqiuArtifacts", service));
+	ctx.effect(() => ctx.webServer.register({
+		kind: "prefix",
+		path: ARTIFACTS_ROUTE_PREFIX,
+		handler: createArtifactsHandler(service)
+	}));
+	ctx.effect(() => {
+		service.deleteAll({ onlyExpired: true }).then((removed) => {
+			if (removed > 0) log("debug", "artifacts: expired sweep removed", { removed });
+		}).catch((err) => log("warn", "artifacts: expired sweep failed", { err }));
+		return () => {};
+	});
+}
+//#endregion
+export { apply, inject, name };

package/lib/service.d.mts

@@ -0,0 +1,63 @@
+//#region src/service.d.ts
+type ArtifactType = 'symbol' | 'footprint' | 'schematic' | 'pcb' | 'zip';
+interface ArtifactMeta {
+  id: string;
+  type: ArtifactType;
+  filename: string;
+  mimeType: string;
+  size: number;
+  createdAt: string;
+  expiresAt?: string;
+}
+interface CreateArtifactInput {
+  type: ArtifactType;
+  filename: string;
+  /** string is UTF-8 (or base64 when `contentEncoding === 'base64'`). */
+  content: string | Uint8Array;
+  contentEncoding?: 'utf8' | 'base64';
+  /** Optional TTL seconds from now; undefined = manual cleanup only. */
+  ttlSeconds?: number;
+}
+interface CreateArtifactResult {
+  id: string;
+  type: ArtifactType;
+  filename: string;
+  size: number;
+}
+interface ArtifactsServiceOptions {
+  /**
+   * Base directory hosting `dsh-artifacts/`. Defaults to
+   * `dshHomePath('artifacts')` (`~/.dsh/artifacts/`). Overridable for tests.
+   */
+  baseDir?: string;
+  /** Hard cap on stored artifact bytes. Default 16 MiB. */
+  maxBytes?: number;
+}
+interface HuaqiuArtifacts {
+  create(input: CreateArtifactInput): Promise<CreateArtifactResult>;
+  get(id: string): Promise<ArtifactMeta | null>;
+  readContent(id: string): Promise<Uint8Array | null>;
+  delete(id: string): Promise<void>;
+  deleteAll(opts?: {
+    onlyExpired?: boolean;
+  }): Promise<number>;
+}
+declare function log(level: 'debug' | 'warn', msg: string, extra?: Record<string, unknown>): void;
+declare class HuaqiuArtifactService implements HuaqiuArtifacts {
+  private readonly baseDir;
+  private readonly maxBytes;
+  constructor(options?: ArtifactsServiceOptions);
+  private artifactsRoot;
+  private artifactDir;
+  create(input: CreateArtifactInput): Promise<CreateArtifactResult>;
+  get(id: string): Promise<ArtifactMeta | null>;
+  /** Returns `null` when missing or expired (miss signal for the HTTP 404). */
+  readContent(id: string): Promise<Uint8Array | null>;
+  delete(id: string): Promise<void>;
+  deleteAll(opts?: {
+    onlyExpired?: boolean;
+  }): Promise<number>;
+  private isExpired;
+}
+//#endregion
+export { ArtifactMeta, ArtifactType, ArtifactsServiceOptions, CreateArtifactInput, CreateArtifactResult, HuaqiuArtifactService, HuaqiuArtifacts, log };

package/lib/service.mjs

@@ -0,0 +1,197 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
+//#region src/service.ts
+/**
+* `@huaqiu/dsh-artifacts` — user-wide, flat storage for ECAD preview artifacts
+* (KiCad symbol / footprint / schematic / pcb / zip) in DSH.
+*
+* Port of `hq-edge`'s `DshPreviewArtifactService` (apps/server/src/artifacts/
+* dsh-preview-artifacts.service.ts) with zero dependency on the HQ Edge
+* monorepo:
+*   - default root = `dshHomePath('artifacts')` (`~/.dsh/artifacts/`)
+*   - `node:crypto.randomUUID` instead of `uuid`
+*   - no logger framework (minimal internal logger)
+*   - hardening: strict `^art_[0-9a-f]+$` id, filename never in the storage
+*     path, max-size cap, atomic writes, TTL expiry
+*   - `readContent(): Promise<Uint8Array | null>` (no streaming abstraction)
+*
+* Layout on disk:
+*   <baseDir>/dsh-artifacts/<artifactId>/
+*     meta.json   # id, type, filename, mimeType, size, createdAt, expiresAt?
+*     content     # raw bytes
+*/
+const VALID_TYPES = /* @__PURE__ */ new Set([
+	"symbol",
+	"footprint",
+	"schematic",
+	"pcb",
+	"zip"
+]);
+function isValidArtifactType(v) {
+	return typeof v === "string" && VALID_TYPES.has(v);
+}
+/** Opaque id we mint ourselves — hardened against any path use. */
+const ARTIFACT_ID_PATTERN = /^art_[0-9a-f]+$/;
+function mimeTypeFor(type, filename) {
+	const lower = filename.toLowerCase();
+	if (lower.endsWith(".kicad_sym")) return "application/x.kicad-symbol";
+	if (lower.endsWith(".kicad_mod")) return "application/x.kicad-footprint";
+	if (lower.endsWith(".kicad_footprint")) return "application/x.kicad-footprint";
+	if (lower.endsWith(".kicad_sch")) return "application/x.kicad-schematic";
+	if (lower.endsWith(".kicad_pcb")) return "application/x.kicad-pcb";
+	if (lower.endsWith(".kicad_pro")) return "application/x.kicad-project";
+	if (lower.endsWith(".zip")) return "application/zip";
+	switch (type) {
+		case "symbol": return "application/x.kicad-symbol";
+		case "footprint": return "application/x.kicad-footprint";
+		case "schematic": return "application/x.kicad-schematic";
+		case "pcb": return "application/x.kicad-pcb";
+		case "zip": return "application/zip";
+	}
+}
+function toBytes(content, encoding) {
+	if (typeof content === "string") return encoding === "base64" ? Buffer.from(content, "base64") : Buffer.from(content, "utf8");
+	return content instanceof Uint8Array ? content : new Uint8Array(content);
+}
+function log(level, msg, extra) {
+	if (level === "warn" || process.env.DSH_ARTIFACTS_DEBUG) {
+		const line = `[dsh-artifacts] ${msg}${extra ? " " + JSON.stringify(extra) : ""}`;
+		if (level === "warn") console.warn(line);
+		else console.debug(line);
+	}
+}
+var HuaqiuArtifactService = class {
+	baseDir;
+	maxBytes;
+	constructor(options = {}) {
+		this.baseDir = options.baseDir ?? dshHomePath("artifacts");
+		this.maxBytes = options.maxBytes ?? 16777216;
+	}
+	artifactsRoot() {
+		return path.resolve(this.baseDir, "dsh-artifacts");
+	}
+	artifactDir(artifactId) {
+		if (!ARTIFACT_ID_PATTERN.test(artifactId)) throw new Error(`Invalid artifactId: does not match ${String(ARTIFACT_ID_PATTERN)}`);
+		return path.join(this.artifactsRoot(), artifactId);
+	}
+	async create(input) {
+		if (!isValidArtifactType(input.type)) throw new Error(`Invalid artifact type: ${String(input.type)}`);
+		if (typeof input.filename !== "string" || input.filename.length === 0) throw new Error("filename is required");
+		const buf = toBytes(input.content, input.contentEncoding);
+		if (buf.byteLength > this.maxBytes) throw new Error(`artifact content exceeds max size (${buf.byteLength} > ${this.maxBytes})`);
+		const id = "art_" + randomUUID().replace(/-/g, "").slice(0, 16);
+		const now = /* @__PURE__ */ new Date();
+		const meta = {
+			id,
+			type: input.type,
+			filename: input.filename,
+			mimeType: mimeTypeFor(input.type, input.filename),
+			size: buf.byteLength,
+			createdAt: now.toISOString()
+		};
+		if (typeof input.ttlSeconds === "number" && Number.isFinite(input.ttlSeconds) && input.ttlSeconds > 0) meta.expiresAt = new Date(now.getTime() + input.ttlSeconds * 1e3).toISOString();
+		const dir = this.artifactDir(id);
+		await fs.promises.mkdir(dir, { recursive: true });
+		const tmpContent = path.join(dir, "content.tmp");
+		await fs.promises.writeFile(tmpContent, buf);
+		await fs.promises.rename(tmpContent, path.join(dir, "content"));
+		const tmpMeta = path.join(dir, "meta.json.tmp");
+		await fs.promises.writeFile(tmpMeta, JSON.stringify(meta, null, 2), "utf8");
+		await fs.promises.rename(tmpMeta, path.join(dir, "meta.json"));
+		log("debug", "created", {
+			id,
+			type: input.type,
+			size: buf.byteLength
+		});
+		return {
+			id,
+			type: meta.type,
+			filename: meta.filename,
+			size: meta.size
+		};
+	}
+	async get(id) {
+		if (typeof id !== "string" || !ARTIFACT_ID_PATTERN.test(id)) return null;
+		try {
+			const dir = this.artifactDir(id);
+			const fp = path.join(dir, "meta.json");
+			const raw = await fs.promises.readFile(fp, "utf8");
+			const meta = JSON.parse(raw);
+			if (this.isExpired(meta)) {
+				this.delete(id);
+				return null;
+			}
+			return meta;
+		} catch {
+			return null;
+		}
+	}
+	/** Returns `null` when missing or expired (miss signal for the HTTP 404). */
+	async readContent(id) {
+		if (!await this.get(id)) return null;
+		try {
+			return new Uint8Array(await fs.promises.readFile(path.join(this.artifactDir(id), "content")));
+		} catch {
+			return null;
+		}
+	}
+	async delete(id) {
+		if (typeof id !== "string" || !ARTIFACT_ID_PATTERN.test(id)) return;
+		try {
+			const dir = this.artifactDir(id);
+			await fs.promises.rm(dir, {
+				recursive: true,
+				force: true
+			});
+			log("debug", "deleted", { id });
+		} catch (err) {
+			log("warn", "delete failed", {
+				id,
+				err
+			});
+		}
+	}
+	async deleteAll(opts = {}) {
+		const { onlyExpired = false } = opts;
+		const root = this.artifactsRoot();
+		let removed = 0;
+		if (!fs.existsSync(root)) return 0;
+		try {
+			const entries = await fs.promises.readdir(root, { withFileTypes: true });
+			for (const entry of entries) {
+				if (!entry.isDirectory()) continue;
+				if (onlyExpired) try {
+					const raw = await fs.promises.readFile(path.join(root, entry.name, "meta.json"), "utf8");
+					const meta = JSON.parse(raw);
+					if (!this.isExpired(meta)) continue;
+				} catch {
+					continue;
+				}
+				await fs.promises.rm(path.join(root, entry.name), {
+					recursive: true,
+					force: true
+				});
+				removed += 1;
+			}
+			log("debug", "deleteAll complete", {
+				onlyExpired,
+				removed
+			});
+		} catch (err) {
+			log("warn", "deleteAll failed", { err });
+		}
+		return removed;
+	}
+	isExpired(meta) {
+		if (!meta.expiresAt) return false;
+		try {
+			return new Date(meta.expiresAt).getTime() <= Date.now();
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+export { HuaqiuArtifactService, log };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@huaqiu/dsh-artifacts",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "./lib/index.mjs",
+  "types": "./lib/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.mts",
+      "default": "./lib/index.mjs"
+    },
+    "./service": {
+      "types": "./lib/service.d.mts",
+      "default": "./lib/service.mjs"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-host-webserver": ">=0.1.0-rc.0 <0.2.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-home-paths": ">=0.1.0-rc.0 <0.2.0"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+/**
+ * `@huaqiu/dsh-artifacts` — DSH plugin entry.
+ *
+ * Provides the `huaqiuArtifacts` service (node tools call it in-process; no
+ * HTTP loopback) and mounts the read-only preview routes on `ctx.webServer`
+ * for the browser UI.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import { HuaqiuArtifactService, log, type HuaqiuArtifacts } from './service.js'
+import { ARTIFACTS_ROUTE_PREFIX, createArtifactsHandler } from './routes.js'
+
+export type {
+  ArtifactMeta,
+  ArtifactType,
+  CreateArtifactInput,
+  CreateArtifactResult,
+  HuaqiuArtifacts,
+} from './service.js'
+
+export const name = '@huaqiu/dsh-artifacts'
+export const inject = ['webServer'] as const
+
+export interface HuaqiuArtifactsConfig {
+  baseDir?: string
+  maxBytes?: number
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    huaqiuArtifacts: HuaqiuArtifacts
+  }
+}
+
+export function apply(ctx: Context, config: HuaqiuArtifactsConfig = {}): void {
+  const service = new HuaqiuArtifactService(config)
+  ctx.effect(() => ctx.provide('huaqiuArtifacts', service))
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'prefix',
+    path: ARTIFACTS_ROUTE_PREFIX,
+    handler: createArtifactsHandler(service),
+  }))
+
+  // Boot-time GC: `deleteAll({ onlyExpired: true })` is implemented but nothing
+  // ever calls it, so `~/.dsh/artifacts/` (and any migrated location) grows
+  // without bound (spec risk R6). Sweep once at startup; never fail startup on a
+  // disk error, and never block activation on the scan.
+  ctx.effect(() => {
+    void service.deleteAll({ onlyExpired: true })
+      .then((removed) => { if (removed > 0) log('debug', 'artifacts: expired sweep removed', { removed }) })
+      .catch((err) => log('warn', 'artifacts: expired sweep failed', { err }))
+    return () => {}
+  })
+}

package/src/routes.ts

@@ -0,0 +1,95 @@
+/**
+ * HTTP adapter for `@huaqiu/dsh-artifacts` (browser half of the preview flow).
+ *
+ * Browser → same-origin DSH webServer → `ctx.webServer` prefix route
+ * `/api/v1/huaqiu/artifacts` (the `edge-bridge` `/hq-edge` precedent, but
+ * plugin-owned). Parameterized sub-paths are parsed in the handler:
+ *
+ *   GET /api/v1/huaqiu/artifacts/<id>          → metadata JSON
+ *   GET /api/v1/huaqiu/artifacts/<id>/content  → raw bytes
+ *
+ * A single prefix route is used because the DSH `WebRoute` supports exact or
+ * prefix matches only (no `:id` path params), and two prefix routes on the
+ * same base path would collide.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { HuaqiuArtifacts } from './service.js'
+
+export const ARTIFACTS_ROUTE_PREFIX = '/api/v1/huaqiu/artifacts'
+
+export type ArtifactsHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+) => Promise<void> | void
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  const payload = JSON.stringify(body)
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(payload)
+}
+
+/** Parse `<id>` or `<id>/content` off the route prefix. Returns null on bad shape. */
+function parsePath(req: IncomingMessage): { id: string; content: boolean } | null {
+  const url = req.url ?? ''
+  const q = url.indexOf('?')
+  const pathname = q >= 0 ? url.slice(0, q) : url
+  if (!pathname.startsWith(ARTIFACTS_ROUTE_PREFIX)) return null
+  const rest = pathname.slice(ARTIFACTS_ROUTE_PREFIX.length)
+  // rest === '' or startsWith('/')
+  if (rest === '') return null
+  const segs = rest.split('/').filter(Boolean)
+  if (segs.length === 1) return { id: segs[0]!, content: false }
+  if (segs.length === 2 && segs[1] === 'content') return { id: segs[0]!, content: true }
+  return null
+}
+
+export function createArtifactsHandler(service: HuaqiuArtifacts): ArtifactsHandler {
+  return async (req, res) => {
+    try {
+      const parsed = parsePath(req)
+      if (!parsed) {
+        sendJson(res, 404, { error: 'not found' })
+        return
+      }
+      const { id, content } = parsed
+
+      if (content) {
+        const meta = await service.get(id)
+        if (!meta) {
+          sendJson(res, 404, { error: 'artifact not found or expired' })
+          return
+        }
+        const bytes = await service.readContent(id)
+        if (!bytes) {
+          sendJson(res, 404, { error: 'artifact content missing' })
+          return
+        }
+        const safeFilename = encodeURIComponent(meta.filename)
+        res.writeHead(200, {
+          'content-type': meta.mimeType || 'application/octet-stream',
+          'content-length': String(bytes.byteLength),
+          'content-disposition': `inline; filename*=UTF-8''${safeFilename}`,
+          'cache-control': 'no-store',
+        })
+        res.end(Buffer.from(bytes))
+        return
+      }
+
+      const meta = await service.get(id)
+      if (!meta) {
+        sendJson(res, 404, { error: 'artifact not found or expired' })
+        return
+      }
+      sendJson(res, 200, {
+        id: meta.id,
+        type: meta.type,
+        filename: meta.filename,
+        mimeType: meta.mimeType,
+        size: meta.size,
+        createdAt: meta.createdAt,
+      })
+    } catch (err) {
+      sendJson(res, 500, { error: 'internal error resolving artifact', detail: String(err) })
+    }
+  }
+}

package/src/service.ts

@@ -0,0 +1,261 @@
+/**
+ * `@huaqiu/dsh-artifacts` — user-wide, flat storage for ECAD preview artifacts
+ * (KiCad symbol / footprint / schematic / pcb / zip) in DSH.
+ *
+ * Port of `hq-edge`'s `DshPreviewArtifactService` (apps/server/src/artifacts/
+ * dsh-preview-artifacts.service.ts) with zero dependency on the HQ Edge
+ * monorepo:
+ *   - default root = `dshHomePath('artifacts')` (`~/.dsh/artifacts/`)
+ *   - `node:crypto.randomUUID` instead of `uuid`
+ *   - no logger framework (minimal internal logger)
+ *   - hardening: strict `^art_[0-9a-f]+$` id, filename never in the storage
+ *     path, max-size cap, atomic writes, TTL expiry
+ *   - `readContent(): Promise<Uint8Array | null>` (no streaming abstraction)
+ *
+ * Layout on disk:
+ *   <baseDir>/dsh-artifacts/<artifactId>/
+ *     meta.json   # id, type, filename, mimeType, size, createdAt, expiresAt?
+ *     content     # raw bytes
+ */
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths'
+
+// ── Public types ────────────────────────────────────────────────────────────
+
+export type ArtifactType = 'symbol' | 'footprint' | 'schematic' | 'pcb' | 'zip'
+
+export interface ArtifactMeta {
+  id: string
+  type: ArtifactType
+  filename: string
+  mimeType: string
+  size: number
+  createdAt: string
+  expiresAt?: string
+}
+
+export interface CreateArtifactInput {
+  type: ArtifactType
+  filename: string
+  /** string is UTF-8 (or base64 when `contentEncoding === 'base64'`). */
+  content: string | Uint8Array
+  contentEncoding?: 'utf8' | 'base64'
+  /** Optional TTL seconds from now; undefined = manual cleanup only. */
+  ttlSeconds?: number
+}
+
+export interface CreateArtifactResult {
+  id: string
+  type: ArtifactType
+  filename: string
+  size: number
+}
+
+export interface ArtifactsServiceOptions {
+  /**
+   * Base directory hosting `dsh-artifacts/`. Defaults to
+   * `dshHomePath('artifacts')` (`~/.dsh/artifacts/`). Overridable for tests.
+   */
+  baseDir?: string
+  /** Hard cap on stored artifact bytes. Default 16 MiB. */
+  maxBytes?: number
+}
+
+export interface HuaqiuArtifacts {
+  create(input: CreateArtifactInput): Promise<CreateArtifactResult>
+  get(id: string): Promise<ArtifactMeta | null>
+  readContent(id: string): Promise<Uint8Array | null>
+  delete(id: string): Promise<void>
+  deleteAll(opts?: { onlyExpired?: boolean }): Promise<number>
+}
+
+// ── Internal helpers ────────────────────────────────────────────────────────
+
+const VALID_TYPES: ReadonlySet<ArtifactType> = new Set([
+  'symbol', 'footprint', 'schematic', 'pcb', 'zip',
+])
+
+function isValidArtifactType(v: unknown): v is ArtifactType {
+  return typeof v === 'string' && VALID_TYPES.has(v as ArtifactType)
+}
+
+/** Opaque id we mint ourselves — hardened against any path use. */
+const ARTIFACT_ID_PATTERN = /^art_[0-9a-f]+$/
+
+function mimeTypeFor(type: ArtifactType, filename: string): string {
+  const lower = filename.toLowerCase()
+  if (lower.endsWith('.kicad_sym')) return 'application/x.kicad-symbol'
+  if (lower.endsWith('.kicad_mod')) return 'application/x.kicad-footprint'
+  if (lower.endsWith('.kicad_footprint')) return 'application/x.kicad-footprint'
+  if (lower.endsWith('.kicad_sch')) return 'application/x.kicad-schematic'
+  if (lower.endsWith('.kicad_pcb')) return 'application/x.kicad-pcb'
+  if (lower.endsWith('.kicad_pro')) return 'application/x.kicad-project'
+  if (lower.endsWith('.zip')) return 'application/zip'
+  switch (type) {
+    case 'symbol': return 'application/x.kicad-symbol'
+    case 'footprint': return 'application/x.kicad-footprint'
+    case 'schematic': return 'application/x.kicad-schematic'
+    case 'pcb': return 'application/x.kicad-pcb'
+    case 'zip': return 'application/zip'
+  }
+}
+
+function toBytes(content: string | Uint8Array, encoding: 'utf8' | 'base64' | undefined): Uint8Array {
+  if (typeof content === 'string') {
+    return encoding === 'base64' ? Buffer.from(content, 'base64') : Buffer.from(content, 'utf8')
+  }
+  return content instanceof Uint8Array ? content : new Uint8Array(content)
+}
+
+export function log(level: 'debug' | 'warn', msg: string, extra?: Record<string, unknown>): void {
+  // Minimal, dependency-free logger. DSH plugins should not pull a logger lib.
+  if (level === 'warn' || process.env.DSH_ARTIFACTS_DEBUG) {
+    const line = `[dsh-artifacts] ${msg}${extra ? ' ' + JSON.stringify(extra) : ''}`
+    if (level === 'warn') console.warn(line)
+    else console.debug(line)
+  }
+}
+
+// ── Service ─────────────────────────────────────────────────────────────────
+
+export class HuaqiuArtifactService implements HuaqiuArtifacts {
+  private readonly baseDir: string
+  private readonly maxBytes: number
+
+  constructor(options: ArtifactsServiceOptions = {}) {
+    this.baseDir = options.baseDir ?? dshHomePath('artifacts')
+    this.maxBytes = options.maxBytes ?? 16 * 1024 * 1024
+  }
+
+  private artifactsRoot(): string {
+    return path.resolve(this.baseDir, 'dsh-artifacts')
+  }
+
+  private artifactDir(artifactId: string): string {
+    // Strict id-only guard: ids are minted by us, but enforce the pattern so
+    // no user-derived input can ever construct a path.
+    if (!ARTIFACT_ID_PATTERN.test(artifactId)) {
+      throw new Error(`Invalid artifactId: does not match ${String(ARTIFACT_ID_PATTERN)}`)
+    }
+    return path.join(this.artifactsRoot(), artifactId)
+  }
+
+  async create(input: CreateArtifactInput): Promise<CreateArtifactResult> {
+    if (!isValidArtifactType(input.type)) {
+      throw new Error(`Invalid artifact type: ${String(input.type)}`)
+    }
+    if (typeof input.filename !== 'string' || input.filename.length === 0) {
+      throw new Error('filename is required')
+    }
+    const buf = toBytes(input.content, input.contentEncoding)
+    if (buf.byteLength > this.maxBytes) {
+      throw new Error(`artifact content exceeds max size (${buf.byteLength} > ${this.maxBytes})`)
+    }
+
+    const id = 'art_' + randomUUID().replace(/-/g, '').slice(0, 16)
+    const now = new Date()
+    const meta: ArtifactMeta = {
+      id,
+      type: input.type,
+      filename: input.filename,
+      mimeType: mimeTypeFor(input.type, input.filename),
+      size: buf.byteLength,
+      createdAt: now.toISOString(),
+    }
+    if (typeof input.ttlSeconds === 'number' && Number.isFinite(input.ttlSeconds) && input.ttlSeconds > 0) {
+      meta.expiresAt = new Date(now.getTime() + input.ttlSeconds * 1000).toISOString()
+    }
+
+    const dir = this.artifactDir(id)
+    await fs.promises.mkdir(dir, { recursive: true })
+    // Write content FIRST so an interrupted write never leaves a "valid" meta
+    // pointing at partial bytes. Both writes are atomic (tmp + rename).
+    const tmpContent = path.join(dir, 'content.tmp')
+    await fs.promises.writeFile(tmpContent, buf)
+    await fs.promises.rename(tmpContent, path.join(dir, 'content'))
+    const tmpMeta = path.join(dir, 'meta.json.tmp')
+    await fs.promises.writeFile(tmpMeta, JSON.stringify(meta, null, 2), 'utf8')
+    await fs.promises.rename(tmpMeta, path.join(dir, 'meta.json'))
+
+    log('debug', 'created', { id, type: input.type, size: buf.byteLength })
+    return { id, type: meta.type, filename: meta.filename, size: meta.size }
+  }
+
+  async get(id: string): Promise<ArtifactMeta | null> {
+    if (typeof id !== 'string' || !ARTIFACT_ID_PATTERN.test(id)) return null
+    try {
+      const dir = this.artifactDir(id)
+      const fp = path.join(dir, 'meta.json')
+      const raw = await fs.promises.readFile(fp, 'utf8')
+      const meta = JSON.parse(raw) as ArtifactMeta
+      if (this.isExpired(meta)) {
+        void this.delete(id) // best-effort cleanup, non-fatal
+        return null
+      }
+      return meta
+    } catch {
+      return null
+    }
+  }
+
+  /** Returns `null` when missing or expired (miss signal for the HTTP 404). */
+  async readContent(id: string): Promise<Uint8Array | null> {
+    const meta = await this.get(id)
+    if (!meta) return null
+    try {
+      return new Uint8Array(await fs.promises.readFile(path.join(this.artifactDir(id), 'content')))
+    } catch {
+      return null
+    }
+  }
+
+  async delete(id: string): Promise<void> {
+    if (typeof id !== 'string' || !ARTIFACT_ID_PATTERN.test(id)) return
+    try {
+      const dir = this.artifactDir(id)
+      await fs.promises.rm(dir, { recursive: true, force: true })
+      log('debug', 'deleted', { id })
+    } catch (err) {
+      log('warn', 'delete failed', { id, err })
+    }
+  }
+
+  async deleteAll(opts: { onlyExpired?: boolean } = {}): Promise<number> {
+    const { onlyExpired = false } = opts
+    const root = this.artifactsRoot()
+    let removed = 0
+    if (!fs.existsSync(root)) return 0
+    try {
+      const entries = await fs.promises.readdir(root, { withFileTypes: true })
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue
+        if (onlyExpired) {
+          try {
+            const raw = await fs.promises.readFile(path.join(root, entry.name, 'meta.json'), 'utf8')
+            const meta = JSON.parse(raw) as ArtifactMeta
+            if (!this.isExpired(meta)) continue
+          } catch {
+            continue // missing/corrupt meta — leave to admin cleanup
+          }
+        }
+        await fs.promises.rm(path.join(root, entry.name), { recursive: true, force: true })
+        removed += 1
+      }
+      log('debug', 'deleteAll complete', { onlyExpired, removed })
+    } catch (err) {
+      log('warn', 'deleteAll failed', { err })
+    }
+    return removed
+  }
+
+  private isExpired(meta: ArtifactMeta): boolean {
+    if (!meta.expiresAt) return false
+    try {
+      return new Date(meta.expiresAt).getTime() <= Date.now()
+    } catch {
+      return false
+    }
+  }
+}