dsh-pet 0.1.6 → 0.1.7

package/src/client/types.ts

@@ -1,37 +1,57 @@
-// 动作配置的类型模型（唯一事实来源为 config.jsonc 的 animations/animationWeights）。
+// 与 config.jsonc 结构完全同构的类型模型（唯一事实来源 = config.jsonc 的
+// animations / animationWeights / pets）。运行时（ANIM / 设置页 / PetCard）
+// 直接使用这套结构，不额外造转换后的类型。
+
+/** 支持的角落 */
+export type Corner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
 /** 移动动作：一个动作名 + 可选覆盖参数（未写字段取 moves.default） */
 export interface MoveSpec {
   name: string;
   params?: Record<string, number>;
 }
-/** 移动池配置 */
+
+/** 移动池 */
 export interface MovesConfig {
   default: Record<string, number>;
   actions: MoveSpec[];
 }
-/** 随机动作分类 */
+
+/** 随机动作分类（带文字、镜像会颠倒，facing=right 时跳过） */
 export interface Category {
   id: string;
   weight: number;
-  /** 带文字、镜像会颠倒：facing=right 时跳过 */
   noMirror?: boolean;
   actions: string[];
 }
-/** 动画权重（百分比） */
+
+/** 动画权重 */
 export interface Weights {
   idle: number;
   turn: number;
   move: number;
 }
-/** 运行时动作配置（由 config.jsonc 构建） */
-export interface AnimConfig {
+
+/** config.jsonc 的 animations 段 */
+export interface Animations {
   idle: string[];
   turn: string[];
   drag: string[];
   clicks: string[];
   moves: MovesConfig;
   categories: Category[];
-  weights: Weights;
 }
-/** 支持的角落 */
-export type Corner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+/** 一只宠物（与 jsonc pets[i] 同形，position 嵌套） */
+export interface Pet {
+  id: string;
+  size: number;
+  position: { corner: Corner; marginX: number; marginY: number };
+}
+
+/** config.jsonc 全集——运行时直接使用（ANIM 即本类型） */
+export interface ClientConfig {
+  pets: Pet[];
+  animations: Animations;
+  animationWeights: Weights;
+}

package/src/host/index.ts

@@ -5,19 +5,20 @@
  * 流式返回给浏览器。源文件（src/host/index.ts）由 tsdown 构建为 lib/index.js。
  *
  * 路由：
- *   /pet/thumb/<动画名>.webm  → 插件包内 assets/thumb/
- *   /pet/full/<动画名>.webm   → $DSH_HOME/pet-assets/（原始母版，需手动下载）
+ *   /pet/thumb/<动画名>.webm  → $DSH_HOME/dsh-pet/main-animation/（用户目录，优先）→ 插件包内 assets/thumb/
  *   /pet/config.jsonc        → 插件包内 assets/config.jsonc（默认值，只读）
- *   /pet/config              → 用户覆盖配置（大小/位置，JSON）
+ *   /pet/config              → 用户覆盖配置（pets / animations / animationWeights，JSON）
  *                                GET 读取、PUT 保存、DELETE 恢复默认（删除用户层）
+ *   /pet/config/meta         → 配置文件与素材目录路径（设置页展示用）
  *
- * 安全性：resolveAsset 做"防穿越"校验，保证路径仍在 assets 根目录内。
+ * 安全性：resolveAsset 做"防穿越"校验，保证路径仍在对应根目录内。
  *
- * TODO(类型)：peer 依赖类型包本地暂不可解析，ctx/config/req/res 暂用 any；
+ * TODO(类型)：peer 依赖类型包本地暂不可解析，ctx/req/res 暂用 any；
  *             依赖可解析后替换为 DSH 官方类型。
  */
 import { createReadStream, existsSync } from 'node:fs';
-import { readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { readFile, mkdir, rm, stat, writeFile } from 'node:fs/promises';
+import type { IncomingMessage, ServerResponse } from 'node:http';
 import { join, normalize, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
@@ -54,8 +55,14 @@ function resolveAsset(root: string, rel: string): string | undefined {
   return candidate;
 }
 
+/** 在 root 下解析并确认实体存在；非法（穿越）或不存在时返回 undefined */
+function resolveExisting(root: string, rel: string): string | undefined {
+  const candidate = resolveAsset(root, rel);
+  return candidate && existsSync(candidate) ? candidate : undefined;
+}
+
 /** 流式返回一个文件（带 Content-Type / 长度 / 缓存头）。 */
-async function sendFile(res: any, file: string, contentType: string): Promise<void> {
+async function sendFile(res: ServerResponse, file: string, contentType: string): Promise<void> {
   const { size } = await stat(file);
   res.writeHead(200, {
     'content-type': contentType,
@@ -71,14 +78,17 @@ async function sendFile(res: any, file: string, contentType: string): Promise<vo
 const CORNERS = ['top-left', 'top-right', 'bottom-left', 'bottom-right'];
 
 /** 发送 JSON 响应 */
-function sendJson(res: any, status: number, obj: unknown): void {
+function sendJson(res: ServerResponse, status: number, obj: unknown): void {
   const body = JSON.stringify(obj);
-  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(body) });
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': Buffer.byteLength(body),
+  });
   res.end(body);
 }
 
 /** 收集请求体（文本） */
-function readBody(req: any): Promise<string> {
+function readBody(req: IncomingMessage): Promise<string> {
   return new Promise((resolve2, reject) => {
     const chunks: Buffer[] = [];
     req.on('data', (c: Buffer) => chunks.push(c));
@@ -89,17 +99,20 @@ function readBody(req: any): Promise<string> {
 
 /** 校验并归一化用户配置：只接受 { pets: [{ id, size, position }] } */
 function sanitizeUserConfig(raw: unknown): { pets: unknown[] } | null {
-  const o = raw && typeof raw === 'object' ? raw as Record<string, any> : {};
+  const o = raw && typeof raw === 'object' ? (raw as Record<string, unknown>) : {};
   const arr = Array.isArray(o.pets) ? o.pets : null;
   if (!arr || !arr.length) return null;
   const out: unknown[] = [];
   for (const p of arr) {
     if (!p || typeof p !== 'object') return null;
-    const id = String((p as any).id ?? '');
+    const pp = p as Record<string, unknown>;
+    const id = String(pp.id ?? '');
+    // 有意过滤文件名非法字符（Windows 保留符 + 控制字符），防止配置值逃逸 main-config.json 路径
+    // eslint-disable-next-line no-control-regex
     if (!id || id.length > 64 || /[\\/:\x00-\x1f]/.test(id)) return null;
-    const size = Number((p as any).size);
+    const size = Number(pp.size);
     if (!Number.isFinite(size) || size <= 0) return null;
-    const pos = (p as any).position && typeof (p as any).position === 'object' ? (p as any).position : {};
+    const pos = pp.position && typeof pp.position === 'object' ? (pp.position as Record<string, unknown>) : {};
     const corner = String(pos.corner ?? '');
     if (!CORNERS.includes(corner)) return null;
     const marginX = Number(pos.marginX);
@@ -111,94 +124,108 @@ function sanitizeUserConfig(raw: unknown): { pets: unknown[] } | null {
 }
 
 /** 宿主插件主体：注册 `/pet` 前缀路由。 */
-export function apply(ctx: any, config: any): void {
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- DSH 注入的 ctx（webServer/locale 等 service 无静态类型）
+export function apply(ctx: any): void {
   const thumbRoot = join(PACKAGE_ROOT, 'assets', 'thumb');
-  const fullRoot: string = config.fullRoot ?? join(resolveDshHome(), 'pet-assets');
-  // 用户覆盖层：设置页保存的大小/位置（与包内 config.jsonc 默认值合并，覆盖层优先）
-  const userConfigPath = join(resolveDshHome(), 'pet-config.json');
-
-  ctx.effect(() => ctx.webServer.register({
-    kind: 'prefix',
-    path: ROUTE_PREFIX,
-    handler: async (req: any, res: any) => {
-      const url = new URL(req.url ?? '/', 'http://localhost');
-      const rest = decodeURIComponent(url.pathname.slice(ROUTE_PREFIX.length + 1));
-
-      // 用户覆盖配置：/pet/config（GET / PUT / DELETE）
-      if (rest === 'config') {
-        if (req.method === 'GET') {
-          try {
-            const raw = await readFile(userConfigPath, 'utf8');
-            sendJson(res, 200, JSON.parse(raw));
-          } catch {
-            sendJson(res, 200, {}); // 无覆盖配置 → 空对象，client 回落默认
+  // 用户数据根：配置与用户素材统一收敛于此（扩展包按 <插件id> 各自建目录）
+  const userRoot = join(resolveDshHome(), 'dsh-pet');
+  // 用户覆盖配置（pets / animations / animationWeights 覆盖片段）
+  const userConfigPath = join(userRoot, 'main-config.json');
+  // 用户动画目录（thumb 播放时优先于包内 assets/thumb）
+  const thumbUserRoot = join(userRoot, 'main-animation');
+
+  ctx.effect(
+    () =>
+      ctx.webServer.register({
+        kind: 'prefix',
+        path: ROUTE_PREFIX,
+        handler: async (req: IncomingMessage, res: ServerResponse) => {
+          const url = new URL(req.url ?? '/', 'http://localhost');
+          const rest = decodeURIComponent(url.pathname.slice(ROUTE_PREFIX.length + 1));
+
+          // 用户覆盖配置：/pet/config（GET / PUT / DELETE）
+          if (rest === 'config') {
+            if (req.method === 'GET') {
+              try {
+                const raw = await readFile(userConfigPath, 'utf8');
+                sendJson(res, 200, JSON.parse(raw));
+              } catch {
+                sendJson(res, 200, {}); // 无覆盖配置 → 空对象，client 回落默认
+              }
+              return;
+            }
+            if (req.method === 'PUT') {
+              try {
+                const body = await readBody(req);
+                const parsed = JSON.parse(body);
+                const clean = sanitizeUserConfig(parsed);
+                if (!clean) {
+                  sendJson(res, 400, {
+                    error: 'invalid pet config: expected { pets:[{id,size,position:{corner,marginX,marginY}}] }',
+                  });
+                  return;
+                }
+                await mkdir(userRoot, { recursive: true });
+                await writeFile(userConfigPath, JSON.stringify(clean, null, 2), 'utf8');
+                sendJson(res, 200, { ok: true });
+              } catch {
+                sendJson(res, 400, { error: 'invalid JSON body' });
+              }
+              return;
+            }
+            if (req.method === 'DELETE') {
+              try {
+                await rm(userConfigPath, { force: true });
+              } catch {
+                /* 不存在也视为成功 */
+              }
+              sendJson(res, 200, { ok: true });
+              return;
+            }
+            sendJson(res, 405, { error: 'method not allowed' });
+            return;
+          }
+
+          // 配置文件路径（设置页「高级配置」展示用）
+          if (rest === 'config/meta') {
+            sendJson(res, 200, {
+              user: userConfigPath,
+              default: join(PACKAGE_ROOT, 'assets', 'config.jsonc'),
+              animations: thumbUserRoot,
+            });
+            return;
           }
-          return;
-        }
-        if (req.method === 'PUT') {
-          try {
-            const body = await readBody(req);
-            const parsed = JSON.parse(body);
-            const clean = sanitizeUserConfig(parsed);
-            if (!clean) {
-              sendJson(res, 400, { error: 'invalid pet config: expected { pets:[{id,size,position:{corner,marginX,marginY}}] }' });
+
+          // 配置文件（JSONC）：/pet/config.jsonc → 包内 assets/config.jsonc
+          if (rest === 'config.jsonc') {
+            const cfgFile = join(PACKAGE_ROOT, 'assets', 'config.jsonc');
+            if (!existsSync(cfgFile)) {
+              res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+              res.end('dsh-pet: config.jsonc not found');
               return;
             }
-            await writeFile(userConfigPath, JSON.stringify(clean, null, 2), 'utf8');
-            sendJson(res, 200, { ok: true });
-          } catch {
-            sendJson(res, 400, { error: 'invalid JSON body' });
+            await sendFile(res, cfgFile, MIME['.jsonc'] ?? 'application/octet-stream');
+            return;
+          }
+
+          // 动画文件：/pet/thumb/<file>，查找顺序 = 用户动画目录 → 包内 assets/thumb
+          const [scope, ...nameParts] = rest.split('/');
+          if (scope !== 'thumb') {
+            res.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' });
+            res.end('dsh-pet: expected /pet/thumb/<file>');
+            return;
+          }
+          const fileName = nameParts.join('/');
+          const file = resolveExisting(thumbUserRoot, fileName) ?? resolveExisting(thumbRoot, fileName);
+          if (file === undefined) {
+            res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+            res.end('dsh-pet: asset not found');
+            return;
           }
-          return;
-        }
-        if (req.method === 'DELETE') {
-          try {
-            await rm(userConfigPath, { force: true });
-          } catch { /* 不存在也视为成功 */ }
-          sendJson(res, 200, { ok: true });
-          return;
-        }
-        sendJson(res, 405, { error: 'method not allowed' });
-        return;
-      }
-
-      // 配置文件（JSONC）：/pet/config.jsonc → 包内 assets/config.jsonc
-      if (rest === 'config.jsonc') {
-        const cfgFile = join(PACKAGE_ROOT, 'assets', 'config.jsonc');
-        if (!existsSync(cfgFile)) {
-          res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
-          res.end('dsh-pet: config.jsonc not found');
-          return;
-        }
-        await sendFile(res, cfgFile, MIME['.jsonc'] ?? 'application/octet-stream');
-        return;
-      }
-
-      // 第一段是 scope：thumb 或 full
-      const [scope, ...nameParts] = rest.split('/');
-      if (scope !== 'thumb' && scope !== 'full') {
-        res.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' });
-        res.end('dsh-pet: expected /pet/{thumb|full}/<file>');
-        return;
-      }
-
-      const fileName = nameParts.join('/');
-      const root = scope === 'thumb' ? thumbRoot : fullRoot;
-      const file = resolveAsset(root, fileName);
-      if (file === undefined) {
-        res.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' });
-        res.end('dsh-pet: invalid path');
-        return;
-      }
-      if (!existsSync(file)) {
-        res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
-        res.end(scope === 'full'
-          ? `dsh-pet: original asset not downloaded yet — run the fetch-assets script to populate ${fullRoot}`
-          : 'dsh-pet: asset not found');
-        return;
-      }
-      const ext = file.slice(file.lastIndexOf('.')).toLowerCase();
-      await sendFile(res, file, MIME[ext] ?? 'application/octet-stream');
-    },
-  }), 'dsh-pet: /pet asset route');
+          const ext = file.slice(file.lastIndexOf('.')).toLowerCase();
+          await sendFile(res, file, MIME[ext] ?? 'application/octet-stream');
+        },
+      }),
+    'dsh-pet: /pet asset route',
+  );
 }