@lincyaw/addon-assistant 0.0.0-stage → 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @lincyaw/addon-assistant
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The readers' questions: readers ask about a lecture with their own model service.
+
+Part of [Presmium](https://github.com/Lincyaw/presmium), which compiles canonical lecture.json teaching documents into web pages, slides, Jupyter notebooks and narrated playback.
+
+## Install
+
+```sh
+pnpm add -D @lincyaw/addon-assistant
+```
+
+Add this package to `metadata.plugins` in the document's `lecture.json`.
+
+It is a Presmium plugin: its components work on the web page and in the slides. It needs `@lincyaw/cli` and the renderers in the same project, and declares the Presmium packages it shares with them as peer dependencies (Presmium 1.x).
+
+## What it provides
+
+An Ask panel on the web page, the slides and the presenter view, also in static sites: readers ask about a section or a selection, with an OpenAI compatible model service they set up in their browser; the site needs no server and no operator setting. Listed among a workspace's operator plugins, every document of the workspace has it.
+
+## Documentation
+
+- [Author guide](https://github.com/Lincyaw/presmium/blob/main/site/guide/locales/en/lecture.json) (Chinese: `site/guide/lecture.json`)
+- [Document contract](https://github.com/Lincyaw/presmium/blob/main/.agents/skills/presmium-author/references/document.md): normalized entities, parameters, states and shared validation
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@lincyaw/addon-assistant",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.1",
+  "description": "Presmium plugin: readers ask an AI about the lecture, with their own model service, in the browser",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lincyaw/presmium.git",
+    "directory": "packages/addon-assistant"
+  },
+  "homepage": "https://github.com/Lincyaw/presmium/tree/main/packages/addon-assistant#readme",
+  "bugs": "https://github.com/Lincyaw/presmium/issues",
+  "keywords": [
+    "presmium"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./domain": "./src/domain/index.ts",
+    "./client": "./src/client/index.ts",
+    "./presmium": "./src/node/presmium.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "eventsource-parser": "4.1.2"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "@lincyaw/kernel": "^1.0.0-rc.1",
+    "@lincyaw/host": "^1.0.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/react": "18.3.28",
+    "@types/react-dom": "^18.3.7",
+    "@lincyaw/host": "1.0.0-rc.1",
+    "@lincyaw/viewer": "1.0.0-rc.1",
+    "@lincyaw/kernel": "1.0.0-rc.1"
+  }
 }

package/src/client/AskPanel.css

@@ -0,0 +1,94 @@
+.pm-assistant {
+  display: grid;
+  gap: var(--pm-space-3);
+  color: var(--pm-color-ink);
+  font-family: var(--pm-font-sans);
+  font-size: var(--pm-text-md);
+  line-height: var(--pm-leading-ui);
+  text-align: left;
+  white-space: normal;
+  overflow-wrap: anywhere;
+}
+.pm-assistant p {
+  margin: 0;
+}
+.pm-assistant__provider,
+.pm-assistant__where,
+.pm-assistant__status {
+  color: var(--pm-color-muted);
+  font-size: var(--pm-text-sm);
+}
+.pm-assistant__provider {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--pm-space-2);
+}
+.pm-assistant__form {
+  display: grid;
+  gap: var(--pm-space-2);
+}
+.pm-assistant__selection {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--pm-space-2);
+  padding: var(--pm-space-2) var(--pm-space-3);
+  border-radius: var(--pm-radius-control);
+  background: var(--pm-color-selected);
+}
+.pm-assistant__selection code {
+  max-width: 100%;
+  white-space: pre-wrap;
+}
+.pm-assistant textarea {
+  width: 100%;
+}
+.pm-assistant__actions {
+  display: flex;
+  justify-content: flex-end;
+}
+.pm-assistant__answers {
+  display: grid;
+  gap: var(--pm-space-3);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.pm-assistant__answers > li {
+  display: grid;
+  gap: var(--pm-space-2);
+}
+.pm-assistant__question {
+  justify-self: end;
+  max-width: 85%;
+  padding: var(--pm-space-2) var(--pm-space-3);
+  border-radius: var(--pm-radius-card);
+  background: var(--pm-color-accent-soft);
+  font-weight: 500;
+}
+.pm-assistant__answer {
+  font-family: var(--pm-font-serif);
+  font-size: var(--pm-text-lg);
+  line-height: 1.7;
+  white-space: pre-wrap;
+}
+.pm-assistant__cite {
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--pm-color-accent);
+  font: inherit;
+  text-decoration: underline;
+  text-underline-offset: var(--pm-size-stroke);
+  cursor: pointer;
+}
+.pm-assistant__cite:focus-visible {
+  outline: var(--pm-size-stroke) solid var(--pm-color-accent);
+  outline-offset: var(--pm-size-stroke);
+}
+.pm-assistant__error {
+  color: var(--pm-color-danger);
+}

package/src/client/AskPanel.tsx

@@ -0,0 +1,195 @@
+import { Fragment, useState, useRef, useEffect, useMemo, useId } from 'react'
+import type { ReactNode } from 'react'
+import { PmButton, useMessages, useStore } from '@lincyaw/host'
+import type { AgentContext, Citation } from '@lincyaw/kernel'
+import { answerParts, askProvider, ASSISTANT_MESSAGES } from '../domain/index.ts'
+import AskSettings from './AskSettings.tsx'
+import { askSettings as settingsStore } from './settings.ts'
+import {
+  askClient as clientStore,
+  exchanges as exchangesStore,
+  selected as selectionStore,
+  showCitation,
+  slideNavigation as navigationStore,
+  startExchange,
+  useWebViewerAccess,
+} from './state.ts'
+import './AskPanel.css'
+export default function AskPanel(props: {
+  children?: ReactNode
+  className?: string
+  onDone?(): void
+  onCited?(): void
+}) {
+  const t = useMessages(ASSISTANT_MESSAGES)
+  const askSettings = useStore(settingsStore)
+  const askClient = useStore(clientStore)
+  const exchanges = useStore(exchangesStore)
+  const selected = useStore(selectionStore)
+  const slideNavigation = useStore(navigationStore)
+  const webViewer = useWebViewerAccess()
+  const [text, setText] = useState('')
+  const [changing, setChanging] = useState(false)
+  const running = exchanges.some((e) => e.state === 'running')
+  const service = askSettings && { provider: askProvider(askSettings.url), model: askSettings.model }
+  const canShowCitations = Boolean(webViewer ?? slideNavigation)
+
+  const place = (() => {
+    const position = webViewer?.position() ?? slideNavigation?.position.getSnapshot()
+    const section = selected?.section ?? position?.section
+    return section
+      ? {
+          section,
+          step: position?.section === section ? position.step : undefined,
+          title: webViewer?.title(section) ?? section,
+        }
+      : undefined
+  })()
+  const excerpt = (() => {
+    const value = selected?.text ?? ''
+    return value.length > 120 ? `${value.slice(0, 120)}…` : value
+  })()
+
+  function submit(): void {
+    const question = text.trim()
+    const client = askClient
+    if (!question || !client) return
+    const context: AgentContext = {
+      document: '',
+      ...(place ? { section: place.section } : {}),
+      ...(place?.step !== undefined ? { step: place.step } : {}),
+      ...(selected?.block ? { block: selected.block } : {}),
+      ...(selected ? { selection: selected.text } : {}),
+    }
+    startExchange(client, question, context)
+    setText('')
+    selectionStore.set(undefined)
+  }
+
+  function drop(): void {
+    selectionStore.set(undefined)
+  }
+
+  function go(citation: Citation): void {
+    showCitation(citation)
+    props.onCited?.()
+  }
+
+  return (
+    <>
+      <div className="pm-assistant">
+        {!service || changing ? (
+          <AskSettings
+            onDone={() => {
+              setChanging(false)
+            }}
+          ></AskSettings>
+        ) : (
+          <>
+            <p className="pm-assistant__provider">
+              <span>{t.panel.provider(service.provider, service.model)}</span>
+              <PmButton
+                className="pm-assistant__service"
+                variant="ghost"
+                small
+                icon="sliders"
+                onClick={(event) => {
+                  setChanging(true)
+                }}
+              >
+                {t.panel.service}
+              </PmButton>
+            </p>
+            <form
+              className="pm-assistant__form"
+              onSubmit={(event) => {
+                event.preventDefault()
+                submit()
+              }}
+            >
+              {selected ? (
+                <p className="pm-assistant__selection">
+                  <span>{t.panel.selection}</span>
+                  <code className="pm-ui-code">{excerpt}</code>
+                  <PmButton variant="ghost" small onClick={drop}>
+                    {t.panel.dropSelection}
+                  </PmButton>
+                </p>
+              ) : null}
+              {place ? <p className="pm-assistant__where">{t.panel.at(place.title)}</p> : null}
+              <textarea
+                value={text}
+                onChange={(event) => setText(event.target.value)}
+                className="pm-ui-textarea"
+                aria-label={t.panel.question}
+                placeholder={t.panel.placeholder}
+                rows={3}
+                maxLength={2000}
+                onKeyDown={(event) => {
+                  event.stopPropagation()
+                }}
+              ></textarea>
+              <p className="pm-assistant__actions">
+                <PmButton type="submit" variant="primary" small disabled={!text.trim() || running}>
+                  {t.panel.ask}
+                </PmButton>
+              </p>
+            </form>
+          </>
+        )}
+        {exchanges.length ? (
+          <ol className="pm-assistant__answers" aria-label={t.panel.answers}>
+            {exchanges.map((exchange) => (
+              <li key={exchange.id} data-state={exchange.state}>
+                <p className="pm-assistant__question">{exchange.question}</p>
+                {exchange.answer ? (
+                  <p className="pm-assistant__answer">
+                    {answerParts(exchange.answer).map((part, j) => (
+                      <>
+                        {part.citation && canShowCitations ? (
+                          <button
+                            type="button"
+                            className="pm-assistant__cite"
+                            data-section={part.citation.section}
+                            title={t.panel.cite(part.text)}
+                            onClick={(event) => {
+                              go(part.citation!)
+                            }}
+                          >
+                            {part.text}
+                          </button>
+                        ) : (
+                          <span>{part.text}</span>
+                        )}
+                      </>
+                    ))}
+                  </p>
+                ) : null}
+                {exchange.state === 'running' ? (
+                  <p className="pm-assistant__status" role="status">
+                    {t.panel.answering}
+                    <PmButton
+                      variant="ghost"
+                      small
+                      onClick={(event) => {
+                        exchange.cancel()
+                      }}
+                    >
+                      {t.panel.cancel}
+                    </PmButton>
+                  </p>
+                ) : exchange.cancelled ? (
+                  <p className="pm-assistant__status">{t.panel.cancelled}</p>
+                ) : exchange.state === 'failed' ? (
+                  <p className="pm-assistant__error" role="alert">
+                    {t.panel.failed(exchange.error ?? '')}
+                  </p>
+                ) : null}
+              </li>
+            ))}
+          </ol>
+        ) : null}
+      </div>
+    </>
+  )
+}

package/src/client/AskSettings.css

@@ -0,0 +1,25 @@
+.pm-assistant-settings {
+  display: grid;
+  gap: var(--pm-space-3);
+}
+.pm-assistant-settings p {
+  margin: 0;
+}
+.pm-assistant-settings__title {
+  margin: 0;
+  font-family: var(--pm-font-serif);
+  font-size: var(--pm-text-title);
+  font-weight: 600;
+  line-height: var(--pm-leading-tight);
+}
+.pm-assistant-settings__intro {
+  color: var(--pm-color-muted);
+}
+.pm-assistant-settings__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--pm-space-2);
+}
+.pm-assistant-settings__problem {
+  color: var(--pm-color-danger);
+}

package/src/client/AskSettings.tsx

@@ -0,0 +1,122 @@
+import { Fragment, useState, useRef, useEffect, useMemo, useId } from 'react'
+import type { ReactNode } from 'react'
+import { PmButton, PmField, PmNotice, useMessages, useStore } from '@lincyaw/host'
+import { ASSISTANT_MESSAGES, isAskUrlValid } from '../domain/index.ts'
+import { askSettings as settingsStore, saveAskSettings } from './settings.ts'
+import './AskSettings.css'
+export default function AskSettings(props: {
+  children?: ReactNode
+  className?: string
+  onDone?(): void
+  onCited?(): void
+}) {
+  const t = useMessages(ASSISTANT_MESSAGES)
+  const askSettings = useStore(settingsStore)
+  const [url, setUrl] = useState(askSettings?.url ?? '')
+  const [key, setKey] = useState(askSettings?.key ?? '')
+  const [model, setModel] = useState(askSettings?.model ?? '')
+  const [problem, setProblem] = useState('')
+
+  function save(): void {
+    if (!isAskUrlValid(url.trim())) {
+      setProblem(t.ask.invalidUrl)
+      return
+    }
+    saveAskSettings({ url: url.trim(), key: key.trim(), model: model.trim() })
+    props.onDone?.()
+  }
+
+  function clear(): void {
+    saveAskSettings(undefined)
+    setUrl('')
+    setKey('')
+    setModel('')
+  }
+
+  return (
+    <>
+      <form
+        className="pm-assistant-settings"
+        aria-label={t.ask.title}
+        onSubmit={(event) => {
+          event.preventDefault()
+          save()
+        }}
+      >
+        <h3 className="pm-assistant-settings__title">{t.ask.title}</h3>
+        <p className="pm-assistant-settings__intro">{t.ask.intro}</p>
+        <PmNotice className="pm-assistant-settings__storage" tone="warn">
+          {t.ask.storage}
+        </PmNotice>
+        <PmField label={t.ask.url}>
+          <input
+            value={url}
+            onChange={(event) => setUrl(event.target.value)}
+            className="pm-ui-input"
+            name="url"
+            type="url"
+            required
+            placeholder={t.ask.urlPlaceholder}
+            autoComplete="off"
+            spellCheck={false}
+            onKeyDown={(event) => {
+              event.stopPropagation()
+            }}
+          ></input>
+        </PmField>
+        <PmField label={t.ask.key}>
+          <input
+            value={key}
+            onChange={(event) => setKey(event.target.value)}
+            className="pm-ui-input"
+            name="key"
+            type="password"
+            required
+            autoComplete="off"
+            spellCheck={false}
+            onKeyDown={(event) => {
+              event.stopPropagation()
+            }}
+          ></input>
+        </PmField>
+        <PmField label={t.ask.model}>
+          <input
+            value={model}
+            onChange={(event) => setModel(event.target.value)}
+            className="pm-ui-input"
+            name="model"
+            type="text"
+            required
+            placeholder={t.ask.modelPlaceholder}
+            autoComplete="off"
+            spellCheck={false}
+            onKeyDown={(event) => {
+              event.stopPropagation()
+            }}
+          ></input>
+        </PmField>
+        {problem ? <p className="pm-assistant-settings__problem">{problem}</p> : null}
+        <p className="pm-assistant-settings__actions">
+          <PmButton type="submit" variant="primary" small>
+            {t.ask.save}
+          </PmButton>
+          {askSettings ? (
+            <PmButton
+              small
+              onClick={(event) => {
+                props.onDone?.()
+              }}
+            >
+              {t.ask.cancel}
+            </PmButton>
+          ) : null}
+          {askSettings ? (
+            <PmButton variant="danger" small onClick={clear}>
+              {t.ask.clear}
+            </PmButton>
+          ) : null}
+        </p>
+      </form>
+    </>
+  )
+}

package/src/client/AssistantToolbar.css

@@ -0,0 +1,20 @@
+.pm-assistant-toolbar {
+  display: inline-flex;
+  align-items: center;
+}
+.pm-assistant-popover__close {
+  margin-top: var(--pm-space-3);
+}
+.pm-assistant-popover {
+  box-sizing: border-box;
+  width: min(28rem, calc(100vw - 2rem));
+  max-height: 80vh;
+  margin: 0;
+  overflow: auto;
+  padding: var(--pm-space-4);
+  border: var(--pm-size-hairline) solid var(--pm-color-line);
+  border-radius: var(--pm-radius-card);
+  background: var(--pm-color-surface);
+  box-shadow: var(--pm-shadow-float);
+  white-space: normal;
+}

package/src/client/AssistantToolbar.tsx

@@ -0,0 +1,33 @@
+import { useState } from 'react'
+import { PmButton, PmPopover, useMessages } from '@lincyaw/host'
+import { ASSISTANT_MESSAGES as MESSAGES } from '../domain/index.ts'
+import { useWebViewerAccess } from './state.ts'
+import AskPanel from './AskPanel.tsx'
+import './AssistantToolbar.css'
+export default function AssistantToolbar() {
+  const t = useMessages(MESSAGES)
+  const [open, setOpen] = useState(false)
+  useWebViewerAccess()
+  return (
+    <span className="pm-assistant-toolbar">
+      {true && (
+        <PmPopover
+          open={open}
+          onOpenChange={setOpen}
+          label={t.panel.title}
+          name="pm-assistant-popover"
+          trigger={
+            <PmButton variant="ghost" small title={t.toolbar.title} aria-expanded={open}>
+              {t.toolbar.button}
+            </PmButton>
+          }
+        >
+          <AskPanel onCited={() => setOpen(false)} />
+          <PmButton small className="pm-assistant-popover__close" onClick={() => setOpen(false)}>
+            {t.panel.close}
+          </PmButton>
+        </PmPopover>
+      )}
+    </span>
+  )
+}

package/src/client/chat-client.ts

@@ -0,0 +1,90 @@
+import { EventSourceParserStream } from 'eventsource-parser/stream'
+import { currentLocale } from '@lincyaw/host'
+import type { Navigation } from '@lincyaw/host'
+import type { AgentContext, AskClient } from '@lincyaw/kernel'
+import { askMessages, askProvider, completionsUrl, completionText, sectionText, serviceError, streamDelta } from '../domain/index.ts'
+import type { AskPlace } from '../domain/index.ts'
+import { askSettings } from './settings.ts'
+import type { WebViewerAccess } from './state.ts'
+
+function placeOf(context: AgentContext, webViewer: WebViewerAccess | undefined, slideNavigation: Navigation | undefined): AskPlace {
+  const selection = context.selection ? { selection: context.selection } : {}
+  const doc = webViewer?.doc()
+  if (doc) {
+    const section = context.section === undefined ? undefined : doc.sections.find(s => s.id === context.section)
+    return {
+      title: doc.meta.title,
+      lang: doc.meta.lang,
+      sections: doc.sections.map(s => ({ id: s.id, title: s.title })),
+      ...section ? { section: { id: section.id, title: section.title, ...context.step !== undefined ? { step: context.step } : {}, text: sectionText(section) } } : {},
+      ...selection,
+    }
+  }
+  const position = slideNavigation?.position.getSnapshot()
+  const page = position && typeof document !== 'undefined' ? document.querySelector<HTMLElement>(`.pm-slide[data-slide="${position.slide}"]`) : undefined
+  const text = page?.innerText.trim() ?? ''
+  const id = position?.section ?? context.section
+  const title = page?.querySelector('h1, h2, h3')?.textContent?.trim() || document.title
+  return {
+    lang: currentLocale(),
+    sections: id ? [{ id, title }] : [],
+    ...id && text ? { section: { id, title, text } } : {},
+    ...selection,
+  }
+}
+
+async function* streamed(body: ReadableStream<Uint8Array<ArrayBuffer>>): AsyncIterable<string> {
+  const reader = body.pipeThrough(new TextDecoderStream()).pipeThrough(new EventSourceParserStream()).getReader()
+  try {
+    for (;;) {
+      const { value, done } = await reader.read()
+      if (done) break
+      const delta = streamDelta(value.data)
+      if (delta.done) return
+      if (delta.text) yield delta.text
+    }
+  } finally {
+    await reader.cancel().catch(() => {})
+    reader.releaseLock()
+  }
+}
+
+export interface ChatClientOptions {
+  webViewer(): WebViewerAccess | undefined
+  slideNavigation(): Navigation | undefined
+  missing(): string
+  signal?: AbortSignal
+}
+
+export function createAskClient(options: ChatClientOptions): AskClient {
+  return {
+    provider: () => (askSettings.getSnapshot() ? askProvider(askSettings.getSnapshot()!.url) : undefined),
+    async* ask(question, context, signal) {
+      const settings = askSettings.getSnapshot()
+      if (!settings) throw new Error(options.missing())
+      const requestSignal = signal && options.signal ? AbortSignal.any([signal, options.signal]) : signal ?? options.signal
+      const response = await fetch(completionsUrl(settings.url), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Accept': 'text/event-stream', 'Authorization': `Bearer ${settings.key}` },
+        body: JSON.stringify({ model: settings.model, stream: true, messages: askMessages(question, placeOf(context, options.webViewer(), options.slideNavigation())) }),
+        credentials: 'omit',
+        referrerPolicy: 'no-referrer',
+        ...requestSignal ? { signal: requestSignal } : {},
+      })
+      if (!response.ok) {
+        const body = await response.text().catch(() => '')
+        requestSignal?.throwIfAborted()
+        throw new Error(serviceError(response.status, body))
+      }
+      if (!response.headers.get('content-type')?.includes('text/event-stream') || !response.body) {
+        const body = await response.json().catch(() => undefined)
+        requestSignal?.throwIfAborted()
+        const text = completionText(body)
+        if (text === undefined) throw new Error(serviceError(response.status, ''))
+        yield text
+        return
+      }
+      yield* streamed(response.body)
+    },
+  }
+}

package/src/client/env.d.ts

@@ -0,0 +1,7 @@
+interface ImportMetaEnv {
+  BASE_URL: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

package/src/client/index.ts

@@ -0,0 +1 @@
+export { assistantPlugin } from './plugin.ts'

package/src/client/plugin.ts

@@ -0,0 +1,49 @@
+import { currentLocale, NAVIGATION, TOOLBAR } from '@lincyaw/host'
+import { ASK, PRESENTER_PANELS } from '@lincyaw/kernel'
+import type { PluginDefinition, Unsubscribe } from '@lincyaw/kernel'
+import { version } from '../../package.json'
+import { ASSISTANT_ID, ASSISTANT_MESSAGES } from '../domain/index.ts'
+import AskPanel from './AskPanel.tsx'
+import AssistantToolbar from './AssistantToolbar.tsx'
+import { createAskClient } from './chat-client.ts'
+import { askClient, keptWebViewerAccess, slideNavigation, trackSelection } from './state.ts'
+
+let cleanup: Unsubscribe[] = []
+
+export const assistantPlugin: PluginDefinition = {
+  manifest: {
+    id: ASSISTANT_ID,
+    name: { 'zh-CN': '读者问答', en: 'Reader Q&A' },
+    version,
+    kernel: '^1.0.0',
+    provides: [ASK],
+    requires: [{ token: TOOLBAR, optional: true }, { token: PRESENTER_PANELS, optional: true }, { token: NAVIGATION, optional: true }],
+  },
+  setup(ctx) {
+    const lifetime = new AbortController()
+    slideNavigation.set(ctx.tryGet(NAVIGATION))
+    const ask = createAskClient({
+      webViewer: keptWebViewerAccess,
+      slideNavigation: () => slideNavigation.getSnapshot(),
+      missing: () => ASSISTANT_MESSAGES[currentLocale()].ask.missing,
+      signal: lifetime.signal,
+    })
+    ctx.provide(ASK, ask)
+    askClient.set(ask)
+    const t = ASSISTANT_MESSAGES[currentLocale()]
+    cleanup = [
+      () => lifetime.abort(),
+      ctx.tryGet(TOOLBAR)?.register({ id: ASSISTANT_ID, title: t.toolbar.title, component: AssistantToolbar, order: 15 }),
+      ctx.tryGet(PRESENTER_PANELS)?.register({ id: ASSISTANT_ID, title: t.panel.title, component: AskPanel, order: 15 }),
+      typeof document === 'undefined' ? undefined : trackSelection(),
+    ].filter(stop => stop !== undefined)
+  },
+  dispose() {
+    cleanup.forEach(stop => stop())
+    cleanup = []
+    askClient.set(undefined)
+    slideNavigation.set(undefined)
+  },
+}
+
+export default assistantPlugin

package/src/client/settings.ts

@@ -0,0 +1,22 @@
+import { createStore } from '@lincyaw/host'
+import { ASK_STORAGE_KEY, toAskSettings } from '../domain/index.ts'
+import type { AskSettings } from '../domain/index.ts'
+
+function storedSettings(): AskSettings | undefined {
+  try {
+    return toAskSettings(JSON.parse(localStorage.getItem(ASK_STORAGE_KEY) ?? 'null'))
+  } catch {
+    return undefined
+  }
+}
+
+export const askSettings = createStore<AskSettings | undefined>(typeof window === 'undefined' ? undefined : storedSettings())
+
+export function saveAskSettings(settings: AskSettings | undefined): void {
+  askSettings.set(settings)
+  try {
+    if (settings) localStorage.setItem(ASK_STORAGE_KEY, JSON.stringify(settings))
+    else localStorage.removeItem(ASK_STORAGE_KEY)
+  } catch {
+  }
+}

package/src/client/state.ts

@@ -0,0 +1,53 @@
+import { createStore } from '@lincyaw/host'
+import type { Navigation } from '@lincyaw/host'
+import type { AgentContext, AskClient, Citation, IRDocument } from '@lincyaw/kernel'
+import { errorMessage } from '@lincyaw/kernel'
+export const askClient = createStore<AskClient | undefined>(undefined)
+export const slideNavigation = createStore<Navigation | undefined>(undefined)
+export interface WebViewerAccess { doc(): IRDocument, position(): { section: string, step: number } | undefined, title(section: string): string | undefined, show(citation: Citation): void }
+let resolveWebViewer: (() => WebViewerAccess | undefined) | undefined
+let keptWebViewer: WebViewerAccess | undefined
+export function setWebViewerAccess(resolve: () => WebViewerAccess | undefined) { resolveWebViewer = resolve; keptWebViewer = undefined }
+export function useWebViewerAccess(): WebViewerAccess | undefined { try { return keptWebViewer = resolveWebViewer?.() } catch { return undefined } }
+export function keptWebViewerAccess() { return keptWebViewer }
+export function showCitation(citation: Citation) {
+  if (keptWebViewer) return keptWebViewer.show(citation)
+  const go = slideNavigation.getSnapshot()
+  if (go) go.go({ slide: go.position.getSnapshot().slide, step: citation.step ?? 0, section: citation.section })
+}
+export interface Selected { text: string, section?: string, block?: string }
+export const selected = createStore<Selected | undefined>(undefined)
+export function trackSelection(): () => void {
+  const update = () => {
+    const selection = document.getSelection()
+    if (!selection || selection.isCollapsed || selection.rangeCount === 0) return
+    const text = selection.toString().trim()
+    const node = selection.getRangeAt(0).commonAncestorContainer
+    const element = node instanceof Element ? node : node.parentElement
+    if (!text || element?.closest('.pm-assistant')) return
+    const section = element?.closest<HTMLElement>('[data-section]')?.dataset.section
+    if (!section) return
+    const block = element?.closest<HTMLElement>('[data-block]')
+    selected.set({ text: text.slice(0,4000), section, ...block?.dataset.block ? { block: block.dataset.block } : {} })
+  }
+  document.addEventListener('selectionchange', update)
+  return () => document.removeEventListener('selectionchange', update)
+}
+export interface Exchange { id: number, question: string, answer: string, state: 'running' | 'done' | 'failed', error?: string, cancelled?: boolean, cancel(): void }
+export const exchanges = createStore<Exchange[]>([])
+let asked = 0
+export function startExchange(client: AskClient, question: string, context: AgentContext) {
+  const stop = new AbortController()
+  const id = ++asked
+  const update = (patch: Partial<Exchange>) => exchanges.set(exchanges.getSnapshot().map(e => e.id === id ? { ...e, ...patch } : e))
+  const exchange: Exchange = { id, question, answer: '', state: 'running', cancel: () => { update({ cancelled: true }); stop.abort() } }
+  exchanges.set([exchange, ...exchanges.getSnapshot()])
+  void (async () => {
+    let answer = ''
+    try { for await (const piece of client.ask(question, context, stop.signal)) { answer += piece; update({ answer }) }; update({ state: 'done' }) }
+    catch (error) {
+      const cancelled = stop.signal.aborted || (error instanceof Error && error.name === 'AbortError')
+      update(cancelled ? { state: 'done', cancelled: true } : { state: 'failed', error: errorMessage(error) })
+    }
+  })()
+}

package/src/client/viewer.ts

@@ -0,0 +1,19 @@
+import { useStore } from '@lincyaw/host'
+import type { ViewerPlugin } from '@lincyaw/viewer'
+import { setWebViewerAccess } from './state.ts'
+
+const plugin: ViewerPlugin = (ctx) => {
+  setWebViewerAccess(() => {
+    const viewer = ctx.useViewer()
+    useStore(viewer.doc)
+    useStore(viewer.position)
+    return {
+      doc: () => viewer.doc.getSnapshot(),
+      position: () => viewer.position.getSnapshot(),
+      title: section => viewer.section(section)?.title,
+      show: citation => viewer.show({ section: citation.section, step: citation.step ?? 0 }),
+    }
+  })
+}
+
+export default plugin

package/src/domain/citations.ts

@@ -0,0 +1,27 @@
+import type { Citation } from '@lincyaw/kernel'
+
+const LINK = /\[([^\]\n]+)\]\(presmium:\/\/sections\/([^)\s/#?]+)(?:\/steps\/(\d+))?(?:#([^)\s]+))?\)/g
+
+function decoded(value: string): string {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}
+
+export type AnswerPart = { text: string, citation?: Citation }
+
+export function answerParts(text: string): AnswerPart[] {
+  const parts: AnswerPart[] = []
+  let at = 0
+  for (const match of text.matchAll(LINK)) {
+    if (match.index > at) parts.push({ text: text.slice(at, match.index) })
+    const [, label, section, step, block] = match
+    const citation: Citation = { label: label!, section: decoded(section!), ...step === undefined ? {} : { step: Number(step) }, ...block ? { block: decoded(block) } : {} }
+    parts.push({ text: label!, citation })
+    at = match.index + match[0].length
+  }
+  if (at < text.length) parts.push({ text: text.slice(at) })
+  return parts
+}

package/src/domain/completion.ts

@@ -0,0 +1,29 @@
+export type StreamDelta = { done: true } | { done?: false, text?: string }
+
+export function streamDelta(data: string): StreamDelta {
+  const value = data.trim()
+  if (value === '[DONE]') return { done: true }
+  try {
+    const parsed = JSON.parse(value) as { choices?: { delta?: { content?: unknown } }[], error?: { message?: unknown } }
+    if (parsed.error) throw new Error(typeof parsed.error.message === 'string' ? parsed.error.message : JSON.stringify(parsed.error))
+    const content = parsed.choices?.[0]?.delta?.content
+    return typeof content === 'string' && content ? { text: content } : {}
+  } catch (error) {
+    if (error instanceof SyntaxError) return {}
+    throw error
+  }
+}
+
+export function completionText(body: unknown): string | undefined {
+  const content = (body as { choices?: { message?: { content?: unknown } }[] } | undefined)?.choices?.[0]?.message?.content
+  return typeof content === 'string' ? content : undefined
+}
+
+export function serviceError(status: number, text: string): string {
+  try {
+    const message = (JSON.parse(text) as { error?: { message?: unknown } }).error?.message
+    if (typeof message === 'string' && message) return `${status}: ${message}`
+  } catch {
+  }
+  return `${status}${text.trim() ? `: ${text.trim().slice(0, 300)}` : ''}`
+}

package/src/domain/index.ts

@@ -0,0 +1,12 @@
+export { answerParts } from './citations.ts'
+export type { AnswerPart } from './citations.ts'
+export { completionText, serviceError, streamDelta } from './completion.ts'
+export type { StreamDelta } from './completion.ts'
+export { ASSISTANT_MESSAGES } from './messages.ts'
+export type { AssistantMessages } from './messages.ts'
+export { askMessages, promptLanguage, sectionText } from './prompt.ts'
+export type { AskPlace } from './prompt.ts'
+export { ASK_STORAGE_KEY, askProvider, completionsUrl, isAskUrlValid, toAskSettings } from './settings.ts'
+export type { AskSettings } from './settings.ts'
+
+export const ASSISTANT_ID = 'presmium.assistant'

package/src/domain/messages.ts

@@ -0,0 +1,81 @@
+import type { Locale } from '@lincyaw/kernel'
+
+const zh = {
+  toolbar: { button: '提问', title: '向 AI 提问（关于当前页面或所选内容），使用你自己的模型服务' },
+  panel: {
+    title: '向 AI 提问',
+    close: '关闭',
+    provider: (provider: string, model: string) => `回答由 ${provider} 的模型 ${model} 生成`,
+    service: '模型服务',
+    question: '问题',
+    placeholder: '想问什么？',
+    selection: '附上所选内容',
+    dropSelection: '不附上',
+    at: (where: string) => `关于：${where}`,
+    ask: '提问',
+    cancel: '取消',
+    cancelled: '已取消',
+    answering: '正在回答…',
+    failed: (message: string) => `无法获得回答：${message}`,
+    answers: '回答',
+    cite: (label: string) => `跳到“${label}”`,
+  },
+  ask: {
+    title: '你的模型服务',
+    intro: '提问由你自己填写的模型服务回答：OpenAI 兼容的 Chat Completions 接口的地址、密钥与模型名。问题与当前页面的内容从这个浏览器直接发给该服务，不经过本站；费用由该服务向你收取。',
+    storage: '设置只保存在这个浏览器中（本站点的存储）。同一站点上的脚本能读到密钥，请只在你信任的站点上填写。',
+    url: '地址',
+    urlPlaceholder: 'https://api.deepseek.com/v1',
+    key: '密钥',
+    model: '模型名',
+    modelPlaceholder: 'deepseek-chat',
+    save: '保存',
+    cancel: '取消',
+    clear: '清除设置',
+    invalidUrl: '地址须以 https:// 或 http:// 开头。',
+    missing: '尚未设置模型服务。',
+  },
+}
+
+type Messages = typeof zh
+
+const en: Messages = {
+  toolbar: { button: 'Ask', title: 'Ask the AI about this page or the selection, using your own model service' },
+  panel: {
+    title: 'Ask the AI',
+    close: 'Close',
+    provider: (provider, model) => `Answers come from ${provider}’s model ${model}`,
+    service: 'Model service',
+    question: 'Question',
+    placeholder: 'What would you like to know?',
+    selection: 'Include the selection',
+    dropSelection: 'Don’t Include',
+    at: where => `About: ${where}`,
+    ask: 'Ask',
+    cancel: 'Cancel',
+    cancelled: 'Canceled',
+    answering: 'Answering…',
+    failed: message => `Couldn’t get an answer: ${message}`,
+    answers: 'Answers',
+    cite: label => `Go to “${label}”`,
+  },
+  ask: {
+    title: 'Your Model Service',
+    intro: 'Your own model service answers: the address, key, and model of an OpenAI-compatible Chat Completions API. The question and this page’s content go from this browser to that service directly, not through this site; the service bills you.',
+    storage: 'The settings stay in this browser (this site’s storage). Scripts on the same site can read the key, so fill it in only on sites you trust.',
+    url: 'Address',
+    urlPlaceholder: 'https://api.deepseek.com/v1',
+    key: 'API key',
+    model: 'Model',
+    modelPlaceholder: 'deepseek-chat',
+    save: 'Save',
+    cancel: 'Cancel',
+    clear: 'Clear Settings',
+    invalidUrl: 'The address must start with https:// or http://.',
+    missing: 'No model service is set up yet.',
+  },
+}
+
+export type AssistantMessages = Messages
+
+export const ASSISTANT_MESSAGES: Record<Locale, AssistantMessages> = { 'zh-CN': zh, 'en': en }

package/src/domain/prompt.ts

@@ -0,0 +1,44 @@
+import { blockText } from '@lincyaw/kernel'
+import type { IRSection } from '@lincyaw/kernel'
+
+const LANGUAGES: Record<string, string> = { zh: 'Simplified Chinese (zh-CN)', en: 'English' }
+
+export function promptLanguage(lang: string | undefined): string {
+  const tag = lang?.trim() || 'zh-CN'
+  return LANGUAGES[tag.toLowerCase().split('-')[0]!] ?? tag
+}
+
+export interface AskPlace {
+  title?: string
+  lang?: string
+  sections: { id: string, title: string }[]
+  section?: { id: string, title: string, step?: number, text: string }
+  selection?: string
+}
+
+const SECTION_CHARS = 12_000
+const SELECTION_CHARS = 4000
+const TOC_SECTIONS = 400
+
+export function sectionText(section: IRSection): string {
+  return section.blocks.map(blockText).filter(Boolean).join('\n\n').slice(0, SECTION_CHARS)
+}
+
+const cut = (text: string, max: number) => (text.length > max ? `${text.slice(0, max)}…` : text)
+
+export function askMessages(question: string, place: AskPlace): { role: 'system' | 'user', content: string }[] {
+  const lines = [
+    `A reader of a course document${place.title ? ` ("${place.title}")` : ''} asks a question. Answer from the content below, which is what the reader's page shows; say so when it does not tell.`,
+    'When your answer relies on a section, link it as [its title](presmium://sections/<section id>), with an id of the table of contents; the reader can follow these links.',
+    `Answer in ${promptLanguage(place.lang)}, briefly.`,
+  ]
+  if (place.sections.length) {
+    lines.push('', 'Table of contents (section id: title):', ...place.sections.slice(0, TOC_SECTIONS).map(s => `- ${s.id}: ${s.title}`))
+  }
+  if (place.section) {
+    const { id, title, step, text } = place.section
+    lines.push('', `The section the reader is at: ${title} (id ${id}${step !== undefined ? `, step ${step}` : ''}). Its content:`, '"""', cut(text, SECTION_CHARS), '"""')
+  }
+  if (place.selection) lines.push('', 'The reader selected this on the page:', '"""', cut(place.selection, SELECTION_CHARS), '"""')
+  return [{ role: 'system', content: lines.join('\n') }, { role: 'user', content: question }]
+}

package/src/domain/settings.ts

@@ -0,0 +1,36 @@
+export interface AskSettings {
+  url: string
+  key: string
+  model: string
+}
+
+export const ASK_STORAGE_KEY = 'presmium.assistant.ask'
+
+export function toAskSettings(value: unknown): AskSettings | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const { url, key, model } = value as Record<string, unknown>
+  const text = (v: unknown) => (typeof v === 'string' && v.trim() ? v.trim() : undefined)
+  const settings = { url: text(url), key: text(key), model: text(model) }
+  return settings.url && settings.key && settings.model && isAskUrlValid(settings.url) ? settings as AskSettings : undefined
+}
+
+export function isAskUrlValid(url: string): boolean {
+  try {
+    return ['https:', 'http:'].includes(new URL(url).protocol)
+  } catch {
+    return false
+  }
+}
+
+export function completionsUrl(url: string): string {
+  const base = url.trim().replace(/\/+$/, '')
+  return /\/chat\/completions$/.test(base) ? base : `${base}/chat/completions`
+}
+
+export function askProvider(url: string): string {
+  try {
+    return new URL(url).host
+  } catch {
+    return url
+  }
+}

package/src/node/presmium.ts

@@ -0,0 +1,14 @@
+import { createRequire } from 'node:module'
+import type { PresmiumNodePlugin } from '@lincyaw/kernel'
+import { ASSISTANT_ID } from '../domain/index.ts'
+
+const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
+
+const plugin: PresmiumNodePlugin = {
+  id: ASSISTANT_ID,
+  version,
+  kernel: '^1.0.0',
+  operator: true,
+}
+
+export default plugin