@michengai/dsh-codex-pet 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/CHANGELOG.md +25 -19
  2. package/CHANGELOG.zh-CN.md +25 -19
  3. package/LICENSE +201 -0
  4. package/NOTICE +14 -0
  5. package/README.md +218 -208
  6. package/README.zh-CN.md +220 -210
  7. package/lib/client.js +1 -1
  8. package/package.json +69 -66
package/README.md CHANGED
@@ -1,208 +1,218 @@
1
- <p align="center">
2
- <img src="assets/branding/dsh-codex-pet-banner.png" alt="DSH Codex Pet — a companion for your tasks" width="100%">
3
- </p>
4
-
5
- <div align="center">
6
-
7
- # DSH Codex Pet
8
-
9
- **A little companion for your DeepSeek Harness tasks.**
10
-
11
- [简体中文](README.zh-CN.md) · [Screenshots](#screenshots) · [Features](#features) · [Installation](#installation) · [Usage](#usage) · [Development](#development) · [Changelog](CHANGELOG.md)
12
-
13
- [![DSH Web Plugin](https://img.shields.io/badge/DSH%20Web-Plugin-0f766e.svg)](https://github.com/deepseek-ai/deepseek-harness)
14
- [![Node.js 22.19+](https://img.shields.io/badge/Node.js-22.19%2B-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org/)
15
- [![Development preview](https://img.shields.io/badge/Status-Development%20preview-d97706.svg)](#validation-and-current-limits)
16
-
17
- </div>
18
-
19
- 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.
20
-
21
- ## Features
22
-
23
- - **Nine built-in pets**: choose a companion and adjust its size in pet settings. Assets are bundled locally.
24
- - **In-page companion**: the plugin displays pets within DSH Web and exposes a consumer API. External hosts own their window and IPC adapters.
25
- - **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.
26
- - **Act from the notification**: open the associated task, stop its current turn, or handle supported approval, question, and plan requests.
27
- - **Quiet when you need it**: dismiss an individual reminder without stopping its task; collapse or restore the pet through its menu or settings.
28
- - **Create your own companion**: describe a pet in settings and start a dedicated DSH task using the bundled `hatch-pet` Skill.
29
- - **Small interactions**: drag to move, double-click to jump, and right-click for the pet menu.
30
-
31
- ## Screenshots
32
-
33
- ### Multiple task notifications
34
-
35
- See running tasks beside your companion, with separate controls to open the conversation, stop its current turn, or dismiss its reminder.
36
-
37
- <p align="center">
38
- <img src="assets/screenshots/pet-notifications.png" alt="A pet with two running task notifications" width="403">
39
- </p>
40
-
41
- ### Pet settings
42
-
43
- Choose from the nine built-in pets, access the custom pet directory, and adjust the pet size.
44
-
45
- ![Pet library and appearance settings](assets/screenshots/pet-settings.png)
46
-
47
- ### A companion in your conversation
48
-
49
- Keep working in DSH while the pet and task notifications remain in the corner of the page.
50
-
51
- ![Pet and task notifications alongside a DSH conversation](assets/screenshots/pet-conversation.png)
52
-
53
- ## DSH product ecosystem
54
-
55
- Install plugins as needed in an existing DeepSeek Harness environment. External consumers may integrate the pet API independently.
56
-
57
- | Plugin | What you can do |
58
- | --- | --- |
59
- | [Codex UI](https://github.com/MichengAI/dsh-codex-ui) | Organize projects and conversations and navigate tasks |
60
- | [IM Connect](https://github.com/MichengAI/dsh-im-connect) | Send tasks and receive replies through messaging platforms |
61
- | [Automation](https://github.com/MichengAI/dsh-automation) | Schedule tasks and review their runs |
62
- | [Skills Manager](https://github.com/MichengAI/dsh-skills-manager) | Find, enable, create, and import local skills |
63
- | [Archive Manager](https://github.com/MichengAI/dsh-archive-manager) | Search, restore, and manage archived conversations |
64
- | [Agency Agents](https://github.com/MichengAI/dsh-agency-agents) | Choose specialists for a task |
65
- | [BTW](https://github.com/MichengAI/dsh-btw) | Ask side questions in the current context |
66
- | [Simplify](https://github.com/MichengAI/dsh-simplify) | Improve code within your Git changes |
67
- | [Codex Pet](https://github.com/MichengAI/dsh-codex-pet) | Keep a companion nearby and handle task notifications |
68
-
69
- ## Prerequisites
70
-
71
- - DeepSeek Harness with its Web interface and the `dsh` command available.
72
- - Node.js **22.19 or newer** for building from source.
73
- - A configured image-generation tool in DSH to create custom pets.
74
-
75
- ## Installation
76
-
77
- 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.
78
-
79
- 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.
80
-
81
- Version 0.1.1 includes the settings, localization, npm updater, and consumer API changes described here; see the [changelog](CHANGELOG.md).
82
-
83
- 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.
84
-
85
- 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.
86
-
87
- ### Ask an agent to install it
88
-
89
- ```text
90
- 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.
91
- ```
92
-
93
- ### Build and install manually
94
-
95
- Run from the project root:
96
-
97
- ```powershell
98
- [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
99
- $OutputEncoding = [System.Text.Encoding]::UTF8
100
-
101
- npm ci
102
- npm run check
103
- npm test
104
- npm pack
105
- dsh plugin --profile web add .\michengai-dsh-codex-pet-0.1.1.tgz --ignore-scripts
106
- dsh --profile web --dump-config
107
- ```
108
-
109
- 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.
110
-
111
- ### Reloading
112
-
113
- 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.
114
-
115
- ## Usage
116
-
117
- Open **Settings → Pets** (`宠物` in the current UI), or open settings from the pet's right-click menu.
118
-
119
- | Goal | Action |
120
- | --- | --- |
121
- | Pick a companion | Select a pet in settings and adjust its size. |
122
- | Move or play | Drag the pet to move it; double-click to jump. |
123
- | Read task updates | Read the notification bubbles; expand the list when several tasks need attention. |
124
- | Continue a conversation | Click its notification or reply control to open the corresponding DSH task. |
125
- | Handle a request | Open the request details and answer the supported approval, question, or plan prompt. |
126
- | Stop a task turn | Click the stop control on that running task's notification. |
127
- | Dismiss a reminder | Click its close control. The task continues running. |
128
- | Hide or restore the pet | Use the right-click menu or pet settings. |
129
-
130
- The pet is a notification and action surface. Start new conversations and write follow-up messages in the main DSH interface.
131
-
132
- ### Create a custom pet
133
-
134
- 1. Open pet settings, click **Create** (`创建`), and describe the companion.
135
- 2. Click **Create in DSH** (`在 DSH 中创建`). The plugin opens a dedicated task and sends the bundled Skill instructions.
136
- 3. Follow that task's progress. Creation uses DSH's configured model and image tools.
137
- 4. Once the pet files are saved, refresh the pet library and select the new companion.
138
-
139
- 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.
140
-
141
- ## Data and assets
142
-
143
- - Built-in sprite sheets: `assets/codex/`, included with the plugin.
144
- - Custom pets: `${DSH_HOME}\codex-pet\pets`; when `DSH_HOME` is unset, the base directory is the user's `.dsh` directory.
145
- - Existing Codex pets are not automatically read, moved, or migrated.
146
- - Uninstalling the plugin leaves custom pet files and configuration in place.
147
-
148
- 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.
149
-
150
- ## Plugin updates
151
-
152
- 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.
153
-
154
- ## Uninstallation
155
-
156
- ```powershell
157
- [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
158
- $OutputEncoding = [System.Text.Encoding]::UTF8
159
-
160
- dsh plugin --profile web remove @michengai/dsh-codex-pet
161
- ```
162
-
163
- Reload DSH afterward. Keep your DSH data directory when switching versions.
164
-
165
- ## Development
166
-
167
- ```powershell
168
- [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
169
- $OutputEncoding = [System.Text.Encoding]::UTF8
170
-
171
- npm ci
172
- npm run check
173
- npm test
174
- npm run build
175
- ```
176
-
177
- - `src/`: Host service, pet settings, animation, and task notifications.
178
- - `skills/`: the bundled pet creation Skill.
179
- - `test/`: library, creation, and notification regression tests.
180
- - `scripts/`: build, asset maintenance, package verification, and isolated Electron smoke checks.
181
- - `lib/`: generated runtime output; edit `src/` instead.
182
-
183
- 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.
184
-
185
- 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.
186
-
187
- ## Validation and current limits
188
-
189
- 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.
190
-
191
- ## Browser smoke test
192
-
193
- 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.
194
-
195
- ## Consumer API v1
196
-
197
- 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.
198
-
199
- | Method | Contract |
200
- | --- | --- |
201
- | `getSnapshot()` | Returns a copied `{pet, config, language, notifications}` or `null` before loading/after disposal. Resolve relative pet asset URLs against the DSH page origin. |
202
- | `subscribe(listener)` | Receives changed snapshots or `null` on disposal; returns an unsubscribe function. Read the initial snapshot separately. |
203
- | `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. |
204
- | `updateConfig(value)` | Updates pet settings through the existing validated Host API. |
205
- | `openSettings()` | Opens plugin settings in DSH. |
206
- | `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. |
207
-
208
- 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.
1
+ <p align="center">
2
+ <img src="assets/branding/dsh-codex-pet-banner.png" alt="DSH Codex Pet — a companion for your tasks" width="100%">
3
+ </p>
4
+
5
+ <div align="center">
6
+
7
+ # DSH Codex Pet
8
+
9
+ **A little companion for your DeepSeek Harness tasks.**
10
+
11
+ [简体中文](README.zh-CN.md) · [Screenshots](#screenshots) · [Features](#features) · [Installation](#installation) · [Usage](#usage) · [Development](#development) · [Changelog](CHANGELOG.md)
12
+
13
+ [![DSH Web Plugin](https://img.shields.io/badge/DSH%20Web-Plugin-0f766e.svg)](https://github.com/deepseek-ai/deepseek-harness)
14
+ [![Node.js 22.19+](https://img.shields.io/badge/Node.js-22.19%2B-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org/)
15
+ [![npm](https://img.shields.io/npm/v/@michengai/dsh-codex-pet)](https://www.npmjs.com/package/@michengai/dsh-codex-pet)
16
+
17
+ </div>
18
+
19
+ 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.
20
+
21
+ ## Features
22
+
23
+ - **Nine built-in pets**: choose a companion and adjust its size in pet settings. Assets are bundled locally.
24
+ - **In-page companion**: the plugin displays pets within DSH Web and exposes a consumer API. External hosts own their window and IPC adapters.
25
+ - **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.
26
+ - **Act from the notification**: open the associated task, stop its current turn, or handle supported approval, question, and plan requests.
27
+ - **Quiet when you need it**: dismiss an individual reminder without stopping its task; collapse or restore the pet through its menu or settings.
28
+ - **Create your own companion**: describe a pet in settings and start a dedicated DSH task using the bundled `hatch-pet` Skill.
29
+ - **Small interactions**: drag to move, double-click to jump, and right-click for the pet menu.
30
+
31
+ ## Screenshots
32
+
33
+ ### Multiple task notifications
34
+
35
+ See running tasks beside your companion, with separate controls to open the conversation, stop its current turn, or dismiss its reminder.
36
+
37
+ <p align="center">
38
+ <img src="assets/screenshots/pet-notifications.png" alt="A pet with two running task notifications" width="403">
39
+ </p>
40
+
41
+ ### Pet settings
42
+
43
+ Choose from the nine built-in pets, access the custom pet directory, and adjust the pet size.
44
+
45
+ ![Pet library and appearance settings](assets/screenshots/pet-settings.png)
46
+
47
+ ### A companion in your conversation
48
+
49
+ Keep working in DSH while the pet and task notifications remain in the corner of the page.
50
+
51
+ ![Pet and task notifications alongside a DSH conversation](assets/screenshots/pet-conversation.png)
52
+
53
+ ## DSH product ecosystem
54
+
55
+ Install plugins as needed in an existing DeepSeek Harness environment. External consumers may integrate the pet API independently.
56
+
57
+ | Plugin | What you can do |
58
+ | --- | --- |
59
+ | [Codex UI](https://github.com/MichengAI/dsh-codex-ui) | Organize projects and conversations and navigate tasks |
60
+ | [IM Connect](https://github.com/MichengAI/dsh-im-connect) | Send tasks and receive replies through messaging platforms |
61
+ | [Automation](https://github.com/MichengAI/dsh-automation) | Schedule tasks and review their runs |
62
+ | [Skills Manager](https://github.com/MichengAI/dsh-skills-manager) | Find, enable, create, and import local skills |
63
+ | [Archive Manager](https://github.com/MichengAI/dsh-archive-manager) | Search, restore, and manage archived conversations |
64
+ | [Agency Agents](https://github.com/MichengAI/dsh-agency-agents) | Choose specialists for a task |
65
+ | [BTW](https://github.com/MichengAI/dsh-btw) | Ask side questions in the current context |
66
+ | [Simplify](https://github.com/MichengAI/dsh-simplify) | Improve code within your Git changes |
67
+ | [Codex Pet](https://github.com/MichengAI/dsh-codex-pet) | Keep a companion nearby and handle task notifications |
68
+
69
+ ## Prerequisites
70
+
71
+ - DeepSeek Harness with its Web interface and the `dsh` command available.
72
+ - Node.js **22.19 or newer** for building from source.
73
+ - A configured image-generation tool in DSH to create custom pets.
74
+
75
+ ## Installation
76
+
77
+ 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.
78
+
79
+ 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.
80
+
81
+ Version 0.1.2 includes the settings, localization, npm updater, and consumer API changes described here; see the [changelog](CHANGELOG.md).
82
+
83
+ The current version is **0.1.2**, 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.
84
+
85
+ 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.
86
+
87
+ ### Ask an agent to install it
88
+
89
+ ```text
90
+ 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.2.tgz using dsh plugin --profile web add .\michengai-dsh-codex-pet-0.1.2.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.
91
+ ```
92
+
93
+ ### Build and install manually
94
+
95
+ Run from the project root:
96
+
97
+ ```powershell
98
+ [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
99
+ $OutputEncoding = [System.Text.Encoding]::UTF8
100
+
101
+ npm ci
102
+ npm run check
103
+ npm test
104
+ npm pack
105
+ dsh plugin --profile web add .\michengai-dsh-codex-pet-0.1.2.tgz --ignore-scripts
106
+ dsh --profile web --dump-config
107
+ ```
108
+
109
+ 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.
110
+
111
+ ### Reloading
112
+
113
+ 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.
114
+
115
+ ## Usage
116
+
117
+ Open **Settings → Pets** (`宠物` in the current UI), or open settings from the pet's right-click menu.
118
+
119
+ | Goal | Action |
120
+ | --- | --- |
121
+ | Pick a companion | Select a pet in settings and adjust its size. |
122
+ | Move or play | Drag the pet to move it; double-click to jump. |
123
+ | Read task updates | Read the notification bubbles; expand the list when several tasks need attention. |
124
+ | Continue a conversation | Click its notification or reply control to open the corresponding DSH task. |
125
+ | Handle a request | Open the request details and answer the supported approval, question, or plan prompt. |
126
+ | Stop a task turn | Click the stop control on that running task's notification. |
127
+ | Dismiss a reminder | Click its close control. The task continues running. |
128
+ | Hide or restore the pet | Use the right-click menu or pet settings. |
129
+
130
+ The pet is a notification and action surface. Start new conversations and write follow-up messages in the main DSH interface.
131
+
132
+ ### Create a custom pet
133
+
134
+ 1. Open pet settings, click **Create** (`创建`), and describe the companion.
135
+ 2. Click **Create in DSH** (`在 DSH 中创建`). The plugin opens a dedicated task and sends the bundled Skill instructions.
136
+ 3. Follow that task's progress. Creation uses DSH's configured model and image tools.
137
+ 4. Once the pet files are saved, refresh the pet library and select the new companion.
138
+
139
+ 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.
140
+
141
+ ## Data and assets
142
+
143
+ - Built-in sprite sheets: `assets/codex/`, included with the plugin.
144
+ - Custom pets: `${DSH_HOME}\codex-pet\pets`; when `DSH_HOME` is unset, the base directory is the user's `.dsh` directory.
145
+ - Existing Codex pets are not automatically read, moved, or migrated.
146
+ - Uninstalling the plugin leaves custom pet files and configuration in place.
147
+
148
+ 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.
149
+
150
+ Original plugin code is licensed under [Apache-2.0](LICENSE), matching the other plugins in this series. Third-party pet artwork is excluded from that license grant; see [NOTICE](NOTICE).
151
+
152
+ ## Plugin updates
153
+
154
+ 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.
155
+
156
+ ## Uninstallation
157
+
158
+ ```powershell
159
+ [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
160
+ $OutputEncoding = [System.Text.Encoding]::UTF8
161
+
162
+ dsh plugin --profile web remove @michengai/dsh-codex-pet
163
+ ```
164
+
165
+ Reload DSH afterward. Keep your DSH data directory when switching versions.
166
+
167
+ ## Development
168
+
169
+ ```powershell
170
+ [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
171
+ $OutputEncoding = [System.Text.Encoding]::UTF8
172
+
173
+ npm ci
174
+ npm run check
175
+ npm test
176
+ npm run build
177
+ ```
178
+
179
+ - `src/`: Host service, pet settings, animation, and task notifications.
180
+ - `skills/`: the bundled pet creation Skill.
181
+ - `test/`: library, creation, and notification regression tests.
182
+ - `scripts/`: build, asset maintenance, package verification, and isolated Electron smoke checks.
183
+ - `lib/`: generated runtime output; edit `src/` instead.
184
+
185
+ 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.
186
+
187
+ 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.
188
+
189
+ ## Validation and current limits
190
+
191
+ 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.
192
+
193
+ ## Browser smoke test
194
+
195
+ 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.
196
+
197
+ ## Consumer API v1
198
+
199
+ 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.
200
+
201
+ | Method | Contract |
202
+ | --- | --- |
203
+ | `getSnapshot()` | Returns a copied `{pet, config, language, notifications}` or `null` before loading/after disposal. Resolve relative pet asset URLs against the DSH page origin. |
204
+ | `subscribe(listener)` | Receives changed snapshots or `null` on disposal; returns an unsubscribe function. Read the initial snapshot separately. |
205
+ | `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. |
206
+ | `updateConfig(value)` | Updates pet settings through the existing validated Host API. |
207
+ | `openSettings()` | Opens plugin settings in DSH. |
208
+ | `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. |
209
+
210
+ 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.
211
+
212
+ ## Automated releases
213
+
214
+ GitHub Actions runs type checking, unit tests, Chromium smoke tests, and package validation on main pushes and pull requests. Pushing a stable version tag matching package.json (for example v0.1.2) runs publish.yml, validates the package, and publishes through npm OIDC. After npm succeeds, it extracts the matching entries from both changelogs and creates a normal Latest GitHub Release with Chinese followed by English, without tarball or checksum attachments.
215
+
216
+ Before the first automated release, configure a GitHub Actions Trusted Publisher in the npm package Settings: owner MichengAI, repository dsh-codex-pet, workflow filename publish.yml, and no Environment. NPM_TOKEN is not required. The workflow cannot create this npm-side trust relationship itself.
217
+
218
+ Update package.json, package-lock.json, and both changelogs before committing and pushing a new version tag. Published npm versions cannot be overwritten; fixes require a version increment. CI also supports manual workflow_dispatch runs without publishing.