@michengai/dsh-codex-pet 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [0.1.1] - 2026-09-09
+
+- Keep pet rendering inside DSH Web and expose a versioned consumer API for state, notifications, commands, and display handoff. Native window adaptation belongs to the consumer; remove native routes, renderer, bridge calls, and sibling-project tests.
+- Use only the verified DSH CLI for npm updates, with a ten-minute timeout and an installation lock retained until process completion. Return stable localized error codes.
+- Localize pet names, descriptions, settings, notifications, and menus; preserve user content. Add version and project links, shared update dialog, and Windows folder opening.
+- Share library polling and publish only changed notification snapshots.
+- Run independent Playwright Chromium smoke tests in temporary directories with automatic cleanup. No Electron or sibling checkout is needed.
+- Pass type checking, 25 automated tests, build, and browser smoke checks. Real image generation, real-model interaction, and real npm updates still require acceptance testing.
+
+## [0.1.0] - 2026-09-09
+
+- Bundle nine pets, pet settings, and a DSH Skill-based entry for creating custom companions.
+- Support in-page Web companions and native windows through a compatible Desktop pet bridge.
+- Add multiple-task notifications, task navigation, current-turn cancellation, and approval, question, and plan request handling.
+- Exclude subagent sessions to prevent subagent routing errors when opening or stopping tasks.
+- Simplify the creation prompt by removing the Codex dependency disclaimer.
+- Provide English and Chinese READMEs, a banner, and real plugin screenshots; keep local docs outside version control.
+- Pass type checking, 17 automated tests, and the build; complete image generation, real-model interaction, and the normal Desktop installation still need end-to-end acceptance testing.

package/CHANGELOG.zh-CN.md

@@ -0,0 +1,20 @@
+# 更新日志
+
+## [0.1.1] - 2026-09-09
+
+- 插件仅在 DSH Web 页内显示，提供版本化消费者接口用于状态、通知、操作和展示接管。原生窗口由消费者适配，移除原生路由、渲染入口、桥接调用和跨仓测试。
+- npm 更新仅使用已验证的 DSH CLI，十分钟超时且进程结束后才释放安装锁；返回稳定错误码并本地化显示。
+- 宠物名称描述、设置、通知和菜单支持中英文，保留用户内容；提供版本号、项目链接、同系列更新弹窗及 Windows 打开文件夹修复。
+- 共享宠物库轮询，仅在通知内容变化时发布快照。
+- 独立使用 Playwright Chromium 冒烟测试，系统临时目录自动清理，不需要 Electron 或相邻仓库。
+- 类型检查、25 项自动化测试、构建及浏览器冒烟通过；真实生图、真实模型联动和真实 npm 更新仍待验收。
+
+## [0.1.0] - 2026-09-09
+
+- 提供 9 只随包内置宠物、宠物设置和基于 DSH Skill 的自定义宠物创建入口。
+- 支持 Web 页内陪伴和兼容 Desktop 宠物桥接的原生浮窗。
+- 提供多会话通知、跳转、停止当前轮次，以及审批、问题和计划请求处理。
+- 排除子代理会话，避免打开或停止操作触发 subagent routing 错误。
+- 简化创建提示词，移除“不依赖 Codex”表述。
+- 提供中英文 README、Banner 与实际插件截图；本地 docs 不纳入版本控制。
+- 类型检查、17 项自动化测试和构建通过；完整生图、真实模型联动与正式 Desktop 安装仍待端到端验收。

package/README.md

@@ -0,0 +1,208 @@
+<p align="center">
+  <img src="assets/branding/dsh-codex-pet-banner.png" alt="DSH Codex Pet — a companion for your tasks" width="100%">
+</p>
+
+<div align="center">
+
+# DSH Codex Pet
+
+**A little companion for your DeepSeek Harness tasks.**
+
+[简体中文](README.zh-CN.md) · [Screenshots](#screenshots) · [Features](#features) · [Installation](#installation) · [Usage](#usage) · [Development](#development) · [Changelog](CHANGELOG.md)
+
+[![DSH Web Plugin](https://img.shields.io/badge/DSH%20Web-Plugin-0f766e.svg)](https://github.com/deepseek-ai/deepseek-harness)
+[![Node.js 22.19+](https://img.shields.io/badge/Node.js-22.19%2B-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Development preview](https://img.shields.io/badge/Status-Development%20preview-d97706.svg)](#validation-and-current-limits)
+
+</div>
+
+DSH Codex Pet brings a pet library, task notifications, and a Skill-based creation flow to [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness). All nine built-in Codex pet sprite sheets ship with the plugin. Users do not need to install Codex.
+
+## Features
+
+- **Nine built-in pets**: choose a companion and adjust its size in pet settings. Assets are bundled locally.
+- **In-page companion**: the plugin displays pets within DSH Web and exposes a consumer API. External hosts own their window and IPC adapters.
+- **Multiple tasks at a glance**: follow running tasks, completion, errors, and requests that need your attention. An empty notification list leaves only the pet visible.
+- **Act from the notification**: open the associated task, stop its current turn, or handle supported approval, question, and plan requests.
+- **Quiet when you need it**: dismiss an individual reminder without stopping its task; collapse or restore the pet through its menu or settings.
+- **Create your own companion**: describe a pet in settings and start a dedicated DSH task using the bundled `hatch-pet` Skill.
+- **Small interactions**: drag to move, double-click to jump, and right-click for the pet menu.
+
+## Screenshots
+
+### Multiple task notifications
+
+See running tasks beside your companion, with separate controls to open the conversation, stop its current turn, or dismiss its reminder.
+
+<p align="center">
+  <img src="assets/screenshots/pet-notifications.png" alt="A pet with two running task notifications" width="403">
+</p>
+
+### Pet settings
+
+Choose from the nine built-in pets, access the custom pet directory, and adjust the pet size.
+
+![Pet library and appearance settings](assets/screenshots/pet-settings.png)
+
+### A companion in your conversation
+
+Keep working in DSH while the pet and task notifications remain in the corner of the page.
+
+![Pet and task notifications alongside a DSH conversation](assets/screenshots/pet-conversation.png)
+
+## DSH product ecosystem
+
+Install plugins as needed in an existing DeepSeek Harness environment. External consumers may integrate the pet API independently.
+
+| Plugin | What you can do |
+| --- | --- |
+| [Codex UI](https://github.com/MichengAI/dsh-codex-ui) | Organize projects and conversations and navigate tasks |
+| [IM Connect](https://github.com/MichengAI/dsh-im-connect) | Send tasks and receive replies through messaging platforms |
+| [Automation](https://github.com/MichengAI/dsh-automation) | Schedule tasks and review their runs |
+| [Skills Manager](https://github.com/MichengAI/dsh-skills-manager) | Find, enable, create, and import local skills |
+| [Archive Manager](https://github.com/MichengAI/dsh-archive-manager) | Search, restore, and manage archived conversations |
+| [Agency Agents](https://github.com/MichengAI/dsh-agency-agents) | Choose specialists for a task |
+| [BTW](https://github.com/MichengAI/dsh-btw) | Ask side questions in the current context |
+| [Simplify](https://github.com/MichengAI/dsh-simplify) | Improve code within your Git changes |
+| [Codex Pet](https://github.com/MichengAI/dsh-codex-pet) | Keep a companion nearby and handle task notifications |
+
+## Prerequisites
+
+- DeepSeek Harness with its Web interface and the `dsh` command available.
+- Node.js **22.19 or newer** for building from source.
+- A configured image-generation tool in DSH to create custom pets.
+
+## Installation
+
+Compatibility: the host must provide the `locale` client service and support function-valued `settings.section` labels. Local contract checks used `@deepseek-ai/cordis 4.0.2` and `@deepseek-ai/dsh-client-locale 0.1.2-rc.1`, plus the community DSH Codex UI settings implementation. These are checked component versions, not a verified minimum DSH release. Hosts without the locale service are not supported.
+
+Automatic updates use `--config.minimumReleaseAge=0` for that install command so a newly published version can be installed immediately. This bypasses pnpm’s release-age delay for the command without changing the global configuration. The package name, npm registry, and resolved version remain fixed by the server.
+
+Version 0.1.1 includes the settings, localization, npm updater, and consumer API changes described here; see the [changelog](CHANGELOG.md).
+
+The current version is **0.1.1**, available on [npm](https://www.npmjs.com/package/@michengai/dsh-codex-pet). See [GitHub Releases](https://github.com/MichengAI/dsh-codex-pet/releases) for release notes. Replace `web` below with your actual DSH profile.
+
+Run `dsh plugin --profile web add @michengai/dsh-codex-pet@latest --registry=https://registry.npmjs.org/ --ignore-scripts`, then reload DSH. The source build instructions follow.
+
+### Ask an agent to install it
+
+```text
+Install DSH Codex Pet from my local source checkout into the DSH web profile. In that checkout, run npm ci, npm run check, npm test, and npm pack. If all checks pass, install the generated michengai-dsh-codex-pet-0.1.1.tgz using dsh plugin --profile web add .\michengai-dsh-codex-pet-0.1.1.tgz --ignore-scripts. Run dsh --profile web --dump-config and confirm michengai-codex-pet is present. Explain how to reload DSH and open pet settings. Preserve existing tasks and user data.
+```
+
+### Build and install manually
+
+Run from the project root:
+
+```powershell
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+$OutputEncoding = [System.Text.Encoding]::UTF8
+
+npm ci
+npm run check
+npm test
+npm pack
+dsh plugin --profile web add .\michengai-dsh-codex-pet-0.1.1.tgz --ignore-scripts
+dsh --profile web --dump-config
+```
+
+Stop if any command fails. `npm pack` builds the plugin and checks that the nine sprite sheets and creation Skill are present. The generated archive includes the runtime assets.
+
+### Reloading
+
+After active tasks finish, restart the relevant DSH Web service and refresh its Web interface. A browser refresh alone does not replace an already loaded Host module.
+
+## Usage
+
+Open **Settings → Pets** (`宠物` in the current UI), or open settings from the pet's right-click menu.
+
+| Goal | Action |
+| --- | --- |
+| Pick a companion | Select a pet in settings and adjust its size. |
+| Move or play | Drag the pet to move it; double-click to jump. |
+| Read task updates | Read the notification bubbles; expand the list when several tasks need attention. |
+| Continue a conversation | Click its notification or reply control to open the corresponding DSH task. |
+| Handle a request | Open the request details and answer the supported approval, question, or plan prompt. |
+| Stop a task turn | Click the stop control on that running task's notification. |
+| Dismiss a reminder | Click its close control. The task continues running. |
+| Hide or restore the pet | Use the right-click menu or pet settings. |
+
+The pet is a notification and action surface. Start new conversations and write follow-up messages in the main DSH interface.
+
+### Create a custom pet
+
+1. Open pet settings, click **Create** (`创建`), and describe the companion.
+2. Click **Create in DSH** (`在 DSH 中创建`). The plugin opens a dedicated task and sends the bundled Skill instructions.
+3. Follow that task's progress. Creation uses DSH's configured model and image tools.
+4. Once the pet files are saved, refresh the pet library and select the new companion.
+
+The bundled `skills/hatch-pet/SKILL.md` is adapted for DSH and the compatible sprite-sheet format. The creation flow does not invoke the Codex CLI. A missing image tool must be resolved in DSH; opening the creation task alone does not mean a pet has been generated.
+
+## Data and assets
+
+- Built-in sprite sheets: `assets/codex/`, included with the plugin.
+- Custom pets: `${DSH_HOME}\codex-pet\pets`; when `DSH_HOME` is unset, the base directory is the user's `.dsh` directory.
+- Existing Codex pets are not automatically read, moved, or migrated.
+- Uninstalling the plugin leaves custom pet files and configuration in place.
+
+The plugin is independently implemented and community maintained. The bundled Codex pet artwork comes from Codex; it is not original artwork by this project. This project is not an official OpenAI or DeepSeek product.
+
+## Plugin updates
+
+Pet settings show the running version, GitHub and issue links, and **Check for updates**. The updater queries npm and installs into the current DSH profile using the verified DSH CLI. Unsupported hosts can copy a manual update command. Wait for active tasks to finish before installing an update; reload DSH when prompted.
+
+## Uninstallation
+
+```powershell
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+$OutputEncoding = [System.Text.Encoding]::UTF8
+
+dsh plugin --profile web remove @michengai/dsh-codex-pet
+```
+
+Reload DSH afterward. Keep your DSH data directory when switching versions.
+
+## Development
+
+```powershell
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+$OutputEncoding = [System.Text.Encoding]::UTF8
+
+npm ci
+npm run check
+npm test
+npm run build
+```
+
+- `src/`: Host service, pet settings, animation, and task notifications.
+- `skills/`: the bundled pet creation Skill.
+- `test/`: library, creation, and notification regression tests.
+- `scripts/`: build, asset maintenance, package verification, and isolated Electron smoke checks.
+- `lib/`: generated runtime output; edit `src/` instead.
+
+There is no standalone HTML preview or native window entry. Verify the plugin inside DSH. `assets:import` is a maintainer command for updating original assets, not an installation requirement.
+
+For CodeGraph, run `codegraph init .` once, `codegraph sync .` after changes, and `codegraph status .` to check freshness. The index and local project documentation under `docs/` are excluded from Git.
+
+## Validation and current limits
+
+Type checking, 25 automated tests, the build, and controlled browser client interaction checks have passed. These cover task notifications and the creation request flow. Complete image generation, real-model task interaction and real npm updates still need end-to-end acceptance testing.
+
+## Browser smoke test
+
+After `npm ci`, run `npx playwright install chromium`, then `npm run smoke`. Playwright is a development dependency of this project. The test uses headless Chromium and a unique system temporary directory, cleaned after the test process exits. No Electron, sibling repository, `.preview`, or docs output is required.
+
+## Consumer API v1
+
+The plugin publishes `window.dshPet` in the DSH page and emits `dsh-pet-ready` / `dsh-pet-disposed`. Consumers subscribe and render independently; the plugin never imports or probes a consumer. Previous native window routes and window bridges have been removed. Existing native adapters must migrate to this contract.
+
+| Method | Contract |
+| --- | --- |
+| `getSnapshot()` | Returns a copied `{pet, config, language, notifications}` or `null` before loading/after disposal. Resolve relative pet asset URLs against the DSH page origin. |
+| `subscribe(listener)` | Receives changed snapshots or `null` on disposal; returns an unsubscribe function. Read the initial snapshot separately. |
+| `command(value)` | Executes notification commands (`open`, `stop`, `dismiss`, `restore`, `approve`, `reject`, `answer`, `sort`). Targeted commands require the current notification `id` and `token`; request answers also require `requestKey`. Validation and rejection stay in the plugin. |
+| `updateConfig(value)` | Updates pet settings through the existing validated Host API. |
+| `openSettings()` | Opens plugin settings in DSH. |
+| `acquireDisplay()` | Hides only the page overlay and returns an idempotent release function. Call release when disconnecting; the overlay returns after all consumers release. This does not change persisted visibility. |
+
+Consumers own their renderer, native window, IPC validation, and disconnect cleanup. The interface carries no native window implementation. User titles, questions, and answer options remain unchanged; the `language` field identifies the display locale.

package/README.zh-CN.md

@@ -0,0 +1,210 @@
+<p align="center">
+  <img src="assets/branding/dsh-codex-pet-banner.png" alt="DSH Codex Pet：任务在跑，宠物相伴" width="100%">
+</p>
+
+<div align="center">
+
+# DSH Codex Pet
+
+**任务在跑，宠物相伴。让 DeepSeek Harness 的任务进展触手可及。**
+
+[English](README.md) · [界面预览](#界面预览) · [功能概览](#功能概览) · [安装](#安装) · [使用](#使用) · [开发](#开发) · [更新日志](CHANGELOG.zh-CN.md)
+
+[![DSH Web Plugin](https://img.shields.io/badge/DSH%20Web-Plugin-0f766e.svg)](https://github.com/deepseek-ai/deepseek-harness)
+[![Node.js 22.19+](https://img.shields.io/badge/Node.js-22.19%2B-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![开发预览版](https://img.shields.io/badge/Status-Development%20preview-d97706.svg)](#验证与当前边界)
+
+</div>
+
+DSH Codex Pet 为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供宠物库、任务通知和基于 Skill 的宠物创建功能。全部 9 只 Codex 内置宠物图集随插件提供，使用人员无需安装 Codex。
+
+## 功能概览
+
+- **9 只内置宠物**：在宠物设置中选择伙伴、调整大小，资源随插件本地打包。
+- **页内陪伴**：插件在 DSH Web 页面内显示宠物，并提供消费者接口；外部宿主自行适配窗口与 IPC。
+- **多会话动态**：查看运行中、完成、错误和待处理请求；没有通知时只显示宠物。
+- **就近处理任务**：从通知打开对应会话、停止当前轮次，或处理支持的审批、问题和计划请求。
+- **按需安静**：关闭单条提醒不会停止任务；通过菜单或设置收起、恢复宠物。
+- **创建自己的伙伴**：在设置中描述宠物，通过随包 `hatch-pet` Skill 发起独立 DSH 创建任务。
+- **轻量互动**：拖动移动、双击跳跃、右键打开宠物菜单。
+
+## 界面预览
+
+### 多会话提醒
+
+宠物旁集中展示运行中的任务，可分别打开会话、停止当前轮次或关闭提醒。
+
+<p align="center">
+  <img src="assets/screenshots/pet-notifications.png" alt="宠物与两条运行中的任务通知" width="403">
+</p>
+
+### 宠物设置
+
+选择 9 只内置宠物、打开自定义宠物目录，并调整宠物大小。
+
+![宠物库与外观设置](assets/screenshots/pet-settings.png)
+
+### 会话内陪伴
+
+在 DSH 中继续工作，宠物和任务通知显示在页面角落。
+
+![DSH 会话中的宠物与任务通知](assets/screenshots/pet-conversation.png)
+
+## DSH 产品生态
+
+为已有 DeepSeek Harness 环境按需安装插件；外部消费者可独立接入宠物接口。
+
+| 插件 | 你可以用它做什么 |
+| --- | --- |
+| [Codex UI](https://github.com/MichengAI/dsh-codex-ui) | 整理项目与会话，导航任务 |
+| [IM Connect](https://github.com/MichengAI/dsh-im-connect) | 从消息平台下任务、收回复 |
+| [Automation](https://github.com/MichengAI/dsh-automation) | 按计划执行任务，查看运行结果 |
+| [Skills Manager](https://github.com/MichengAI/dsh-skills-manager) | 查找、启停、创建和导入本机技能 |
+| [Archive Manager](https://github.com/MichengAI/dsh-archive-manager) | 搜索、恢复和管理已归档会话 |
+| [Agency Agents](https://github.com/MichengAI/dsh-agency-agents) | 为任务选择专业角色 |
+| [BTW](https://github.com/MichengAI/dsh-btw) | 在当前上下文中临时旁问 |
+| [Simplify](https://github.com/MichengAI/dsh-simplify) | 整理 Git 改动范围内的代码 |
+| [Codex Pet](https://github.com/MichengAI/dsh-codex-pet) | 宠物陪伴，查看和处理任务通知 |
+
+## 前置条件
+
+- 已安装 DeepSeek Harness，可使用 Web 界面和 `dsh` 命令。
+- 从源码构建需要 **Node.js 22.19 或更高版本**。
+- 创建自定义宠物需要在 DSH 中配置可用的图像生成工具。
+
+## 安装
+
+兼容要求：宿主必须提供 `locale` 客户端服务，并支持函数形式的 `settings.section` 标签。本地契约核验使用 `@deepseek-ai/cordis 4.0.2`、`@deepseek-ai/dsh-client-locale 0.1.2-rc.1` 及社区 DSH Codex UI 设置实现。这些是已核验组件版本，不代表已经验证的最低 DSH 版本；不支持缺少 locale 服务的宿主。
+
+自动更新命令使用 `--config.minimumReleaseAge=0`，以便立即安装刚发布的版本；该参数仅对本次安装跳过 pnpm 的发布时间等待，不改写全局配置。包名、npm registry 和解析后的版本仍由服务端固定。
+
+v0.1.1 安装包包含本文描述的设置、本地化、npm 更新器和消费者接口改动，详见[更新日志](CHANGELOG.zh-CN.md)。
+
+当前版本为 **0.1.1**，通过 [npm](https://www.npmjs.com/package/@michengai/dsh-codex-pet) 安装；版本记录见 [GitHub Releases](https://github.com/MichengAI/dsh-codex-pet/releases)。以下命令使用 `web` profile，请按实际环境替换。
+
+执行 `dsh plugin --profile web add @michengai/dsh-codex-pet@latest --registry=https://registry.npmjs.org/ --ignore-scripts`，然后重新加载 DSH。也可按下面的步骤从源码构建。
+
+### 让 Agent 帮你安装
+
+```text
+请从我的本地源码目录将 DSH Codex Pet 安装到 DSH 的 web profile。在源码目录依次执行 npm ci、npm run check、npm test 和 npm pack。检查通过后，执行 dsh plugin --profile web add .\michengai-dsh-codex-pet-0.1.1.tgz --ignore-scripts 安装生成的包，再执行 dsh --profile web --dump-config，确认包含 michengai-codex-pet。说明如何重新加载 DSH 并打开宠物设置，保留已有任务和用户数据。
+```
+
+### 手动构建并安装
+
+在项目根目录执行：
+
+```powershell
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+$OutputEncoding = [System.Text.Encoding]::UTF8
+
+npm ci
+npm run check
+npm test
+npm pack
+dsh plugin --profile web add .\michengai-dsh-codex-pet-0.1.1.tgz --ignore-scripts
+dsh --profile web --dump-config
+```
+
+任一步骤失败时先停止并解决错误。`npm pack` 会构建插件并检查 9 只图集和创建 Skill，生成的安装包包含运行所需资源。
+
+### 重新加载
+
+等待正在执行的任务结束后，重启对应 DSH Web 服务并刷新页面。仅刷新浏览器不能替换已经加载的 Host 模块。
+
+## 使用
+
+打开 **设置 → 宠物**，也可从宠物右键菜单打开设置。
+
+| 目标 | 操作 |
+| --- | --- |
+| 选择伙伴 | 在设置中选择宠物并调整大小。 |
+| 移动与互动 | 拖动宠物移动，双击跳跃。 |
+| 查看任务动态 | 阅读通知气泡；多个任务需要关注时展开列表。 |
+| 继续会话 | 点击通知或回复按钮，打开对应的 DSH 任务。 |
+| 处理请求 | 展开请求详情，处理支持的审批、问题或计划。 |
+| 停止任务轮次 | 点击对应运行中通知的停止按钮。 |
+| 关闭提醒 | 点击通知关闭按钮，任务仍继续运行。 |
+| 收起或恢复宠物 | 使用右键菜单或宠物设置。 |
+
+宠物承担通知和待处理操作。新建会话、输入后续消息仍在 DSH 主界面完成。
+
+### 创建自定义宠物
+
+1. 打开宠物设置，点击 **创建**，描述想要的伙伴。
+2. 点击 **在 DSH 中创建**，插件会打开独立任务并发送随包 Skill 指令。
+3. 在该任务中查看进展，创建使用 DSH 当前配置的模型和图像工具。
+4. 宠物文件生成并保存后，刷新宠物库并选择新伙伴。
+
+随包 `skills/hatch-pet/SKILL.md` 已针对 DSH 和兼容图集格式适配，创建流程不调用 Codex CLI。缺少生图工具时需要先完善 DSH 配置；成功打开创建任务不等于宠物已经生成。
+
+## 数据与资源
+
+- 内置图集：`assets/codex/`，随插件提供。
+- 自定义宠物：`${DSH_HOME}\codex-pet\pets`；未设置 `DSH_HOME` 时，以用户目录下的 `.dsh` 为基础目录。
+- 不自动读取、移动或迁移原有 Codex 宠物。
+- 卸载插件会保留自定义宠物文件和配置。
+
+插件代码独立实现、由社区维护。随包 Codex 宠物图集来源于 Codex，并非本项目原创素材。本项目不是 OpenAI 或 DeepSeek 官方产品。
+
+## 插件更新
+
+宠物设置页显示当前运行版本、GitHub 和问题反馈链接，以及**检查更新**入口。更新器查询 npm，通过已验证的 DSH CLI 安装到当前 profile；npm 尚未发布时会明确提示。宿主不支持在线安装时，可复制手动更新命令。请等待任务结束后更新，并按提示重新加载 DSH。
+
+## 卸载
+
+```powershell
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+$OutputEncoding = [System.Text.Encoding]::UTF8
+
+dsh plugin --profile web remove @michengai/dsh-codex-pet
+```
+
+完成后重新加载 DSH。切换版本时保留 DSH 数据目录。
+
+## 开发
+
+```powershell
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+$OutputEncoding = [System.Text.Encoding]::UTF8
+
+npm ci
+npm run check
+npm test
+npm run build
+```
+
+- `src/`：Host 服务、宠物设置、动画和任务通知。
+- `skills/`：随包宠物创建 Skill。
+- `test/`：宠物库、创建和通知回归测试。
+- `scripts/`：构建、资源维护、安装包校验和隔离 Electron smoke 检查。
+- `lib/`：生成的运行产物，修改源码应在 `src/` 中进行。
+
+项目不提供独立 HTML 预览页或原生窗口入口，请在 DSH 内验证。`assets:import` 仅供维护者更新原始资源，使用者安装时无需执行。
+
+使用 CodeGraph 时，首次运行 `codegraph init .`，修改后运行 `codegraph sync .`，通过 `codegraph status .` 检查索引新鲜度。索引与 `docs/` 下的本地项目文档均不纳入 Git。
+
+## 验证与当前边界
+
+类型检查、25 项自动化测试、构建和受控浏览器客户端交互验证已通过，覆盖任务通知和创建请求流程。完整图像生成、真实模型任务联动及真实 npm 更新仍待端到端验收。
+
+
+
+## 浏览器冒烟测试
+
+执行 `npm ci` 后，运行 `npx playwright install chromium`，再执行 `npm run smoke`。Playwright 是本项目的开发依赖，测试使用无头 Chromium 和独立系统临时目录，测试进程退出后自动清理；不需要 Electron、相邻仓库、`.preview` 或 docs 输出。
+
+## 消费者接口 v1
+
+插件在 DSH 页面提供 `window.dshPet`，发布 `dsh-pet-ready` / `dsh-pet-disposed` 事件。消费者主动订阅和展示，插件不导入或探测消费者。旧原生窗口路由与窗口桥接已移除，已有原生适配需迁移到此接口。
+
+| 方法 | 约定 |
+| --- | --- |
+| `getSnapshot()` | 返回独立副本 `{pet, config, language, notifications}`；未加载或卸载后为 `null`。宠物资源相对 URL 按 DSH 页面 origin 解析。 |
+| `subscribe(listener)` | 内容变化时通知，卸载时收到 `null`；返回退订函数。初始状态另行调用 getSnapshot。 |
+| `command(value)` | 执行通知操作：open、stop、dismiss、restore、approve、reject、answer、sort。目标操作携带当前通知 id、token；请求回答另带 requestKey。校验和拒绝由插件执行。 |
+| `updateConfig(value)` | 通过现有 Host 校验接口更新宠物设置。 |
+| `openSettings()` | 在 DSH 打开宠物设置。 |
+| `acquireDisplay()` | 暂时隐藏页内浮层，返回幂等释放函数。消费者断开时必须释放，所有接管者释放后恢复页内显示，不改持久化可见性配置。 |
+
+消费者负责自身渲染器、原生窗口、IPC 校验和断开清理；接口不携带原生窗口实现。用户标题、问题与回答选项保持原文，language 字段提供显示语言。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: michengai-codex-pet
+      name: '@michengai/dsh-codex-pet'