@chentyit/dsh-chatbot-panel 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chentyit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,175 @@
-# Temporary Holding Version
+# ChatBot capability panel
 
-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.
+A **DeepSeek Harness** bundle that turns the composer's web capabilities into an explicit,
+per-session choice, and keeps the usage honest.
+
+It adds a small **ChatBot** chip right of the composer's permission chip («Workspace Write»).
+Clicking the chip opens an upward panel; enabling a capability there starts it for the current
+session. While a capability is off, its tools are not "politely denied" — they leave the model's
+tool catalog entirely.
+
+## Features
+
+- **Per-session capability switch.** Click the chip to open/close the panel. The chip itself never
+  toggles a capability; enabling anything in the panel marks it active (tinted bot icon).
+- **Web search** — exposes the built-in `web_search` / `web_fetch` tools only while enabled.
+- **Image search** — adds `chatbot_image_search` while web search is on. When the user's message
+  carries an image, the tool reads that image from the current turn and asks DeepSeek's native
+  `deepseek_web_search` server tool to search by it, returning an identification, source pages and
+  the matched `image_url`s. An explicit workspace path, `http(s)` URL or base64 data URI also works.
+- **Deep thinking search** — adds `chatbot_deep_search`, which runs DeepSeek's server-side
+  `deepseek_web_search` tool with thinking enabled: the search model plans several queries,
+  searches, opens and reads relevant pages over multiple steps, then answers with sources. Pass
+  `image: "auto"` to combine it with the current message's image.
+- **Default off.** A fresh session starts with no web tools declared; turning a capability off
+  restores that state.
+- **Durable state.** The switch is stored in the session log through the `/chatbot` command
+  lifecycle and read back from a session projection, so it survives page reloads, resume and forks.
+- **Usage and estimated cost.** The panel footer shows billed searches / sources, fetch calls,
+  image searches / images sent / billed requests, deep-search calls and tool calls, deep-search
+  tokens and failures, per-category fees and the estimated total, with a link to the DeepSeek
+  platform usage page. Image and deep fees are split into tool and auxiliary-token fees.
+- **Theme-native, borderless.** The chip uses the host theme tokens and matches the permission
+  chip's 28 px text-chip look; no border, no fill, hover tints the whole chip.
+
+## Install
+
+Requires DeepSeek Harness `0.2.2-rc.3` or another compatible `0.2.x` runtime (`engines.dsh`).
+
+After the package is published to a registry:
+
+1. **Settings → Plugins → install** and enter `@chentyit/dsh-chatbot-panel@0.2.0`, or
+2. use the plugin manager tool: `install_bundle` with target `@chentyit/dsh-chatbot-panel@0.2.0`.
+
+From a local checkout (development):
+
+```bash
+# a local directory is linked into the profile; edits need a bundle toggle or restart
+plugin_manager install_bundle target=/path/to/dsh-chatbot-panel
+```
+
+The Web page reloads the client half after activation; if the Plugins page asks for a restart,
+restart the app. Uninstall from Settings → Plugins (or remove the bundle).
+
+## Usage
+
+1. Open a session. The **ChatBot** chip sits right of the permission chip.
+2. Click it; the panel opens upward. Tick **Web search** (and optionally **Deep thinking search**).
+3. Ask the model a question that needs current information — it now has the matching tools.
+4. Attach an image and ask what it is, where it comes from, or to find similar images. With web
+   search on, the model calls `chatbot_image_search`; with deep search on it can also add
+   `image: "auto"` to `chatbot_deep_search` for a slower, multi-step image search.
+5. Untick everything, and the tools disappear from the model's catalog again.
+6. The panel footer reports this session's usage and estimated cost.
+
+You can also drive the same state with the slash command:
+
+```text
+/chatbot web on | web off
+/chatbot deep on | deep off
+/chatbot reset
+```
+
+## Usage and billing
+
+The official price list bills web search, image search and page fetch separately from model tokens:
+**CNY 5 per 1,000 successful requests** (≈ ¥0.005 per call; failed or empty results are not
+billed).
+
+| Row in the panel | What is counted |
+|---|---|
+| Search | one successful `web_search` tool call fans out one request per query, so a successful call counts `queries.length` billed searches |
+| Fetch | successful `web_fetch` calls; anonymous HTTP fetch is free, so no fee is added unless the fetch provider is the DeepSeek Fetch API (`countFetchCost: true`) |
+| Image | `chatbot_image_search` calls, images sent, and the billed request count (`tool_search` + `tool_fetch` + `tool_image_search`); the fee is split into tool and auxiliary-token fees |
+| Deep | deep-search tool calls plus the billed `tool_search` / `tool_fetch` / `tool_image_search` counters from the provider and the auxiliary model's input/output tokens |
+| Failed | calls that ended in an error; a failed multi-query search may already have billed some requests |
+
+The displayed amount is an **estimate**: the API returns counts, not money, so the panel multiplies
+counts by the configured unit prices. The DeepSeek platform usage page remains authoritative, and
+the panel links to it.
+
+## Configuration
+
+Override the row's `config` in the profile patch (`~/.dsh/profiles/<profile>/cordis.patch.yml`):
+
+```yaml
+- id: chatbot-panel
+  name: '@chentyit/dsh-chatbot-panel'
+  config:
+    manageBuiltinWebTools: true   # false = the panel no longer hides/enables built-in web tools
+    pricePerThousand: 5           # CNY per 1,000 successful web-tool requests (estimate only)
+    countFetchCost: false         # true only when the fetch provider is the DeepSeek Fetch API
+    deepSearch:
+      baseURL: https://api.deepseek.com/anthropic/v1
+      apiKeyEnv: DEEPSEEK_API_KEY
+      model: deepseek-flash
+      maxTokens: 4096
+      timeoutMs: 180000
+    tokenPrice:                   # auxiliary search turn, deepseek-flash idle prices
+      inputPerMillion: 1
+      outputPerMillion: 4
+```
+
+Image search uses the same `deepSearch` endpoint, model and credential as deep search. It
+authenticates with the signed-in DeepSeek account when the session runs on the account route
+(`x-dsh-auth-token`), otherwise with a stored API key or the key named by
+`deepSearch.apiKeyEnv` (`$DSH_HOME/.env`, the credential service, or the process environment).
+Without either it fails with a clear message.
+
+## Limitations
+
+- Deep search and image search need a DeepSeek account sign-in or an API key.
+- Image search reads the images attached to the **current turn's** user message. In a later turn,
+  attach the image again or pass an explicit workspace path, `http(s)` URL or data URI.
+- One image search accepts up to four images; each must be PNG, JPEG, WebP or GIF, up to 8 MB
+  (attached images are resized toward the DeepSeek vision budget first).
+- Searching by image uploads that image to DeepSeek's Messages API. The result's `image_url` is for
+  display only and is not guaranteed to be reachable.
+- Toggling a capability changes the request's tool catalog, so that session's DeepSeek prompt
+  cache is invalidated once.
+- With plan mode active, the plan chip sits between the permission chip and this chip (official
+  single-slot order).
+- Usage is folded from the session log; billing counts from failed multi-query searches are not
+  recoverable, so they are reported as failures only.
+- Requires a DeepSeek model route that serves the official Messages API; other providers keep
+  their own web tools untouched.
+
+## Development
+
+The package is plain JavaScript — no build step, no runtime dependencies:
+
+```bash
+npm run check        # syntax + metadata validation + node:test suites
+npm pack --dry-run   # inspect the published file list
+npm publish --access public
+```
+
+The Host half is `index.js`; `pure.js` holds the testable capability, usage and response helpers;
+`client.js` is the browser half. `test/` covers the pure helpers and the two auxiliary tools with a
+mocked Cordis context and Messages response.
+
+## License
+
+MIT. Copyright (c) 2026 chentyit.
+
+---
+
+## 中文说明
+
+**DeepSeek Harness 插件（bundle）**：把 composer 里的联网能力变成按会话的显式开关，并如实记录用量。
+
+在输入框「工作区内修改」权限按钮右侧加一个 **ChatBot** 小按钮（无边框、无底色，与权限 chip 同款视觉）。
+点击按钮展开向上弹出的能力面板；在面板里勾选能力，才对本会话生效。**关闭时不是"拒绝调用"，而是把对应工具从模型的工具目录里彻底移除。**
+
+- **联网搜索**：仅在开启时向模型暴露内置 `web_search` / `web_fetch`。
+- **以图搜图**：联网搜索开启时额外提供 `chatbot_image_search`。用户消息带图时，工具读取本轮的图片，交给 DeepSeek 服务端 `deepseek_web_search` 按图搜索，返回识别结论、来源页面和匹配到的 `image_url`；也支持工作区路径、`http(s)` URL 或 base64 data URI。
+- **深度思考搜索**：额外提供 `chatbot_deep_search`，走 DeepSeek 服务端 `deepseek_web_search`（thinking 开启）多步搜索、打开网页后带来源作答；传 `image: "auto"` 可结合本轮图片做深度以图搜图。
+- **默认关闭**；开关按会话写入会话日志，刷新、恢复、分叉后仍有效。
+- **用量与费用**：面板底部按官方口径记录搜索、抓取、搜图、深搜的次数与估算费用，并链接开放平台用量页。
+- **图片限制**：只读取本条消息里的图片；一次最多 4 张，支持 PNG/JPEG/WebP/GIF，单张 ≤ 8MB；搜索时图片会上传给 DeepSeek，搜图与深搜需 DeepSeek 账号或 API key。
+
+安装：`Settings → Plugins` 输入 `@chentyit/dsh-chatbot-panel@0.2.0`，或用 `plugin_manager` 的 `install_bundle`。
+
+计费口径：联网搜索/抓取/图片搜索官方价 **5 元 / 1000 次成功请求**（失败或零结果不计费）；一次 `web_search` 按查询词数拆成多次请求；图片搜索每张图片计 1 次，模型框选图片中的区域时每个区域另计 1 次。面板金额是**估算**（API 只返回次数），以平台账单为准。
+
+配置项与限制见上方英文段落（`manageBuiltinWebTools` / `pricePerThousand` / `countFetchCost` / `deepSearch` / `tokenPrice`）。