@huaweidevtools/aishell-dsh-llm 0.0.1-beta.1 → 0.0.1-beta.3

package/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2024 Huawei Cloud AI Shell
+   Copyright 2026 Huawei Cloud AI Shell
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -2,6 +2,12 @@
 
 OpenAI-compatible LLM adapter for DSH. Registers the `aishell` provider route on `ctx.llm`, routing model calls through the aishell gateway with direct AK/SK signing.
 
+Besides the live route, the plugin declares `aishell` in the configurable-provider directory (`ctx.llm.registerConfigurableProviders`) — the directory the Models page joins with live routes, so the route shows up as a configurable provider row with its own settings address. The plugin also carries a Config schema; the settings mirror only lists namespaces whose plugin declares one, so without it the Models page would not show the row.
+
+## The Models-page row
+
+The row itself is read-only: the profile has no fields the host editor knows how to write, and credentials are entered through the form the `aishell-credentials` chips open (the account chip beside the chat input, or the chip on a New Session page). The browser half therefore does not extend the row with a card — it shadows the row's header at runtime (`src/client/provider-row-shadow.ts`, the same approach `aishell-brand` uses for its digest-protected host residues): a status dot after the row's name (green when AK/SK are stored, warn when they are not, with the readiness copy as its hover title) and the header's Edit button hidden, because there is nothing to edit. A MutationObserver keeps the shadow applied across the page's re-renders; the shadow is re-installed on a locale switch so the hover copy follows the active language; disabling the plugin restores the official row exactly.
+
 ## How it works
 
 ```
@@ -9,7 +15,7 @@ User selects aishell/<model>
   → GatewayAdapter.stream(options)
 
   Every request is signed directly with AK/SK (SDK-HMAC-SHA256):
-    → credential store reads HW_ACCESS_KEY + HW_SECRET_KEY (+ optional HW_SECURITY_TOKEN)
+    → credential store reads the AK/SK pair (one record; optional STS token)
     → sign(POST, host, /chat/completions, query, body) → signed headers
     → POST {baseUrl}/chat/completions  (signed headers, OpenAI wire format)
     → parseSse → translate → StreamChunks
@@ -21,6 +27,29 @@ User selects aishell/<model>
 
 No intermediate API-key exchange or config fetch — every request is signed with the user's AK/SK. The credential store (OS keyring with fingerprint + memory fallback) holds the AK/SK; this adapter only reads them.
 
+## Image input
+
+The adapter carries images for models whose gateway catalog entry lists `image` in `modalities`. A model the catalog describes as text-only never receives one: `dsh-llm` projects such an image to a stable placeholder before the adapter sees it.
+
+For an image-capable model the pipeline is:
+
+```
+harness history (durable image *references*, not bytes)
+  → prepareRequestImages: one request version per attachment, via ctx.attachments
+  → byte budget check → IMAGE_OFFLOAD_REQUIRED when over
+  → projectOffloaded: occurrences an earlier offload decision marked
+  → serialize: [handle text, base64 data URL] parts on the user message
+```
+
+Two properties are worth knowing:
+
+- **Bytes are read from the attachment service, not the block.** An image block holds an opaque `attachmentId` that is deliberately neither a path nor a URL, so the adapter resolves bytes through `ctx.attachments.readImageRequest`, which also normalizes and re-encodes to the route's target size. A deployment without that service fails image requests with `UNSUPPORTED_CONTENT` rather than sending an empty turn.
+- **Tool-result images ride a separate user turn.** OpenAI's `tool` message takes text only, so an image a tool returned is hoisted into a following `user` message — the same shape the ecosystem's OpenAI-path serializer produces.
+
+Over-budget requests fail with `IMAGE_OFFLOAD_REQUIRED` and are retried by `@deepseek-ai/dsh-compaction-image-offload`, which `dsh-base` mounts: it marks the oldest occurrences offloaded, after which they travel as placeholder text. This adapter never offloads on its own.
+
+Image token accounting uses the token meter's structural estimate — this adapter implements no `imageRequestPricing`, matching `dsh-llm-pi-ai`. Image-heavy sessions are therefore approximated rather than priced per model.
+
 ## What it does NOT touch
 
 - `ctx.credentials` — DSH's own credential provider stays `dsh-credentials-local`. User-configured models and `.credentials.yaml` keep working.
@@ -41,23 +70,30 @@ dsh plugin --profile <name> add @huaweidevtools/aishell-dsh-base
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `baseUrl` | `string?` | `https://api.aishell.openbuildlab.com` | Chat API base URL. `/chat/completions` and `/models` are appended. |
-| `keyringService` | `string?` | `aishell-dsh` | Credential store service name. |
+| `baseUrl` | `string?` | `https://openai.aishell.openbuildlab.com/v1` | Chat API base URL. `/chat/completions` and `/models` are appended, so a base carrying its own path segment is signed and requested in full. |
+| `requestImagePixelBudget` | `number?` | `4194304` | Total-pixel cap one request image is scaled into. |
+| `requestImageMaxBytes` | `number?` | `1048576` | Encoded-byte target for one request image. |
+| `maxRequestImageBytes` | `number?` | `20971520` | Accumulated base64 image bytes one request accepts before the oldest images must be offloaded. |
+
+The three image fields share `dsh-llm-pi-ai`'s defaults: the gateway publishes no image budget of its own, so the route supplies one.
 
 ## Storing credentials
 
-**Web UI (recommended):** Install `aishell-credentials` (or the `aishell-base` bundle) — the Settings page gets an "AI Shell" section with AK/SK/SecurityToken input fields. Values are transferred to the credential store.
+**Web UI (recommended):** Install `aishell-credentials` (or the `aishell-base` bundle) — clicking the credentials button beside the chat input (or the one on a New Session page) opens a form with AK/SK/SecurityToken fields. Values are verified against Huawei Cloud IAM and transferred to the credential store; the button flips to the account name when they are stored.
 
 **CLI fallback:**
 
 ```sh
 node --input-type=module -e "
 import { createCredentialsStore } from '@huaweidevtools/aishell-dsh-credentials-store';
-const s = createCredentialsStore();
-s.set('HW_ACCESS_KEY', 'your-ak');
-s.set('HW_SECRET_KEY', 'your-sk');
-// Optional: temporary security token (STS)
-s.set('HW_SECURITY_TOKEN', 'your-token');
+import { writeHuaweiCloud } from '@huaweidevtools/aishell-dsh-credentials-store/accounts';
+
+// One record, one write. The pair and its optional STS token go in together.
+writeHuaweiCloud(createCredentialsStore(), {
+  ak: 'your-ak',
+  sk: 'your-sk',
+  // securityToken: 'your-token',   // only for temporary credentials
+});
 "
 ```
 

package/lib/client.js

@@ -0,0 +1,234 @@
+window.__ModuleLoader__.load({ id: "@huaweidevtools/aishell-dsh-llm", factory: (require) => {
+"use strict";
+var module = { exports: {} }; var exports = module.exports;
+
+//#region src/provider-name.ts
+/**
+* The aishell provider's display name, shared by both plugin halves.
+*
+* The Host half registers it on the configurable-provider directory (the
+* Models page renders it as the provider row's name), and the browser half's
+* row shadow finds that row by matching the rendered name against this
+* literal (see `client/provider-row-shadow.ts`). It must stay a single
+* literal string — the shadow compares `textContent` with it.
+*
+* It is also the name `providerInfo()` reports, so the picker and the Models
+* row call the route the same thing: this package's whole surface is one
+* product, and qualifying it by cloud ("AI Shell (Huawei Cloud)") added a
+* distinction no reader needed — there is no second AI Shell to tell it
+* apart from.
+*/
+const PROVIDER_DISPLAY_NAME = "AI Shell";
+
+//#endregion
+//#region src/client/provider-row-shadow.ts
+/** Marker attribute the dot carries (exposed for the spec). */
+const ROW_DOT_MARKER = "data-aishell-provider-dot";
+/** Marker attribute a hidden Edit button carries (exposed for the spec). */
+const ROW_EDIT_HIDDEN = "data-aishell-edit-hidden";
+/** The dot's own CSS: the host credential dot's geometry and palette. */
+const ROW_DOT_CSS = [
+	`[class*="rowIdentity"] [${ROW_DOT_MARKER}] {`,
+	"  box-sizing: border-box;",
+	"  border-radius: 50%;",
+	"  flex: none;",
+	"  width: 8px;",
+	"  height: 8px;",
+	"  display: inline-block;",
+	"}",
+	`[class*="rowIdentity"] [${ROW_DOT_MARKER}="ok"] {`,
+	"  background: var(--dsw-alias-state-success-primary);",
+	"}",
+	`[class*="rowIdentity"] [${ROW_DOT_MARKER}="warn"] {`,
+	"  background: var(--dsw-alias-state-warn-label);",
+	"}",
+	`[${ROW_EDIT_HIDDEN}] {`,
+	"  display: none !important;",
+	"}"
+].join("\n");
+/** Every Edit button an aishell row renders (there is ordinarily one; a
+* re-render that leaves a second copy gets both, so none stays visible). */
+function findEditButtons(row) {
+	const actions = row.querySelector("[class*=\"rowActions\"]");
+	if (actions === null) return [];
+	const found = [];
+	for (const button of actions.querySelectorAll("button")) {
+		const label = button.getAttribute("aria-label") ?? "";
+		if (label.includes(PROVIDER_DISPLAY_NAME) || button.textContent === "编辑") found.push(button);
+	}
+	return found;
+}
+/**
+* Whether `node` is an Element (`querySelectorAll` roots can be non-element
+* nodes like the Document, where the row check below simply answers false).
+*/
+function isElement(node) {
+	return node.nodeType === Node.ELEMENT_NODE;
+}
+/**
+* Whether `node` is a provider row whose rendered name is ours.
+*
+* Duck-typed on the attribute surface rather than `instanceof Element` so
+* the shadow works identically in the browser and under the specs' DOM
+* stub, which provides the attribute methods without the constructor.
+*/
+function isProviderRow(node) {
+	if (node.nodeType !== Node.ELEMENT_NODE) return false;
+	const element = node;
+	const name = element.querySelector("[class*=\"rowName\"]");
+	return name !== null && name.textContent === PROVIDER_DISPLAY_NAME;
+}
+/**
+* Apply the shadow to one row: add the dot (or repaint an existing one) and
+* hide the Edit button. Idempotent — a second pass rewrites the dot's
+* readiness instead of stacking another one.
+*
+* `target` is the owning document, passed in because the stub DOM the specs
+* run on keeps no `ownerDocument` link.
+*/
+function shadowRow(row, ready, titles, target) {
+	const identity = row.querySelector("[class*=\"rowIdentity\"]");
+	if (identity === null) return;
+	const state = ready ? "ok" : "warn";
+	const existing = identity.querySelector(`[${ROW_DOT_MARKER}]`);
+	const dot = existing ?? target.createElement("span");
+	dot.setAttribute(ROW_DOT_MARKER, state);
+	dot.setAttribute("title", titles[state]);
+	dot.setAttribute("aria-label", titles[state]);
+	if (existing === null) {
+		dot.setAttribute("role", "img");
+		identity.appendChild(dot);
+	}
+	for (const edit of findEditButtons(row)) edit.setAttribute(ROW_EDIT_HIDDEN, "");
+}
+/** Undo one row: remove the dot, restore the Edit button. */
+function unshadowRow(row) {
+	row.querySelectorAll(`[${ROW_DOT_MARKER}]`).forEach((dot) => {
+		dot.remove();
+	});
+	row.querySelectorAll(`[${ROW_EDIT_HIDDEN}]`).forEach((button) => {
+		button.removeAttribute(ROW_EDIT_HIDDEN);
+	});
+}
+/**
+* Install the provider-row shadow on a document.
+*
+* `ready` is the credential fact as the browser half derives it from the
+* settings namespace `aishell-credentials` owns (see `client/index.ts`);
+* `titles` is the dot's hover copy in the active locale (the installer
+* translates; this module holds only the DOM work). Neither is read from any
+* store here, so a later credential save or locale switch is a reinstall with
+* the new values, not a re-derivation buried in here. Sweeps the page once,
+* then observes the body so re-rendered rows are covered too. Returns the
+* disposer that stops the observer and restores every row.
+*/
+function installProviderRowShadow(target, ready, titles) {
+	if (typeof target.querySelector !== "function" || typeof MutationObserver !== "function") return () => {};
+	/** Run the shadow over every provider row at or below `root`. */
+	const sweep = (root) => {
+		if (isElement(root) && isProviderRow(root)) shadowRow(root, ready, titles, target);
+		for (const row of root.querySelectorAll("[class*=\"rowCard\"], [class*=\"setupCard\"]")) if (isProviderRow(row)) shadowRow(row, ready, titles, target);
+	};
+	const sweepIfRow = (node) => {
+		if (isProviderRow(node)) {
+			shadowRow(node, ready, titles, target);
+			return;
+		}
+		for (let parent = node.parentElement; parent !== null; parent = parent.parentElement) sweep(parent);
+	};
+	const style = target.createElement("style");
+	style.setAttribute(ROW_DOT_MARKER + "-css", "");
+	style.textContent = ROW_DOT_CSS;
+	target.head.appendChild(style);
+	sweep(target.body);
+	const observer = new MutationObserver((mutations) => {
+		for (const mutation of mutations) for (const node of mutation.addedNodes) if (node.nodeType === Node.ELEMENT_NODE) sweepIfRow(node);
+	});
+	observer.observe(target.body, {
+		childList: true,
+		subtree: true
+	});
+	return () => {
+		observer.disconnect();
+		style.remove();
+		for (const row of target.body.querySelectorAll("[class*=\"rowCard\"], [class*=\"setupCard\"]")) if (isProviderRow(row)) unshadowRow(row);
+	};
+}
+
+//#endregion
+//#region src/client/locales.ts
+/**
+* aishell-llm locale dictionaries — the Models-page provider row's copy.
+*
+* The row shadow is a DOM patch, not a React render, so its strings do not
+* ride the framework's locale seat: the install reads them through `t` at
+* install time and repaints on a locale switch (the client half re-installs
+* on `locale/change`). zh is the key-set source of truth; en mirrors it.
+*
+* @module @huaweidevtools/aishell-dsh-llm/client/locales
+*/
+/** Dictionary namespace owned by this plugin. */
+const NS = "aishell-llm";
+/** Simplified Chinese dictionary (the key-set source of truth). */
+const zh = {
+	"provider.ready": "已就绪",
+	"provider.warn": "未就绪 — 凭据未配置（点击对话输入框上方的凭据按钮填写 AK/SK）"
+};
+/** English dictionary. */
+const en = {
+	"provider.ready": "Ready",
+	"provider.warn": "Not ready — credentials missing (click the credentials button above the chat input to enter AK/SK)"
+};
+
+//#endregion
+//#region src/client/index.ts
+/** The settings namespace aishell-credentials owns (the shadow reads its status). */
+const AISHELL_CREDENTIALS_NS = "aishell-client-credentials";
+/** Required services. */
+const inject = ["configForms", "locale"];
+function apply(ctx) {
+	if (typeof document === "undefined") return;
+	ctx.effect(() => ctx.locale.register(NS, {
+		zh,
+		en
+	}), "aishell-llm: dictionaries");
+	const t = ctx.locale.bind(NS);
+	const form = ctx.configForms.get(AISHELL_CREDENTIALS_NS);
+	let readiness = form.getSnapshot().value?.credentialsStored === true;
+	let disposeShadow;
+	const titles = () => ({
+		ok: t("provider.ready"),
+		warn: t("provider.warn")
+	});
+	const sync = () => {
+		disposeShadow?.();
+		disposeShadow = installProviderRowShadow(document, readiness, titles());
+	};
+	const derive = () => {
+		const next = form.getSnapshot().value?.credentialsStored === true;
+		if (next !== readiness) {
+			readiness = next;
+			sync();
+		}
+	};
+	ctx.effect(() => ctx.configForms.whileServed([AISHELL_CREDENTIALS_NS], () => {
+		sync();
+		return () => {
+			disposeShadow?.();
+			disposeShadow = void 0;
+		};
+	}), "aishell-llm: models page provider row shadow");
+	ctx.effect(() => form.subscribe(derive), "aishell-llm: credential presence for the models row");
+	ctx.effect(() => ctx.on("locale/change", () => {
+		sync();
+	}), "aishell-llm: shadow locale repaint");
+}
+
+//#endregion
+exports.ROW_DOT_MARKER = ROW_DOT_MARKER
+exports.ROW_EDIT_HIDDEN = ROW_EDIT_HIDDEN
+exports.apply = apply
+exports.inject = inject
+exports.installProviderRowShadow = installProviderRowShadow
+return module.exports; } });
+//# sourceMappingURL=client.js.map