dsh-pet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PC2005-cloud
+
+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,10 @@
+# dsh-pet
+
+A floating desktop pet for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web UI.
+
+```sh
+dsh plugin --profile web add dsh-pet
+```
+
+Full source, asset pipeline, and generation prompts live in the repository:
+**https://github.com/PC2005-cloud/dsh-pet**

package/README.zh.md

@@ -0,0 +1,10 @@
+# dsh-pet
+
+一只住在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web 界面里的桌面宠物。
+
+```sh
+dsh plugin --profile web add dsh-pet
+```
+
+完整源码、素材生成链与提示词都在仓库中：
+**https://github.com/PC2005-cloud/dsh-pet**

package/cordis.patch.yml

@@ -0,0 +1,29 @@
+# ============================================================================
+# dsh-pet 的 bundle patch —— 把宠物插件挂进 DSH 配置树
+# ============================================================================
+#
+# 【这是什么】
+#   这是 dsh-pet 的"挂载声明"。DSH 启动时按 bundle 层栈把各个插件的
+#   patch 叠起来组成配置树。本文件就是 dsh-pet 这一层的内容。
+#
+# 【工作原理】
+#   - insert：往配置树里添加新的插件行（entry）
+#   - 每个 entry 有 id（行标识，patch 覆盖时按它定位）和 name（插件模块）
+#   - name: 'dsh-pet' 会解析包入口 lib/index.js（宿主半侧）
+#   - 因为 package.json 声明了 dsh.client，DSH 的模块系统同时会把
+#     这个包扫描为"浏览器插件"，提供 /plugins/dsh-pet/client.js 给页面
+#
+# 【config 说明】
+#   这里写的 config 会传给 host 半侧的 apply(ctx, config)。
+#   注意：浏览器半侧（client）目前收不到这些配置（DSH 客户端配置管线
+#   限制，client 收到的是空对象），所以这些值目前只影响 host 半侧。
+#   宠物行为参数（size/position 等）在 client 里走代码默认值。
+#
+# ============================================================================
+
+- insert:
+    - id: pet                     # 插件行 id（唯一）
+      name: 'dsh-pet'             # 模块名：解析到 lib/index.js
+      config:
+        size: 260                 # 宠物显示高度（px）—— 目前未传到 client
+        position: bottom-right    # 默认角落位置 —— 目前未传到 client

package/lib/client.js

@@ -0,0 +1,598 @@
+/**
+ * ============================================================================
+ * dsh-pet 浏览器半侧（browser half）—— 宠物插件的"前端"部分
+ * ============================================================================
+ *
+ * 【这个文件是什么】
+ *   本文件是宠物在浏览器里运行的代码。它：
+ *   1. 以官方规定的"客户端 bundle 形态"注册自己（window.__ModuleLoader__.load）
+ *   2. 把宠物组件挂到 DSH 界面的 `shell.overlay` 槽位（右下角的浮动层）
+ *   3. 负责宠物的所有视觉与交互：播放动画、随机行为、点击/拖拽、屏幕漫游
+ *
+ * 【为什么长这样（重要背景）】
+ *   DSH 的浏览器插件必须是一个特殊格式的 JS 文件：
+ *   - 用 `window.__ModuleLoader__.load({ id, factory })` 注册
+ *   - factory 接收一个同步的 `require`，用它拿 React 和 DSH 提供的模块
+ *   - **不能**自己打包 React（React 由 DSH 外壳提供，这里直接 require）
+ *   - CSS 以字符串形式内联注入 <style> 标签
+ *   官方插件（如 dsh-client-ui-goal）的 lib/client.js 就是这种形态，
+ *   本文件是手写等价实现，零构建依赖，方便直接阅读和修改。
+ *
+ * 【动画文件从哪来】
+ *   动画视频通过 /pet/thumb/<动画名>.webm 加载——这个路由由宿主半侧
+ *   （lib/index.js）提供，把 assets/thumb/ 下的 WebM 文件发给浏览器。
+ *
+ * ============================================================================
+ */
+window.__ModuleLoader__.load({
+	// 插件唯一 ID，必须与 package.json 里声明的一致
+	id: 'dsh-pet',
+
+	// factory：浏览器加载本 bundle 时执行，返回插件的导出
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+
+		// ---- 从 DSH 外壳拿 React（不能自己打包） ----
+		let react = require('react');
+		let { useEffect, useRef, useState } = react;
+		// jsx 是 React 18 的新 JSX 转换函数，这里起个别名 h 方便书写
+		let { jsx: h } = require('react/jsx-runtime');
+
+		// ============================================================================
+		// 内联 CSS —— 注入一次，官方插件标准做法
+		// ============================================================================
+		// 说明：
+		// - .dsh-pet-root       宠物的根容器，fixed 定位（相对视口），默认右下角
+		// - .dsh-pet-stage      内部舞台，承载两个 video 的层叠
+		// - .dsh-pet-video      动画视频；opacity 默认 0（隐藏），.is-front 时显示
+		// - 双 video 层叠：一个显示、一个预加载，切换时交叉淡入避免闪空白
+		const css = [
+			// 根容器：fixed 固定定位、层级 40（在界面之上）、整体点击穿透（不挡界面操作）、禁止选中
+			'.dsh-pet-root{position:fixed;z-index:40;pointer-events:none;user-select:none}',
+			// 右下角默认位置（right:24px 距右缘、bottom:0 贴底）
+			'.dsh-pet-root[data-corner="bottom-right"]{right:24px;bottom:0}',
+			// 左下角位置
+			'.dsh-pet-root[data-corner="bottom-left"]{left:24px;bottom:0}',
+			// 舞台：正方形（尺寸由 --dsh-pet-size 控制，默认 260px），本身不响应鼠标
+			'.dsh-pet-stage{position:relative;width:var(--dsh-pet-size,260px);height:var(--dsh-pet-size,260px);pointer-events:none}',
+			// 视频：铺满舞台、保持比例、可交互（pointer-events:auto 重新开启）、抓取光标
+			// opacity:0 初始隐藏，transition 做 180ms 淡入淡出
+			'.dsh-pet-video{position:absolute;inset:0;width:100%;height:100%;object-fit:contain;pointer-events:auto;cursor:grab;opacity:0;transition:opacity .18s ease;transform-origin:center}',
+			// 显示中的视频（is-front 类）
+			'.dsh-pet-video.is-front{opacity:1}',
+			// 按住时显示"抓取中"光标
+			'.dsh-pet-video:active{cursor:grabbing}',
+			// 朝向镜像：facing=right 时水平翻转（人物偏右）。镜像只作用 CSS，
+			// 不碰视频文件——这是"所有动画都能朝左/朝右"的实现关键
+			'.dsh-pet-root[data-facing="right"] .dsh-pet-video{transform:scaleX(-1)}',
+			// 无障碍：用户系统开启"减少动态效果"时关闭过渡动画
+			'@media (prefers-reduced-motion: reduce){.dsh-pet-video{transition:none}}',
+		].join('\n');
+		const cssTag = 'dsh-pet/style.css';
+		// 只在页面还没有这个 style 标签时才注入（防止热重载/重复挂载时重复）
+		if (typeof document !== 'undefined' && document.querySelector('style[data-plugin-css="' + cssTag + '"]') === null) {
+			const tag = document.createElement('style');
+			tag.dataset.plugin = 'dsh-pet';
+			tag.dataset.pluginCss = cssTag;
+			tag.textContent = css;
+			document.head.appendChild(tag);
+		}
+
+		// ============================================================================
+		// 动画目录（animation catalog）—— 所有动画名和参数的"事实来源"
+		// ============================================================================
+		// 对齐说明：thumb 视频是 360×360 画布，人物的"脚底"在 y=330 处。
+		// (360-330)/360 = 30/360 = 0.0833，与 1200 母版 (1200-1100)/1200 比例一致，
+		// 所以用这个比例做落地对齐，缩放后依然准确。
+		const CANVAS_H = 360; // thumb 画布高度
+		const FEET_Y = 330;   // thumb 画布上"脚底"的 y 坐标（人物站在 y=330 线上）
+
+		// 主体待机动画（唯一常驻、循环播放）
+		const IDLE = '待机呼吸休闲';
+		// 转向动画（东张西望本身内容就是"从偏左看到偏右"，播完翻转 facing）
+		const TURN = '东张西望';
+		// 随机动作池：纯字符串数组，全部等概率抽取。
+		// 含"打瞌睡被惊醒"（原独立闲置动画，已统一纳入）。
+		// 注意：原地漂浮踏步不在这里，它是移动动画（在 MOVES 里）。
+		const ACTS = [
+			'悠闲哼歌',
+			'超大伸懒腰',
+			'原地专心玩魔方',
+			'原地敲击桌面互动',
+			'原地重力下蹲压缩',
+			'哈欠连天',
+			'原地小憩沉眠',
+			'原地蹲下玩玩具汽车',
+			'鲸鱼吐泡泡特效',
+			'女仆屈膝礼仪',
+			'被吓一跳（炸毛）',
+			'原地跳跃抓碎头顶物品',
+			'小幅度原地 360 度旋转展示',
+			'偷吃零食被抓住',
+			'玩游戏气急败坏',
+			'用鲸鱼尾巴拍打地面',
+			'打瞌睡被惊醒', // 原独立闲置动画，已并入
+		];
+		// 点击回应动画池（3 选 1）
+		const CLICKS = ['点击回应 - 开心跃动', '点击回应 - 害羞惊讶', '点击回应 - 傲娇生气（侧身展示）'];
+		// 拖拽动画（按住时播放）
+		const DRAG = '被鼠标拖拽悬空反馈';
+		// 移动动画池：动画只提供"走路姿态"，实际位置移动由代码（rAF）驱动
+		const MOVES = ['螃蟹走路', '原地漂浮踏步'];
+		// 移动参数：
+		const MOVE_MIN_PX = 60;  // 每次移动的最短距离（px）
+		const MOVE_MAX_PX = 240; // 每次移动的最长距离（px）
+		const MOVE_MARGIN = 20;  // 屏幕边缘安全边距（px），防止宠物贴边/出屏
+		const MOVE_LEAD_SEC = 2; // 动画开头 2s 是"准备动作"，位置不动
+		const MOVE_TAIL_SEC = 2; // 动画结尾 2s 是"收尾动作"，位置不动
+
+		// 生成 [min, max) 区间内的随机整数
+		const randomBetween = (min, max) => Math.floor(min + Math.random() * (max - min));
+		// 从字符串池里等概率随机抽一个；exclude 排除某个名字（避免连续重复）
+		const pick = (pool, exclude) => {
+			const entries = exclude ? pool.filter((n) => n !== exclude) : pool;
+			return entries[Math.floor(Math.random() * entries.length)];
+		};
+
+		// ============================================================================
+		// Pet 组件 —— 宠物本体
+		// ============================================================================
+		/**
+		 * 核心组件。职责：
+		 * 1. 渲染"双缓冲"的一对 <video>（A/B 交替显示），切换动画时交叉淡入，永无空白帧
+		 * 2. 状态机：待机 →（定时器随机）→ 转向/移动/动作；点击/拖拽可打断
+		 * 3. 朝向（facing）渲染：right 时 CSS 镜像
+		 *
+		 * 参数 config：来自 patch 配置。当前 DSH 客户端配置管线尚未打通，
+		 * 实际收到的是空对象，所以下面全部用 || 默认值兜底。
+		 */
+		function Pet({ config }) {
+			// ---- 从 config 读取参数（当前走默认值） ----
+			const size = (config && config.size) || 260;             // 显示尺寸（px）
+			const corner = (config && config.position) || 'bottom-right'; // 默认角落
+
+			// ---- React 状态 ----
+			const [anim, setAnim] = useState(IDLE);   // 当前动画名
+			const [once, setOnce] = useState(true);   // 是否一次性播放——链式模型全部一次性
+			const [facing, setFacing] = useState('left'); // 朝向：left | right
+			const [dragging, setDragging] = useState(false); // 是否正在拖拽
+			// 自定义位置（拖拽/移动后宠物停留的视口坐标）；null = 回到默认角落
+			const [customPos, setCustomPos] = useState(null);
+			// 播放序号：每次切换 +1。即使连续选中同一个动画（如待机播完又选待机），
+			// seq 变化也能保证 switchTo 重新执行、视频重新播放（否则 anim 没变 React 不重渲染）。
+			const [seq, setSeq] = useState(0);
+			// ---- DOM 引用 ----
+			const rootRef = useRef(null);  // 根容器（fixed 定位）
+			const stageRef = useRef(null); // 内部舞台（落地对齐）
+			const videoARef = useRef(null); // 视频 A
+			const videoBRef = useRef(null); // 视频 B
+			// ---- 双缓冲/竞态相关 ref ----
+			const frontRef = useRef(0);  // 当前显示的是哪个视频：0=A, 1=B
+			const pendingRef = useRef(null); // 正在加载中的 {anim, once, gen}
+			const genRef = useRef(0);    // 切换代数：每次切换 +1，用于识别"过期回调"
+			// ---- 交互相关 ref ----
+			const dragRef = useRef({ active: false, dragging: false, sx: 0, sy: 0 }); // 拖拽状态
+			const justDraggedRef = useRef(false); // 刚拖拽完（用于抑制拖拽后的误点击）
+			const animRef = useRef(IDLE); // 动画名镜像（供异步回调读当前值）
+			animRef.current = anim;
+
+			// ============================================================================
+			// 双缓冲切换（switchTo）—— 核心播放逻辑
+			// ============================================================================
+			// 思路：两个 video 层叠。切换动画时：
+			//   1. 把目标动画 src 设到"非当前显示"的那个 video 上
+			//   2. 等它 loadeddata（数据加载完成）
+			//   3. 新 video 淡入（加 is-front），旧 video 淡出（去 is-front）
+			//   4. frontRef 翻转，下次切换用另一个
+			// 这样切换时旧画面一直显示到新画面就绪，永远不会闪空白。
+			//
+			// 竞态防护（重要）：快速连点/连续切换时，可能前一个动画还没加载完
+			// 就又要切下一个。每个切换有一个递增的"代数" gen，loadeddata 回调
+			// 执行时检查自己是否还是最新代——不是就放弃（避免两个 video 都被
+			// 移除 is-front 而全部透明、宠物消失）。
+			const switchTo = (next, nextOnce) => {
+				// 如果目标动画已经在加载中，直接跳过（避免重复加载）
+				const pending = pendingRef.current;
+				if (pending && pending.anim === next && pending.once === nextOnce) return;
+				const gen = ++genRef.current; // 本次切换的代数
+				pendingRef.current = { anim: next, once: nextOnce, gen };
+
+				// 目标 video = 当前"非显示"的那个（front 是 A 就用 B，反之用 A）
+				const target = frontRef.current === 0 ? videoBRef : videoARef;
+				const el = target.current;
+				if (!el) return;
+				// 设置视频属性并开始加载
+				el.src = '/pet/thumb/' + encodeURIComponent(next) + '.webm';
+				el.loop = !nextOnce;           // 一次性动画不循环
+				el.muted = true;               // 静音（动画无声音）
+				el.autoplay = true;            // 自动播放
+				el.playsInline = true;         // 行内播放（移动端不弹全屏）
+				el.onended = nextOnce ? handleEnded : undefined; // 一次性动画播完 → 回待机
+				el.load();
+
+				// 数据加载完成后的回调
+				const onReady = () => {
+					el.removeEventListener('loadeddata', onReady);
+					// 过期检查：如果期间又有更新的切换，本回调作废
+					if (pendingRef.current?.gen !== gen) return;
+					// 交换前后台：新 video 加 is-front（淡入），旧 video 移除（淡出）
+					const old = frontRef.current === 0 ? videoARef : videoBRef;
+					el.classList.add('is-front');
+					// old !== el 守卫：防止把自己刚加的 is-front 又移除
+					if (old.current && old.current !== el) old.current.classList.remove('is-front');
+					frontRef.current = frontRef.current === 0 ? 1 : 0;
+					pendingRef.current = null;
+					el.play().catch(() => {}); // 开始播放（捕获自动播放策略异常）
+					// 如果这是"计划中的移动"的动画，现在动画就绪了，
+					// 开始驱动位置移动（见 startMoveDrive）
+					if (pendingMoveRef.current) startMoveDrive(el);
+				};
+				el.addEventListener('loadeddata', onReady);
+				// 如果视频已缓存就绪（readyState>=2），立即触发回调
+				if (el.readyState >= 2) onReady();
+			};
+
+			// ============================================================================
+			// 随机事件定时器 —— 待机时的"自主行为"
+			// ---- 状态驱动播放：anim/once/seq 一变就切换视频 ----
+			// seq 参与依赖：即使 anim/once 没变（连续选中同一动画），seq 变化也强制重播。
+			useEffect(() => {
+				switchTo(anim, once);
+			}, [anim, once, seq]);
+
+			// ---- 组件卸载时清理移动 rAF ----
+			useEffect(() => () => { stopMove(); }, []);
+
+			// ---- 窗口尺寸变化：重算比例位置（触发重渲染，宠物保持相对窗口位置） ----
+			useEffect(() => {
+				const onResize = () => {
+					// 有自定义位置时，用同值 setCustomPos 触发重渲染；
+					// 渲染逻辑会用新窗口尺寸 × 比例重算坐标。
+					setCustomPos((prev) => (prev ? { ...prev } : prev));
+				};
+				window.addEventListener('resize', onResize);
+				return () => window.removeEventListener('resize', onResize);
+			}, []);
+
+			// ============================================================================
+			// 动画链：每次动画播完 → 按概率选下一个
+			// ============================================================================
+			// 链式模型（无常驻待机、无定时器）：
+			//   每个动画（含待机呼吸休闲）都是一次性播放，播完 handleEnded 触发，
+			//   按概率选下一个：30% 待机 / 10% 转向 / 40% 动作 / 20% 移动。
+			//   点击/拖拽打断的动画播完后先回待机（作为缓冲），待机播完再进随机链。
+			const pickNext = () => {
+				const roll = Math.random();
+				if (roll < 0.3) {
+					// 30% 待机：待机呼吸休闲（也是一次性，播完再选）
+					setAnim(IDLE);
+				} else if (roll < 0.4) {
+					// 10% 转向：东张西望，播完 handleEnded 里翻转 facing
+					setAnim(TURN);
+				} else if (roll < 0.8) {
+					// 40% 随机动作（等概率 + 去重）
+					setAnim(pick(ACTS, animRef.current));
+				} else {
+					// 20% 尝试移动：tryMove 先检查空间，不够就回退随机动作
+					if (!tryMove()) {
+						setAnim(pick(ACTS, animRef.current));
+					}
+				}
+				setOnce(true);        // 链式模型全部一次性
+				setSeq((s) => s + 1); // 保证即使 anim 没变也重新播放
+			};
+
+			// 一次性动画播完的回调：决定下一个动画。
+			// 拖拽中途不响应（让拖拽动画继续）。
+			const handleEnded = () => {
+				if (dragRef.current.active) return; // 拖拽中：不打断
+				if (animRef.current === TURN) {
+					// 东张西望播完 → 翻转朝向
+					setFacing((f) => (f === 'left' ? 'right' : 'left'));
+				}
+				// 点击回应/拖拽动画（用户打断触发的）播完 → 先回待机缓冲
+				if (animRef.current === DRAG || CLICKS.includes(animRef.current)) {
+					setAnim(IDLE);
+					setOnce(true);
+					setSeq((s) => s + 1);
+					return;
+				}
+				// 自主链动画播完 → 按概率选下一个
+				pickNext();
+			};
+
+			// ============================================================================
+			// 移动系统 —— 动画提供姿态，代码驱动位置
+			// ============================================================================
+			const moveRef = useRef(null);        // 移动中的 rAF id
+			const moveTokenRef = useRef(0);      // 移动令牌：每次取消 +1 使旧回调失效
+			const pendingMoveRef = useRef(null); // 计划中的移动 {startX,startY,target,dir,total}
+			const customPosRef = useRef(null);   // customPos 的 ref 镜像（供异步读取）
+			customPosRef.current = customPos;
+
+			// 当前宠物中心 x（视口坐标）：
+			// customPos 存"相对窗口比例"（rx = centerX/innerWidth），渲染时乘当前窗口尺寸。
+			// 窗口 resize 后按新尺寸重算 → 宠物保持相对位置。
+			const currentCenterX = () => {
+				const cp = customPosRef.current;
+				if (cp) return cp.rx * window.innerWidth;
+				const rootEl = rootRef.current;
+				if (rootEl) return rootEl.getBoundingClientRect().left + size / 2;
+				return window.innerWidth - 24 - size / 2;
+			};
+			// 当前宠物中心 y（视口坐标）
+			const currentCenterY = () => {
+				const cp = customPosRef.current;
+				if (cp) return cp.ry * window.innerHeight;
+				const rootEl = rootRef.current;
+				if (rootEl) return rootEl.getBoundingClientRect().top + size / 2;
+				return window.innerHeight - 20 - size / 2;
+			};
+
+			/**
+			 * 启动"位置驱动"循环。只在移动动画真正加载完成并开始播放后调用
+			 * （在 switchTo 的 onReady 里），保证人物姿态先出现在屏幕上、位置才开始动。
+			 *
+			 * 关键设计：位置跟随动画的播放时钟（video.currentTime）——
+			 *   动画开头 MOVE_LEAD_SEC(2s) 是准备动作：位置不动
+			 *   中间窗口：位置按 (t-LEAD)/window 比例从起点走向终点
+			 *   结尾 MOVE_TAIL_SEC(2s) 是收尾动作：位置已到终点不动
+			 * 这样踏步节奏和位移完全同步，不会有"滑步"。
+			 */
+			const startMoveDrive = (el) => {
+				const pm = pendingMoveRef.current;
+				if (!pm || moveRef.current !== null) return; // 没有计划或已在移动
+				pendingMoveRef.current = null;
+				const { startRatio, startYRatio, targetRatio, dir, totalRatio } = pm;
+				// 动画时长驱动节奏（10.09s），取不到时兜底
+				const duration = Number.isFinite(el.duration) && el.duration > 0 ? el.duration : 10.09;
+				// 真正移动的窗口 = 总时长 - 前后 2s（至少 0.1s 防除零）
+				// 命名注意：不能叫 window——会遮蔽全局 window，导致 window.innerWidth 变 undefined（历史 bug）
+				const travelWindow = Math.max(0.1, duration - MOVE_LEAD_SEC - MOVE_TAIL_SEC);
+				const token = ++moveTokenRef.current;
+				const step = () => {
+					if (moveTokenRef.current !== token) return;
+					const t = el.currentTime || 0; // 动画当前播放进度（秒）
+					const rootEl = rootRef.current;
+					if (rootEl) {
+						// 每帧用"当前窗口尺寸 × 比例"算实际坐标——resize 后自动跟随
+						const W = window.innerWidth;
+						const H = window.innerHeight;
+						let ratioX;
+						if (t <= MOVE_LEAD_SEC) {
+							ratioX = startRatio; // 准备动作：原地
+						} else if (t >= duration - MOVE_TAIL_SEC) {
+							ratioX = targetRatio; // 收尾动作：已到终点
+						} else {
+							// 移动窗口：按进度插值（比例制）
+							const progress = (t - MOVE_LEAD_SEC) / travelWindow;
+							ratioX = startRatio + dir * totalRatio * progress;
+						}
+						const px = ratioX * W;
+						const py = startYRatio * H;
+						// 直接改 DOM style（不触发 React 重渲染，保证 60fps 平滑）
+						rootEl.style.left = (px - size / 2) + 'px';
+						rootEl.style.top = (py - size / 2) + 'px';
+						rootEl.style.right = 'auto';
+						rootEl.style.bottom = 'auto';
+					}
+					if (t < duration - MOVE_TAIL_SEC) {
+						moveRef.current = requestAnimationFrame(step); // 继续下一帧
+					} else {
+						// 到位：提交终点位置（存相对窗口比例），让动画自然播完最后 2s 收尾——
+						// 它是一次性动画，ended 事件会带我们回待机
+						moveRef.current = null;
+						setCustomPos({ rx: targetRatio, ry: startYRatio });
+					}
+				};
+				moveRef.current = requestAnimationFrame(step);
+			};
+
+			/**
+			 * 尝试计划一次移动（朝当前 facing 方向）。
+			 * 只做两件事：检查空间是否够 + 记录计划；真正的位置驱动
+			 * 等移动动画就绪后由 switchTo 的 onReady 触发。
+			 * @returns {boolean} true=移动已计划；false=空间不够（调用方回退随机动作）
+			 */
+			const tryMove = () => {
+				if (moveRef.current !== null || pendingMoveRef.current) return true; // 已在移动/已计划
+				const dir = facingRef.current === 'right' ? 1 : -1; // 朝右=+1，朝左=-1
+				const W = window.innerWidth;
+				const cx = currentCenterX();
+				const distance = randomBetween(MOVE_MIN_PX, MOVE_MAX_PX);
+				const target = cx + dir * distance;
+				// 【播放前检查一次距离】目标点必须在屏幕安全边距内，否则不移动
+				const leftBound = MOVE_MARGIN + size / 2;
+				const rightBound = W - MOVE_MARGIN - size / 2;
+				if (target < leftBound || target > rightBound) return false; // 空间不够
+				// 记录计划（存"比例"而非绝对坐标，resize 后仍正确）：
+				// 起点比例、目标比例、Y 比例、方向、总距离比例
+				pendingMoveRef.current = {
+					startRatio: cx / W,
+					startYRatio: currentCenterY() / window.innerHeight,
+					targetRatio: target / W,
+					dir,
+					totalRatio: Math.abs(target - cx) / W,
+				};
+				// 移动动画一次性播放（10s），播完 ended 触发 handleEnded → 进入动画链
+				setOnce(true);
+				setAnim(pick(MOVES));
+				return true;
+			};
+			// 停止移动（点击/拖拽打断时调用）：取消计划 + 使 rAF 失效 + 取消帧
+			const stopMove = () => {
+				pendingMoveRef.current = null;
+				moveTokenRef.current++;
+				if (moveRef.current !== null) {
+					cancelAnimationFrame(moveRef.current);
+					moveRef.current = null;
+				}
+			};
+
+			// facing 的 ref 镜像（tryMove/定时器读取当前朝向）
+			const facingRef = useRef(facing);
+			facingRef.current = facing;
+
+			// ============================================================================
+			// 点击 vs 拖拽的区分
+			// ============================================================================
+			// 问题：按下+松开可能是一次"点击"，也可能是一次"拖拽"。
+			// 方案：pointerdown 只记录起点；pointermove 超过 5px 才判定为拖拽
+			// （播放拖拽动画并跟手）；松手时若没拖过，click 事件正常触发点击回应。
+			const DRAG_THRESHOLD = 5; // 拖拽判定阈值（px）
+
+			// 按下：只记录，不立即切动画
+			const handlePointerDown = (e) => {
+				stopMove(); // 用户交互打断正在进行的移动
+				e.currentTarget.setPointerCapture(e.pointerId); // 捕获指针（拖出元素也能收到 move）
+				dragRef.current = { active: true, dragging: false, sx: e.clientX, sy: e.clientY };
+			};
+			// 移动：超过阈值才进入拖拽模式
+			const handlePointerMove = (e) => {
+				const d = dragRef.current;
+				if (!d.active) return;
+				const dx = e.clientX - d.sx;
+				const dy = e.clientY - d.sy;
+				if (!d.dragging) {
+					// 还没超过阈值：仍是"点击候选"，不动
+					if (Math.hypot(dx, dy) < DRAG_THRESHOLD) return;
+					// 进入拖拽：播放拖拽动画
+					d.dragging = true;
+					setDragging(true);
+					setOnce(true);
+					setAnim(DRAG);
+				}
+				// 跟手：直接改 root 的 style（不触发 React 重渲染 → 60fps 平滑）
+				const rootEl = rootRef.current;
+				if (rootEl) {
+					rootEl.style.left = (e.clientX - size / 2) + 'px';
+					rootEl.style.top = (e.clientY - size / 2) + 'px';
+					rootEl.style.right = 'auto';
+					rootEl.style.bottom = 'auto';
+				}
+				const stageEl = stageRef.current;
+				if (stageEl) stageEl.style.transform = 'none'; // 拖拽时去掉落地偏移
+			};
+			// 松手：真拖拽则停留 + 回待机；没拖过则等 click 事件
+			const handlePointerUp = (e) => {
+				const d = dragRef.current;
+				const wasDragging = d.dragging;
+				d.active = false;
+				d.dragging = false;
+				if (wasDragging) {
+					// 抑制拖拽结束后的"幽灵点击"（浏览器在拖完也会发 click）
+					justDraggedRef.current = true;
+					setTimeout(() => { justDraggedRef.current = false; }, 100);
+					setDragging(false);
+					// 停在松手处（存相对窗口比例，窗口变化时位置跟随）
+					setCustomPos({
+						rx: e.clientX / window.innerWidth,
+						ry: e.clientY / window.innerHeight,
+					});
+					const stageEl = stageRef.current;
+					if (stageEl) stageEl.style.transform = 'translateY(' + bottomPad + 'px)'; // 恢复落地对齐
+					setAnim(IDLE);
+					setOnce(false);
+				}
+				// 没拖过：交给 handleClick
+			};
+
+			// ---- 点击回应（仅真点击触发，拖拽后的 click 被忽略） ----
+			const handleClick = () => {
+				const d = dragRef.current;
+				if (d.active || d.dragging || justDraggedRef.current) return; // 拖拽中/刚拖完：忽略
+				if (once && animRef.current !== IDLE) return; // 正在播一次性动画：不打断
+				stopMove(); // 点击打断移动
+				setOnce(true);
+				setAnim(pick(CLICKS)); // 随机一个点击回应动画
+			};
+
+			// ============================================================================
+			// 渲染
+			// ============================================================================
+			// 落地对齐：视频是 360 画布、脚在 y=330，脚底距画布底 30px。
+			// bottomPad = size × (360-330)/360，把舞台向下平移这么多，
+			// 让"脚"正好落在视口底线上（宠物看起来站在地上而不是悬空）。
+			const bottomPad = (size * (CANVAS_H - FEET_Y)) / CANVAS_H;
+			// 舞台样式：拖拽中无偏移；平时 translateY(bottomPad) 落地
+			const stageStyle = dragging
+				? { transform: 'none' }
+				: { transform: 'translateY(' + bottomPad + 'px)' };
+
+			// 根容器样式：有自定义位置（拖过/走过）就按"相对窗口比例 × 当前窗口尺寸"定位；
+			// 否则不设（走 CSS 的 data-corner 默认角落，天然响应式）。
+			// resize 后重渲染会用新尺寸重算 → 宠物保持相对位置；
+			// 同时钳制到窗口内，防止窗口缩小到宠物放不下时跑出屏幕。
+			const rootStyle = customPos
+				? (() => {
+					const half = size / 2;
+					const rx = customPos.rx;
+					const ry = customPos.ry;
+					const left = Math.min(Math.max(rx * window.innerWidth - half, 0), window.innerWidth - size);
+					const top = Math.min(Math.max(ry * window.innerHeight - half, 0), window.innerHeight - size);
+					return { left: left + 'px', top: top + 'px', right: 'auto', bottom: 'auto' };
+				})()
+				: {};
+
+			// 两个 video 共用的 props（事件绑定 + 播放属性）
+			const commonVideoProps = {
+				muted: true,
+				playsInline: true,
+				autoPlay: true,
+				onClick: handleClick,
+				onPointerDown: handlePointerDown,
+				onPointerMove: handlePointerMove,
+				onPointerUp: handlePointerUp,
+				onPointerCancel: handlePointerUp,
+				title: 'dsh-pet',
+			};
+
+			// 渲染树：root > stage > [video A, video B]
+			// A 初始带 is-front（显示），B 隐藏待命
+			return h('div', {
+				ref: rootRef,
+				className: 'dsh-pet-root',
+				'data-corner': corner,   // CSS 决定默认角落
+				'data-facing': facing,   // CSS 决定是否镜像
+				style: Object.assign({ '--dsh-pet-size': size + 'px' }, rootStyle),
+				children: h('div', {
+					ref: stageRef,
+					className: 'dsh-pet-stage',
+					style: stageStyle,
+					children: [
+						h('video', Object.assign({}, commonVideoProps, { ref: videoARef, className: 'dsh-pet-video is-front' })),
+						h('video', Object.assign({}, commonVideoProps, { ref: videoBRef, className: 'dsh-pet-video' })),
+					],
+				}),
+			});
+		}
+
+		// ============================================================================
+		// 插件主体（Cordis 插件三件套：name / inject / apply）
+		// ============================================================================
+		const name = 'pet';        // 插件行 id（与 cordis.patch.yml 一致）
+		const inject = ['slots'];  // 需要注入的服务：slots（槽位注册表）
+
+		// apply：插件被激活时调用
+		function apply(ctx, config) {
+			// 官方"叠加式"注册模式：
+			// slots.inject 等 shell.overlay 槽位被声明后，再注册我们的条目。
+			// 用 generator + yield 形式（与官方 dsh-client-ui-directory-picker-native 一致），
+			// 这样不会替换其他条目，而是以 id='pet' 叠加进列表槽。
+			ctx.slots.inject('shell.overlay', function* () {
+				yield ctx.slots.register({
+					name: 'shell.overlay',
+					id: 'pet',       // 列表槽的条目 id（唯一）
+					order: 1000,     // 排序（大 = 靠后渲染）
+				}, (ownerProps) => h(Pet, { config, ...ownerProps }));
+			});
+		}
+
+		// 导出插件三件套（Cordis Loader 需要）
+		exports.apply = apply;
+		exports.inject = inject;
+		exports.name = name;
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -0,0 +1,135 @@
+/**
+ * ============================================================================
+ * dsh-pet 宿主半侧（host half）—— 宠物插件的"后端"部分
+ * ============================================================================
+ *
+ * 【这个文件是什么】
+ *   本文件运行在 DSH 的 Node 服务端（不是浏览器）。它的唯一职责是：
+ *   在 DSH 的 Web 服务器上注册一个 `/pet/` 前缀的 HTTP 路由，
+ *   把插件包里的动画 WebM 文件流式返回给浏览器。
+ *
+ * 【为什么需要它】
+ *   DSH 的 `/plugins/` 路由只服务"客户端 JS bundle"，不服务视频等静态资源。
+ *   所以浏览器半侧（lib/client.js）要播放动画，必须有一个专门的路由来取文件。
+ *   这正是 DSH 官方提供的扩展点：`ctx.webServer.register()`。
+ *
+ * 【路由结构】
+ *   /pet/thumb/<动画名>.webm   → 读插件包内 assets/thumb/（360×360 播放变体）
+ *   /pet/full/<动画名>.webm    → 读 $DSH_HOME/pet-assets/（原始 1200×1200，需先下载）
+ *
+ * 【安全性】
+ *   路径做了"防穿越"校验（resolveAsset）：请求里的路径规范化后必须仍在
+ *   assets 根目录内，否则返回 400。防止 /pet/../../etc/passwd 这类攻击。
+ *
+ * ============================================================================
+ */
+import { createReadStream, existsSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { join, normalize, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// 官方 API：解析 DSH 主目录（$DSH_HOME，默认 ~/.dsh）——full 资源存放位置
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+
+// 插件行 id（与 cordis.patch.yml 一致）
+const name = 'pet';
+/** 需要注入的服务：webServer（Web 服务器路由注册表） */
+const inject = ['webServer'];
+
+/** 本包目录（src 和安装后都适用——import.meta.url 指向 lib/，上一级即包根） */
+const PACKAGE_ROOT = resolve(fileURLToPath(new URL('..', import.meta.url)));
+
+/** 路由前缀：/pet/thumb/<name>.webm、/pet/full/<name>.webm */
+const ROUTE_PREFIX = '/pet';
+
+/** 不同扩展名对应的 Content-Type 映射 */
+const MIME = {
+  '.webm': 'video/webm',
+  '.mp4': 'video/mp4',
+  '.png': 'image/png',
+  '.json': 'application/json; charset=utf-8',
+};
+
+/**
+ * 规范化并校验请求路径，确保它在 assets 根目录内（防路径穿越）。
+ * @param root - assets 根目录（绝对路径）
+ * @param rel  - 解码后的、路由前缀之后的路径片段
+ * @returns 规范化后的绝对文件路径；非法（穿越）时返回 undefined
+ */
+function resolveAsset(root, rel) {
+  if (rel.length === 0) return undefined;
+  // join + normalize 得到规范化路径（处理 ..、./、多余分隔符）
+  const candidate = normalize(join(root, rel));
+  // 根目录带分隔符的前缀，用于判断候选路径是否真的在根目录内
+  const rootWithSep = root.endsWith(sep) ? root : root + sep;
+  // 候选路径必须等于根目录或以"根目录/"开头，否则是穿越（如 ../lib/index.js）
+  if (candidate !== root && !candidate.startsWith(rootWithSep)) return undefined;
+  return candidate;
+}
+
+/**
+ * 宿主插件主体：注册 `/pet` 前缀路由。
+ * @param ctx    - 插件上下文；ctx.webServer 是 Web 服务器服务
+ * @param config - 本行的配置（来自 patch 树）
+ */
+function apply(ctx, config) {
+  // 两个资源根：
+  // - thumbRoot：插件包内 assets/thumb/（360×360 播放变体，随包发布，一定存在）
+  // - fullRoot ：$DSH_HOME/pet-assets/（原始母版，需手动下载，可能不存在）
+  const thumbRoot = join(PACKAGE_ROOT, 'assets', 'thumb');
+  const fullRoot = config.fullRoot ?? join(resolveDshHome(), 'pet-assets');
+
+  // ctx.effect 包裹：插件卸载时自动注销路由（官方生命周期管理）
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'prefix',     // 前缀路由：匹配 /pet 以及 /pet/xxx
+    path: ROUTE_PREFIX,
+    handler: async (req, res) => {
+      const url = new URL(req.url ?? '/', 'http://localhost');
+      // 去掉 /pet/ 前缀并 URL 解码（中文文件名是编码后的）
+      const rest = decodeURIComponent(url.pathname.slice(ROUTE_PREFIX.length + 1));
+      // 第一段是 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;
+      }
+      // 文件不存在：full 未下载 vs thumb 缺失给不同提示
+      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;
+      }
+      // 按扩展名定 Content-Type，附 Content-Length（浏览器可显示进度）
+      const ext = file.slice(file.lastIndexOf('.')).toLowerCase();
+      const contentType = MIME[ext] ?? 'application/octet-stream';
+      const { size } = await stat(file);
+      res.writeHead(200, {
+        'content-type': contentType,
+        'content-length': size,
+        // 缓存 1 小时：动画是静态文件，重复播放直接命中缓存
+        'cache-control': 'public, max-age=3600',
+      });
+      // 流式返回（大文件不占内存）
+      const stream = createReadStream(file);
+      stream.on('error', () => {
+        res.destroy();
+      });
+      stream.pipe(res);
+    },
+  }), 'dsh-pet: /pet asset route');
+}
+
+// 导出插件三件套（Cordis Loader 需要）
+export { apply, inject, name };

package/lib/types/client/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ============================================================================
+ * dsh-pet 浏览器半侧的类型声明（TypeScript）
+ * ============================================================================
+ *
+ * 【用途】
+ *   给 lib/client.js（浏览器半侧）提供类型信息。纯类型文件，不影响运行时。
+ *
+ * 【对应实现】
+ *   lib/client.js —— 注册宠物到官方 `shell.overlay` 列表槽，播放动画。
+ *
+ * 【注意】
+ *   当前 DSH 客户端配置管线尚未打通，apply 实际收到的 config 是空对象，
+ *   下面这些配置项已按默认值实现在代码里，但**尚未真正可覆盖**。
+ *
+ * ============================================================================
+ * @module dsh-pet/client
+ */
+import type { Context } from '@deepseek-ai/dsh-client-runtime';
+
+/** Cordis 插件名（loader 诊断用），与 lib/client.js 的 name 一致 */
+export declare const name = 'pet';
+/** 需要注入的服务列表（slots 槽位注册表），与 lib/client.js 的 inject 一致 */
+export declare const inject: string[];
+
+/** 插件配置：显示调参 */
+export interface Config {
+    /** 宠物显示高度（px）。默认 260。 */
+    size?: number;
+    /** 默认角落：'bottom-right' | 'bottom-left'。默认 'bottom-right'。 */
+    position?: 'bottom-right' | 'bottom-left';
+}
+
+/**
+ * 客户端插件主体：把宠物注册进 `shell.overlay`。
+ * @param ctx    - 客户端根上下文（ctx.slots 提供槽位注册）
+ * @param config - 本行配置（来自 patch 树；当前实际为空对象）
+ */
+export declare function apply(ctx: Context, config: Config): void;

package/lib/types/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * ============================================================================
+ * dsh-pet 宿主半侧的类型声明（TypeScript）
+ * ============================================================================
+ *
+ * 【用途】
+ *   给 lib/index.js（宿主半侧）提供类型信息，让 TypeScript 用户/编辑器
+ *   在 import 本包时获得智能提示和类型检查。纯类型文件，不影响运行时。
+ *
+ * 【对应实现】
+ *   lib/index.js —— 注册 /pet/ 前缀路由，向浏览器提供动画 WebM 文件。
+ *
+ * ============================================================================
+ * @module dsh-pet
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+
+/** Cordis 插件名（loader 诊断用），与 lib/index.js 的 name 一致 */
+export declare const name = 'pet';
+/** 需要注入的服务列表（webServer），与 lib/index.js 的 inject 一致 */
+export declare const inject: string[];
+
+/** 插件配置：/pet 路由的资源根目录 */
+export interface Config {
+    /**
+     * "full"（原始 1200×1200）资源的根目录，当部署方下载了原始母版时使用。
+     * 默认 `$DSH_HOME/pet-assets`。
+     */
+    fullRoot?: string;
+}
+
+/**
+ * 宿主插件主体：注册 /pet 前缀路由。
+ * @param ctx    - 插件上下文；ctx.webServer 是 Web 服务器服务
+ * @param config - 本行配置（来自 patch 树）
+ */
+export declare function apply(ctx: Context, config: Config): void;
+
+export type { WebRoute };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "dsh-pet",
+  "version": "0.1.0",
+  "description": "A floating desktop pet for the DeepSeek Harness Web UI: idle breathing, occasional direction turns, random actions, and screen wandering.",
+
+  "_comment": [
+    "=============== dsh-pet 包清单说明 ===============",
+    "type: module —— 本包是 ESM",
+    "main: lib/index.js —— 宿主半侧入口（Cordis 插件：name/inject/apply）",
+    "exports['./client'] —— 浏览器半侧入口，DSH 模块系统按它提供 /plugins/dsh-pet/client.js",
+    "dsh.bundle.patch —— 声明本包是 bundle，patch 文件是 cordis.patch.yml（安装后自动进层栈）",
+    "dsh.client —— 声明浏览器半侧的注入依赖和平台（web）",
+    "files —— npm publish 只发这些目录/文件（assets/thumb 播放资源；assets/preview 的 GIF 仅 README 展示、不入包）",
+    "scripts.encode:thumbs —— 转码管线（step03 母版 → assets/thumb 360×360）",
+    "scripts.prepack —— 发布前自动健康检查",
+    "peerDependencies —— 运行时由宿主（DSH）提供的模块，本包不打包它们",
+    "================================================"
+  ],
+
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "assets/thumb",
+    "cordis.patch.yml"
+  ],
+  "scripts": {
+    "prepack": "node scripts/prepack-check.js"
+  },
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "platform": "web"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "react": "^18.2.0"
+  }
+}