dsh-astudio-connect 0.0.0-stage → 0.1.0
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.
- package/LICENSE +21 -0
- package/README.en.md +380 -0
- package/README.md +380 -2
- package/cordis.patch.yml +6 -0
- package/lib/bin.d.ts +18 -0
- package/lib/bin.js +157 -0
- package/lib/catalog-V2vZUp8z.js +692 -0
- package/lib/client.js +753 -0
- package/lib/index.d.ts +381 -0
- package/lib/index.js +1848 -0
- package/package.json +108 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 dsh-astudio-connect contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.en.md
ADDED
|
@@ -0,0 +1,380 @@
|
|
|
1
|
+
# dsh-astudio-connect
|
|
2
|
+
|
|
3
|
+
English | [中文](./README.md)
|
|
4
|
+
|
|
5
|
+
Bring the models signed in to the AStudio desktop app into [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) with zero configuration.
|
|
6
|
+
|
|
7
|
+
An adaptation of the design in [dsh-workbuddy-connect](https://github.com/corrinehu/dsh-workbuddy-connect), heavily slimmed down for AStudio's maas-api (a standard OpenAI protocol).
|
|
8
|
+
|
|
9
|
+
> **Zero configuration**: reuses your local AStudio sign-in. No second login, nothing written to disk.
|
|
10
|
+
|
|
11
|
+
## Table of Contents
|
|
12
|
+
|
|
13
|
+
- [Installation](#installation)
|
|
14
|
+
- [Features](#features)
|
|
15
|
+
- [Command Line](#command-line)
|
|
16
|
+
- [How It Works](#how-it-works)
|
|
17
|
+
- [Configuration](#configuration)
|
|
18
|
+
- [Model Catalog](#model-catalog)
|
|
19
|
+
- [Reasoning Effort and Probing](#reasoning-effort-and-probing)
|
|
20
|
+
- [Model Visibility](#model-visibility)
|
|
21
|
+
- [Points Balance Badge](#points-balance-badge)
|
|
22
|
+
- [Settings Card](#settings-card)
|
|
23
|
+
- [Update Check and Host Heartbeat](#update-check-and-host-heartbeat)
|
|
24
|
+
- [Location Discovery (Windows)](#location-discovery-windows)
|
|
25
|
+
- [DSH Version Support](#dsh-version-support)
|
|
26
|
+
- [Known Limitations](#known-limitations)
|
|
27
|
+
- [Security](#security)
|
|
28
|
+
- [Development](#development)
|
|
29
|
+
- [Disclaimer](#disclaimer)
|
|
30
|
+
- [Related Projects / Community Ecosystem](#related-projects--community-ecosystem)
|
|
31
|
+
- [Acknowledgements](#acknowledgements)
|
|
32
|
+
- [License](#license)
|
|
33
|
+
|
|
34
|
+
## Installation
|
|
35
|
+
|
|
36
|
+
### Prerequisites
|
|
37
|
+
|
|
38
|
+
- Node.js `^22.19.0 || >=24.0.0` installed locally
|
|
39
|
+
- The AStudio desktop app installed and signed in (the plugin reuses the app's sign-in state; account switches follow automatically)
|
|
40
|
+
- A DeepSeek Harness runtime — see [DSH Version Support](#dsh-version-support)
|
|
41
|
+
|
|
42
|
+
### Install the plugin
|
|
43
|
+
|
|
44
|
+
The plugin registers its manifest through `cordis.patch.yml`, and DSH loads it at startup.
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
# Install from the local directory
|
|
48
|
+
npm install -D ./dsh-astudio-connect
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Or add this directory path in the DSH plugin manager.
|
|
52
|
+
|
|
53
|
+
### Verify
|
|
54
|
+
|
|
55
|
+
After installing you must **fully quit and restart DSH** (DSH loads plugins at startup; refreshing the page is not enough), then confirm:
|
|
56
|
+
|
|
57
|
+
1. An **AStudio** group appears in the model picker;
|
|
58
|
+
2. Pick a model from that group and complete a short conversation that answers normally.
|
|
59
|
+
|
|
60
|
+
Both must hold for the install to count as successful. If the group does not appear, start with `doctor` in the [Command Line](#command-line) section to check sign-in state and the config path.
|
|
61
|
+
|
|
62
|
+
> You can also hand the install to an agent you already have locally (DSH Agent, Codex, Claude Code, Cursor, …) by sending it this paragraph verbatim:
|
|
63
|
+
>
|
|
64
|
+
> Please install and verify the DSH (DeepSeek Harness) plugin dsh-astudio-connect (local directory: `<repo path>`):
|
|
65
|
+
> Read the project README first, and confirm which interface I actually use (Web / Desktop / TUI) and the DSH kernel version;
|
|
66
|
+
> Install from the local directory using the `cordis.patch.yml` registration, without modifying dependency packages or bypassing host validation;
|
|
67
|
+
> Ask me for consent and back up any local file or configuration change;
|
|
68
|
+
> Once installed, verify that an AStudio group appears in the model picker, and run a short conversation with me.
|
|
69
|
+
|
|
70
|
+
## Features
|
|
71
|
+
|
|
72
|
+
- **Works out of the box**: no extra configuration after the plugin is installed and enabled.
|
|
73
|
+
- **Credential reuse**: reads AStudio's `experimental_bearer_token`; no separate OAuth flow.
|
|
74
|
+
- **Standard protocol**: maas-api speaks standard OpenAI-compatible protocol, which pi-ai supports natively — no protocol translation.
|
|
75
|
+
- **Full capability bridge**: non-streaming, streaming SSE, tool calls, `reasoning_content` from reasoning models, and context compaction all reuse the DSH host's own implementations.
|
|
76
|
+
- **Model catalog**: taken from AStudio's own model-manager endpoint (the same document the AStudio UI renders), carrying real context windows and max output, with a three-tier fallback of live → saved → built-in.
|
|
77
|
+
- **Reasoning-effort probing**: for models that declare no levels, sends a minimal sentinel-bearing request under your explicit consent, confirming the upstream actually validates `reasoning_effort` before accepting which levels it accepts.
|
|
78
|
+
- **Model visibility**: pick which models appear in the picker from the settings card; preferences are stored per signed-in account, and hiding only affects selectability, not sessions already using that model.
|
|
79
|
+
- **Balance at a glance**: with an AStudio model selected, the composer shows the account's general and Spark points balances beside the model picker, with a ↻ manual refresh and no automatic polling.
|
|
80
|
+
- **Settings card**: the AStudio Connect card under the sidebar Plugins panel, split into Account / Context / Probe sections, with manual catalog refresh and probing.
|
|
81
|
+
- **Command-line diagnostics**: `status`, `doctor` and `logout` — never emit credential material.
|
|
82
|
+
- **Update check**: compares against npm's public dist-tags to decide whether a newer release exists, and enriches with GitHub release notes.
|
|
83
|
+
|
|
84
|
+
## Command Line
|
|
85
|
+
|
|
86
|
+
The plugin ships a `dsh-astudio-connect` executable (the `bin` in `package.json`). It **does not start the host and does not load pi-ai**, so it can run standalone and be used to troubleshoot from anywhere:
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
Usage: dsh-astudio-connect <doctor|status|logout> [--provider astudio] [--json]
|
|
90
|
+
|
|
91
|
+
doctor secret-free sign-in and environment diagnostics
|
|
92
|
+
status sign-in state, catalog source, and model count
|
|
93
|
+
logout clear the plugin in-memory credential cache
|
|
94
|
+
|
|
95
|
+
--provider which provider to inspect; defaults to astudio
|
|
96
|
+
--json emit one secret-free JSON document (doctor/status only)
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Run it from a local checkout (when not globally installed):
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
node lib/bin.js status
|
|
103
|
+
node lib/bin.js doctor --json
|
|
104
|
+
node lib/bin.js logout
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
| Command | Output | Exit code |
|
|
108
|
+
|---|---|---|
|
|
109
|
+
| `doctor` | Config file path and presence, sign-in state, whether the model-manager token exists, remediation hints | `0` when `signed-in` **and** the config file exists, otherwise `1` |
|
|
110
|
+
| `status` | Sign-in state, catalog source, model count | `0` when `signed-in`, otherwise `1` |
|
|
111
|
+
| `logout` | Clears the plugin's own in-memory credential cache | Always `0` |
|
|
112
|
+
|
|
113
|
+
Behaviour guarantees:
|
|
114
|
+
|
|
115
|
+
- **Writes nothing**: none of the three commands writes AStudio's `config.toml`; `logout` clears only the plugin's own in-memory cache, leaves the desktop app's sign-in alone, and does not promise to make the model group disappear (it still applies as long as the app's credential file is present).
|
|
116
|
+
- **Never echoes credentials**: output carries only `tokenLength` and "present / absent", never the token itself; JWT-shaped strings in error text are replaced with `[redacted token]`.
|
|
117
|
+
- **`--provider` accepts only `astudio`** — anything else errors out.
|
|
118
|
+
|
|
119
|
+
> **Known behaviour**: the catalog source reported by `status` is always `built-in`. The live refresh happens inside the host process, and a standalone CLI process does not issue that request, so it reflects the built-in roster rather than the catalog the host is actually using. For the host's real source, see the Account section of the settings card.
|
|
120
|
+
|
|
121
|
+
## How It Works
|
|
122
|
+
|
|
123
|
+
The plugin registers maas-api's models into DSH's `llm` seam through a three-layer bridge:
|
|
124
|
+
|
|
125
|
+
1. **Credential layer** (`auth.ts`): reads `experimental_bearer_token` from AStudio's `config.toml`, caches it in memory, never writes it to disk.
|
|
126
|
+
2. **Local shim** (`shim.ts`): starts an OpenAI-compatible endpoint on `127.0.0.1`, validates four inbound guards, then forwards to maas-api.
|
|
127
|
+
3. **pi-ai adapter** (`adapter.ts`): registers the shim's endpoint as DSH's `astudio` provider using `openAICompletionsApi()` + `PiAiAdapter`.
|
|
128
|
+
|
|
129
|
+
```
|
|
130
|
+
DSH (llm seam) → AStudioPiAiAdapter → 127.0.0.1 shim → maas-api (Bearer token)
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
The model catalog and the points balance travel over two separate read-only paths that do not go through the shim:
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
model-manager API ← modelBearerToken (model roster and context parameters)
|
|
137
|
+
account points API ← ssoSessionId (general / Spark points balance)
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
All three credentials come from AStudio's own files, but they serve different purposes and are not interchangeable.
|
|
141
|
+
|
|
142
|
+
### Shim routes
|
|
143
|
+
|
|
144
|
+
| Method | Path | Purpose |
|
|
145
|
+
|---|---|---|
|
|
146
|
+
| `GET` | `/healthz` | Liveness probe |
|
|
147
|
+
| `GET` | `/v1/models` | Model roster, **hidden entries filtered out** |
|
|
148
|
+
| `POST` | `/v1/chat/completions` | Forwarded to maas-api, request body and streaming response passed through |
|
|
149
|
+
|
|
150
|
+
Request bodies are capped at 64 MB; a broken stream gets a terminating `data: [DONE]\n\n`; a single stream idles out after 300 seconds.
|
|
151
|
+
|
|
152
|
+
The port the shim binds avoids the ports the fetch standard refuses to connect to (`FETCH_BLOCKED_PORTS` in `loopback.ts`): the OS may hand out an ephemeral port that fetch will not dial, in which case the shim listens successfully yet every request fails with `TypeError: fetch failed`. So it rebinds, up to 16 attempts.
|
|
153
|
+
|
|
154
|
+
## Configuration
|
|
155
|
+
|
|
156
|
+
Plugin configuration is managed through DSH's plugin page (on 0.2.x: sidebar **Plugins** panel → AStudio Connect):
|
|
157
|
+
|
|
158
|
+
| Field | Description |
|
|
159
|
+
|------|------|
|
|
160
|
+
| `displayName` | Provider name shown in the model picker (default `AStudio`) |
|
|
161
|
+
| `configPath` | Explicit path to AStudio's `config.toml` |
|
|
162
|
+
|
|
163
|
+
`cordis.patch.yml` only registers the plugin; it does not change the profile's current default model.
|
|
164
|
+
|
|
165
|
+
## Model Catalog
|
|
166
|
+
|
|
167
|
+
The model roster and context parameters come from AStudio's **model-manager** endpoint (`GET /api/v1/model-manager/models`, production base `https://astronstudio-api-volces-prod.xf-yun.com/api/v1/model-manager`), which is the same document the AStudio UI renders. Authentication uses `modelBearerToken` from `astron-session.json` — a separate credential from the chat `experimental_bearer_token`.
|
|
168
|
+
|
|
169
|
+
> `/v1/models` is deliberately not used: that OpenAI-compatible discovery endpoint answers with a smaller, staler subset and would drop models that are in fact callable.
|
|
170
|
+
|
|
171
|
+
Catalog parsing rules:
|
|
172
|
+
|
|
173
|
+
- Only models with `visibility` of `list` are kept; those with `supported_in_api` of `false` are dropped;
|
|
174
|
+
- Context window and max output come from the upstream's real values (e.g. `spark-x2.6-preview` is 262144 / 100000);
|
|
175
|
+
- The upstream's `none` in `supported_reasoning_levels` is translated into a "thinking can be switched off" capability flag rather than treated as an effort level;
|
|
176
|
+
- When merging, the built-in roster's order and names win; models unique to the upstream are appended at the end.
|
|
177
|
+
|
|
178
|
+
**Fallback order**:
|
|
179
|
+
|
|
180
|
+
1. Live catalog
|
|
181
|
+
2. Last successful snapshot
|
|
182
|
+
3. Built-in roster
|
|
183
|
+
|
|
184
|
+
Snapshots are written to `$DSH_HOME/.astudio-connect/catalog.json`, stored per local identity. The catalog source (`live` / `saved` / `fallback`) and the fetch time are both shown on the settings card.
|
|
185
|
+
|
|
186
|
+
The current built-in roster covers:
|
|
187
|
+
|
|
188
|
+
- **Reasoning models**: `spark-x2.5`, `spark-x2.6-preview` (thinking switchable, `low` / `high` / `max`)
|
|
189
|
+
- **Chat models**: `spark-x2.5-4b`, `xopglm52`, `xopdeepseekv4pro`, `xopdeepseekv4pro0813`, `xopdsv4flash0731in`, `astronclaw-auto`
|
|
190
|
+
|
|
191
|
+
## Reasoning Effort and Probing
|
|
192
|
+
|
|
193
|
+
For WorkBuddy-style upstreams, reasoning-level information is scattered across upstream endpoints and the client's private UI logic, and the model roster changes quickly. If the plugin backfilled a uniform level for every model that declares none, it would have to keep chasing undocumented product logic with no stable contract.
|
|
194
|
+
|
|
195
|
+
Testing also shows that some models accept the `reasoning_effort` parameter yet may ignore unknown values and fall back to default behaviour — a single successful response does not prove a level is genuinely available.
|
|
196
|
+
|
|
197
|
+
So this plugin uses a **user-consented, dynamically discovered** approach:
|
|
198
|
+
|
|
199
|
+
1. The Probe section of the settings card offers Probe / Re-probe for models with no declared levels;
|
|
200
|
+
2. Clicking sends a minimal request carrying a sentinel string (`max_tokens: 1`, 30 second per-request timeout);
|
|
201
|
+
3. Upstream accepts → recorded as `validating`, storing only the accepted levels; upstream rejects with `invalid_parameter_value` → recorded as `rejected` / `non-validating`;
|
|
202
|
+
4. Results are persisted per `account:modelId` and expire after 24 hours.
|
|
203
|
+
|
|
204
|
+
Probing consumes a small amount of points. A result only means the current upstream accepts that level — **it does not promise that reasoning quality, speed, or point consumption will change**.
|
|
205
|
+
|
|
206
|
+
The mapping from `reasoning_effort` to pi-ai levels only exposes levels the upstream declared; `off` is exposed only when the model declares `none` (i.e. thinking can be switched off).
|
|
207
|
+
|
|
208
|
+
## Model Visibility
|
|
209
|
+
|
|
210
|
+
In the Context section of the settings card you can check which models appear in the model picker. Visibility preferences are written to `$DSH_HOME/.astudio-connect/model-visibility.json`, stored per local identity.
|
|
211
|
+
|
|
212
|
+
- **Only affects selectability**: hidden models do not appear in the picker, in `listModels()`, or in the shim's `/v1/models`; but sessions already using that model are unaffected, and `resolveModel()` does not filter.
|
|
213
|
+
- **New accounts and newly listed models are visible by default.**
|
|
214
|
+
|
|
215
|
+
AStudio's token carries no stable uid, so this plugin has a single local identity, `astudio-local` — catalog snapshots, visibility preferences and probe records all hang off it, with no multi-account isolation.
|
|
216
|
+
|
|
217
|
+
## Points Balance Badge
|
|
218
|
+
|
|
219
|
+
With an AStudio model selected, the composer's tool row (beside the model picker) shows the account's two points balances, with a ↻ manual refresh on the right:
|
|
220
|
+
|
|
221
|
+
```
|
|
222
|
+
General 1393 · Spark 24621
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
The two balances are shown separately and are **never added together**, because they pay for different things:
|
|
226
|
+
|
|
227
|
+
- **General points** (`totalBalance`): every model, plus plugins and Skill calls.
|
|
228
|
+
- **Spark points** (`sparkTotalBalance`): Spark-branded models only.
|
|
229
|
+
|
|
230
|
+
The data comes from the account endpoint the AStudio desktop app itself uses (`https://agent.xfyun.cn/xingchen-studio/points/balance`). AStudio's settings page requests its own loopback service, which forwards to the account API carrying the desktop session cookie; this plugin reaches the same upstream directly using the `ssoSessionId` already present in `astron-session.json`, so it **adds no location discovery and does not require AStudio to be running**.
|
|
231
|
+
|
|
232
|
+
> `ssoSessionId`, the `modelBearerToken` used by the catalog, and the chat `experimental_bearer_token` all live in the same file — but they are three credentials for three different purposes.
|
|
233
|
+
|
|
234
|
+
Behaviour guarantees:
|
|
235
|
+
|
|
236
|
+
- **Read timing**: once when the badge appears, and again when you click ↻. **No timed polling** — every read hits the upstream.
|
|
237
|
+
- **Visibility**: appears only when an AStudio model is selected in the current session; no request is issued under a provider-independent model.
|
|
238
|
+
- **Never shows a fabricated number on failure**: if the balance cannot be read it degrades instead of rendering "unreadable" as `0`.
|
|
239
|
+
- **30 second cache**: successful reads are cached for 30 seconds; ↻ sends `?refresh=1` to bypass the cache. Failures are not cached — the next read asks the upstream again.
|
|
240
|
+
|
|
241
|
+
| Situation | Display |
|
|
242
|
+
|---|---|
|
|
243
|
+
| Network failure / upstream error | "Unavailable", ↻ retries |
|
|
244
|
+
| Sign-in expired (upstream `code: 80000`, or 401/403) | "Sign-in expired" — sign in to AStudio again |
|
|
245
|
+
| Account has no Spark pool | Only general points are shown; no `0` |
|
|
246
|
+
| The balance really is 0 | Shows `0` normally (0 is a real balance, not "unknown") |
|
|
247
|
+
| Never signed in to AStudio | The badge does not appear at all |
|
|
248
|
+
|
|
249
|
+
> **Known limitation**: the account endpoint only provides aggregate balances, with no per-transaction detail — the AStudio desktop app itself is the same way (it directs users to the web to view details). So the badge can reflect *balance changes* but cannot say *exactly how much this conversation consumed*.
|
|
250
|
+
|
|
251
|
+
If the badge shows "Unavailable" and clicking ↻ does nothing, first confirm the plugin artifacts match the running DSH version: DSH loads plugins at startup, so after rebuilding you must **fully quit and restart DSH** (refreshing the page is not enough).
|
|
252
|
+
|
|
253
|
+
## Settings Card
|
|
254
|
+
|
|
255
|
+
Sidebar **Plugins** panel → AStudio Connect. One card split into three sections, switching between Chinese and English with the plugin language:
|
|
256
|
+
|
|
257
|
+
- **Account**: sign-in state, config file path, catalog source (live / saved / built-in), model count, and a one-click catalog refresh.
|
|
258
|
+
- **Context**: each model's context window and max output, plus the model visibility toggles.
|
|
259
|
+
- **Probe**: probe state and accepted levels for models with no declared levels, with manual probe / re-probe.
|
|
260
|
+
|
|
261
|
+
The card reads the status document once on mount and then every 60 seconds; all data comes from the same-origin `GET /astudio/status` and carries no credential material.
|
|
262
|
+
|
|
263
|
+
### Same-origin routes
|
|
264
|
+
|
|
265
|
+
| Path | Method | Purpose | Guards |
|
|
266
|
+
|---|---|---|---|
|
|
267
|
+
| `/astudio/status` | `GET` | Status document | loopback Host + Origin |
|
|
268
|
+
| `/astudio/points` | `GET` | Points balance (`?refresh=1` bypasses the cache) | loopback Host + Origin |
|
|
269
|
+
| `/astudio/update` | `GET` | Version and update info | loopback Host + Origin |
|
|
270
|
+
| `/astudio/probe/{modelId}` | `POST` | Reasoning-effort probing | loopback Host + Origin + in-process probe key |
|
|
271
|
+
|
|
272
|
+
The probe route separately requires an in-process key (handed out with the status document, rotated per process, never persisted): the status route's loopback check stops a DNS-rebinding **page**, and that is not the same as authorising a **state-changing** action.
|
|
273
|
+
|
|
274
|
+
## Update Check and Host Heartbeat
|
|
275
|
+
|
|
276
|
+
**Update check** (`update.ts`): reads npm's public dist-tags first to decide whether an update exists — looking only at the `latest` tag, since pre-release channels are not this plugin's release line; only once an update is confirmed does it query GitHub releases for the version notes. Both requests have a timeout (8 seconds) and a response body size cap, and the browser re-validates the version numbers, release URL and range with `parseAStudioUpdateResult` before rendering; any mismatch suppresses rendering.
|
|
277
|
+
|
|
278
|
+
**Host heartbeat** (`host-heartbeat.ts`): after the plugin registers the provider, it writes a JSON document containing `pid` and `registeredAt` to `$DSH_HOME/.astudio-host-heartbeat.json`; the host deletes it on `ctx.dispose()`.
|
|
279
|
+
|
|
280
|
+
The heartbeat distinguishes "the host is still running" from "the host crashed and left the file behind". Checking the PID alone is not enough — after a crash the OS may hand the same PID to an unrelated process, and that uncleared heartbeat would falsely report "host alive". So the condition is that the PID exists **and** the process holding it started no later than `registeredAt`; when the start time cannot be read, it degrades to a plain PID check.
|
|
281
|
+
|
|
282
|
+
The browser half writes no files and reports failure only through `console.error`. That asymmetry is intentional: the host is the load-bearing half, and a missing heartbeat unambiguously means the host never started.
|
|
283
|
+
|
|
284
|
+
## Location Discovery (Windows)
|
|
285
|
+
|
|
286
|
+
The plugin does not assume AStudio lives at a fixed path. It locates the data directory in this order:
|
|
287
|
+
|
|
288
|
+
1. A path explicitly set in the `configPath` setting (used verbatim, not probed)
|
|
289
|
+
2. The `ASTUDIO_DATA_HOME` environment variable (used verbatim, not probed)
|
|
290
|
+
3. AStudio's own registry record: `ProductionDataRoot` / `ProductionAcodeHome` under `HKCU\Software\AStudioStorage`
|
|
291
|
+
4. The `<install directory name> Data` directory beside the install directory
|
|
292
|
+
|
|
293
|
+
Item 3 is the record AStudio itself writes, so moving drives or reinstalling needs no configuration at all. A record that exists but is incomplete or of an unsupported schema version raises an explicit error rather than silently degrading to "not connected" — an older install this plugin cannot read must not win over a newer one.
|
|
294
|
+
|
|
295
|
+
Registry value-name prefixes are split by release channel: `production` → `Production*`, `canary` → `Canary*`, `development` → `Development*`; item 4's directory name follows as `AStudio Data` / `AStudio Canary Data` / `AStudio Dev Data`.
|
|
296
|
+
|
|
297
|
+
Automatic discovery is not implemented on non-Windows platforms; set `ASTUDIO_DATA_HOME` explicitly there.
|
|
298
|
+
|
|
299
|
+
## DSH Version Support
|
|
300
|
+
|
|
301
|
+
The plugin declares host dependencies in two places, both pinned to seam package version **`0.2.0-rc.2`**.
|
|
302
|
+
|
|
303
|
+
**Host-side `peerDependencies`** (run in the host process):
|
|
304
|
+
|
|
305
|
+
| Package | Purpose |
|
|
306
|
+
|---|---|
|
|
307
|
+
| `dsh-llm` / `dsh-llm-pi-ai` | Register the `astudio` provider |
|
|
308
|
+
| `dsh-host-webserver` | Routes for the settings card and points badge |
|
|
309
|
+
| `dsh-settings` | Plugin configuration |
|
|
310
|
+
| `dsh-home-paths` | Where snapshots, visibility preferences and the heartbeat are written |
|
|
311
|
+
| `dsh-attachment` | Attachment passing |
|
|
312
|
+
| `@deepseek-ai/cordis` | `^4.0.2` (`4.x`) |
|
|
313
|
+
| `@deepseek-ai/schemastery` | `^3.18.2` |
|
|
314
|
+
| `react` | `^18.2.0` |
|
|
315
|
+
|
|
316
|
+
**Browser-side `dsh.client.inject`** (host packages the client bundle depends on):
|
|
317
|
+
|
|
318
|
+
`dsh-client-ui-renderer`, `dsh-client-ui-conversation`, `dsh-client-ui-model-selection`, `dsh-client-locale`, `dsh-api-remotes`, `dsh-api-session-controller`.
|
|
319
|
+
|
|
320
|
+
| Status | Version | Notes |
|
|
321
|
+
|---|---|---|
|
|
322
|
+
| **Supported** | DSH Desktop **2.0.17** (seam `0.2.0-rc.2`) | Current development and verification environment: provider registration, settings card and points badge all confirmed on a real machine |
|
|
323
|
+
|
|
324
|
+
## Known Limitations
|
|
325
|
+
|
|
326
|
+
- [ ] **Image input is not enabled yet**: the adapter already maps a model to `input: ['text', 'image']` based on the catalog declaration, but model-manager parsing currently hardcodes `supportsImages: false` (and the upstream document has no corresponding field), so every model accepts plain text only.
|
|
327
|
+
- [ ] **The update check requires the package to be published on npm**: the version judgement reads npm's public dist-tags, so with the package unpublished that step 404s and the check is always "unavailable". The repository URL also once named a nonexistent org, making the GitHub release enrichment 404 as well; both are corrected in `src/version.ts` and `package.json`'s `repository`. The enrichment path only takes effect once the package is published.
|
|
328
|
+
- [ ] **Automatic location discovery is implemented only on Windows**: macOS / Linux need `ASTUDIO_DATA_HOME` set explicitly.
|
|
329
|
+
- [ ] **A single local identity**: AStudio's token carries no stable uid, so catalog snapshots, visibility preferences and probe records all hang off `astudio-local`, with no multi-account isolation.
|
|
330
|
+
- [ ] **No per-transaction billing detail**: the account endpoint only provides aggregate balances, so the badge can only reflect balance changes.
|
|
331
|
+
- [ ] **No long-term compatibility guarantee for upstream private endpoints**: the model catalog, account endpoint and reasoning-level information are the AStudio client's own interfaces rather than an official open API, and upstream changes may break the plugin. In that case it degrades through "last successful catalog → built-in roster" and labels the source on the card, but long-term compatibility cannot be promised.
|
|
332
|
+
- [ ] **The CLI's `status` does not reflect the live catalog**: see the note in [Command Line](#command-line).
|
|
333
|
+
- [ ] **No account-switch following**: unlike WorkBuddy's two variants, AStudio is a single product, so the plugin does not replicate variant-level capabilities.
|
|
334
|
+
|
|
335
|
+
## Security
|
|
336
|
+
|
|
337
|
+
- Credentials are cached only in memory and never written to any file; points reads re-read the session file every time (so an AStudio re-login takes effect immediately) but only take `ssoSessionId`.
|
|
338
|
+
- The shim binds only to `127.0.0.1` and accepts no external network access.
|
|
339
|
+
- Inbound requests must pass four checks: Host, Origin, Content-Type and the Bearer shared secret; the Host check blocks DNS rebinding.
|
|
340
|
+
- The shared secret is a random 32-byte value generated per process, compared in constant time with `timingSafeEqual`; the real AStudio token is resolved by the credential layer alone and never travels in a request header.
|
|
341
|
+
- Tokens are never echoed in any UI or log; the CLI strips JWT-shaped strings from error text.
|
|
342
|
+
- The points route and the status route apply the same loopback Host / Origin double check; responses contain only numbers and state, and account credentials stay inside the host process.
|
|
343
|
+
- Every upstream response is treated as untrusted input: streaming reads carry size caps, and route responses are re-validated in the browser before rendering.
|
|
344
|
+
|
|
345
|
+
## Development
|
|
346
|
+
|
|
347
|
+
```bash
|
|
348
|
+
npm install
|
|
349
|
+
npm run check # typecheck + test + build
|
|
350
|
+
npm test # run 263 tests (28 test files)
|
|
351
|
+
npm run build # produce lib/ (the directory DSH actually loads)
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
In `lib/`, `index.js` is the host entry, `client.js` is the browser half, and `bin.js` is the command line. Host and runtime dependencies (pi-ai, cordis, schemastery, the `dsh-*` packages) are all declared external and not bundled, avoiding duplication with the host modules in the profile; the browser side keeps only React as a runtime dependency.
|
|
355
|
+
|
|
356
|
+
Strict TypeScript, with `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` enabled.
|
|
357
|
+
|
|
358
|
+
## Disclaimer
|
|
359
|
+
|
|
360
|
+
This project is **for personal learning and research only**. It drives only the user's own AStudio account on the local machine — do not use it commercially or beyond reasonable personal use.
|
|
361
|
+
|
|
362
|
+
Users must comply with AStudio's terms of service; any consequence arising from use of this project (including but not limited to account restrictions, cleared credits, or service interruption) is borne by the user alone.
|
|
363
|
+
|
|
364
|
+
The authors accept no liability for any direct or indirect damages arising from the use or misuse of this project.
|
|
365
|
+
|
|
366
|
+
This project is not affiliated with, authorised by, or endorsed by iFLYTEK, AStudio, or DeepSeek. Names appearing in this document are used only to describe compatibility; their trademark rights belong to their respective owners.
|
|
367
|
+
|
|
368
|
+
## Related Projects / Community Ecosystem
|
|
369
|
+
|
|
370
|
+
- **[corrinehu/dsh-workbuddy-connect](https://github.com/corrinehu/dsh-workbuddy-connect)** (MIT) — the sibling DSH bridge plugin, aimed at the WorkBuddy desktop app. This project follows its overall structure, with AStudio's maas-api as the upstream instead.
|
|
371
|
+
|
|
372
|
+
Refer to that project's own documentation for supported versions and installation requirements. It is maintained independently by a third party; listing it is not an endorsement, and is not a stability or compatibility promise about this plugin's internal interfaces.
|
|
373
|
+
|
|
374
|
+
## Acknowledgements
|
|
375
|
+
|
|
376
|
+
- **[corrinehu/dsh-workbuddy-connect](https://github.com/corrinehu/dsh-workbuddy-connect)** (MIT) — the overall structure, the settings card sections, the reasoning-effort probing and the command-line design of this project are all implemented following it.
|
|
377
|
+
|
|
378
|
+
## License
|
|
379
|
+
|
|
380
|
+
[MIT](./LICENSE)
|