dsh-alk-pet 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 dsh-alk-pet contributors
+
+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.
+
+The character animation frames under assets/animations are derived from
+PC2005-cloud/dsh-pet and licensed under MIT; see assets/LICENSE.txt for the
+original copyright notice.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# DSH ALK Pet
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+让 DeepSeek Harness 的任务状态变成一只始终陪在桌面上的小宠物。
+
+DSH ALK Pet 是一个**非官方** DeepSeek Harness（DSH）插件：在 macOS 和 Windows 上优先使用跨应用置顶的原生透明悬浮窗；原生窗口不可用时，自动回退到 DSH 页面右下角。它不只是播放动画，还能把多个会话、子 Agent、待办步骤和工具动作汇总成一块可视化任务看板。
+
+## 特色功能
+
+- **用动画展示真实任务状态**：根据 DSH 会话事件切换待机、思考、工作、等待确认、完成和错误动作，约 12 帧/秒播放。
+- **多任务一眼可见**：同时运行多个顶层会话时，以状态圆点展示每个任务；每行最多 12 个，超过后自动换行，并自动轮播当前任务。
+- **鼠标悬停即可切换任务**：移入圆点立即查看对应任务，悬停期间暂停轮播，移开约 2 秒后恢复。
+- **了解 Agent 正在做什么**：气泡第一行显示顶层会话标题，第二行显示当前待办、执行步骤或工具动作及其关键参数。
+- **正确归并子 Agent**：子 Agent 的活动会归入所属顶层会话，不会产生难以辨认的额外任务项。
+- **结果不会一闪而过**：完成或失败状态会保留，直到你打开相应会话并查看结果。
+- **原生悬浮与网页回退**：macOS、Windows 使用可拖动的原生置顶窗口；启动失败时自动切换为页面内宠物。
+- **兼顾无障碍与省电**：可关闭气泡、调整尺寸，或启用静态单帧的“减少动态效果”模式。
+
+## 预览
+
+![多任务与状态圆点](docs/screenshots/multi-task.png)
+
+![任务超过 12 个时自动换行](docs/screenshots/multi-row.png)
+
+## 使用方法
+
+### 1. 安装插件
+
+#### 从插件源安装（推荐）
+
+1. 打开 DeepSeek Harness 的插件页面，进入插件源或插件搜索。
+2. 搜索 **`dsh-alk-pet`**，核对项目仓库为 [penguinbing/dsh-alk-pet](https://github.com/penguinbing/dsh-alk-pet)。
+3. 安装插件并确认已启用，然后按界面提示重启。
+
+如果暂时搜不到，请刷新插件源后重试；也可以使用下面的 GitHub 本地安装方式。
+
+#### 从 GitHub 安装（备用）
+
+先将仓库下载到本机：
+
+```sh
+git clone https://github.com/penguinbing/dsh-alk-pet.git
+```
+
+在 DSH 插件页面选择“添加插件”，填写克隆后 `dsh-alk-pet` 目录的**绝对路径**，安装并启用。请保留该目录，不要将其放在会被自动清理的临时文件夹中。
+
+也可以先退出正在运行的 DSH，再使用 `dsh` 命令安装（将示例路径替换为实际路径）：
+
+```sh
+# 桌面端
+dsh plugin --profile desktop add /absolute/path/to/dsh-alk-pet
+
+# 独立 WebUI
+dsh plugin --profile web add /absolute/path/to/dsh-alk-pet
+```
+
+桌面端和独立 WebUI 使用不同的 profile，只需为实际使用的环境安装；两个环境都使用时需要分别安装。
+
+### 2. 重启并使用
+
+安装或修改配置后，重启 Host 并刷新客户端。此后正常使用 DSH 即可：插件会自动监听会话状态，不需要手动启动宠物。
+
+- 拖动宠物可改变位置。
+- 多任务时，将鼠标移到状态圆点上可切换任务。
+- 待机时气泡自动隐藏。
+- 完成或失败后，打开对应 DSH 会话查看结果，该任务圆点随后移除。
+
+宠物位置会自动保存，下次启动时恢复；窗口尺寸变化后，宠物会自动回到可见区域内。
+
+### 3. 修改设置
+
+可调整的设置如下（安装时的默认值由插件提供）：
+
+| 配置项 | 默认值 | 说明 |
+| --- | ---: | --- |
+| `enabled` | `true` | 是否启用宠物；关闭后不启动原生窗口，也不渲染网页回退版本 |
+| `size` | `120` | 宠物尺寸，取值会自动限制在 72–200 之间 |
+| `reducedMotion` | `false` | 只显示动画第 1 帧，适合减少动态效果或降低资源消耗 |
+| `showBubble` | `true` | 是否显示标题与动作气泡；任务状态圆点不受影响 |
+
+请在 DSH 提供的插件配置入口中调整这些选项，修改后重启 Host 并刷新客户端。
+
+## 状态说明
+
+| 状态 | 圆点样式 | 含义 |
+| --- | --- | --- |
+| 运行中 | 青绿色圆点、白色小方块 | Agent 正在思考、执行步骤或调用工具 |
+| 等待确认 | 琥珀色问号 | 需要用户输入、授权或确认 |
+| 成功 | 绿色勾 | 当前任务已完成 |
+| 失败 | 玫瑰红叉 | 当前任务遇到错误 |
+| 待机 | 灰色圆环 | 当前没有活动任务 |
+
+选中的任务会显示白色描边；将鼠标移到其他任务圆点上，即可查看对应的任务信息。
+
+## 权限与安全
+
+插件的本地接口设计用于本机访问，不提供账号登录或远程鉴权能力。所有 HTTP 接口（`/plugins/dsh-alk-pet/*`）只检查 TCP 对端是否为回环地址（`127.0.0.1` / `::1`）。因此：
+
+- 仅建议配合本机直连的 WebUI 使用。
+- **不要**将 WebUI 暴露到不受信任的网络。
+- **不要**把插件的回环地址检查视为登录鉴权或访问控制。
+
+Windows 原生窗口通过 PowerShell 启动，并使用分层窗口实现逐像素透明。若系统策略禁止运行 PowerShell 脚本，插件会自动回退到网页内宠物。
+
+随包提供的 macOS Helper 当前为 Apple Silicon 版本。Intel Mac 会自动回退到网页版本，也可以使用本机工具链重新构建。Linux 不提供原生悬浮窗，仅使用 WebUI 页面内版本。原生窗口异常退出时会自动重启两次；仍无法运行则自动回退。
+
+## 授权与声明
+
+- 项目代码采用 [MIT License](LICENSE) 发布，可在保留版权与许可声明的前提下使用、复制、修改、合并、发布、分发、再许可或销售。
+- 角色动画素材来自 [PC2005-cloud/dsh-pet](https://github.com/PC2005-cloud/dsh-pet)，使用参考仓库 `dsh-dafeiyu` 导出的六组动作帧，同样按 MIT 许可分发；原始版权与许可文本见 [assets/LICENSE.txt](assets/LICENSE.txt)。
+- 本项目是社区维护的非官方插件，与 DeepSeek 官方无关，也不代表 DeepSeek 官方立场。
+- 软件按“原样”提供，不附带任何明示或默示担保；完整条款以许可证原文为准。
+
+## 反馈与贡献
+
+遇到问题或有功能建议，欢迎提交 [GitHub Issue](https://github.com/penguinbing/dsh-alk-pet/issues)。请附上操作系统、DSH 版本、插件版本、复现步骤，以及相关截图或错误信息；提交前请移除会话内容中的隐私信息。
+
+欢迎通过 Pull Request 改进插件。参与开发需要 Node.js 20 或更高版本，克隆仓库后可运行：
+
+```sh
+npm test                 # 运行测试
+npm run check:assets     # 校验动画素材
+npm run build:assets     # 修改素材后重新生成资源
+npm run build:native     # macOS：构建原生 Helper（需要 Swift 工具链）
+```

package/assets/LICENSE.txt

@@ -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.