dsh-background-by-model 0.12.0-test.1 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,9 @@
 
 ## v0.12.0
 
+- **The two tools now say what the theme already decides for them** — a picture is not chosen to match the current light or dark interface (the scheme follows the wallpaper's own luminance, so both work), a colour is not supplied unless the user named one (a picture themes the interface from its own bytes), and the URL is picked from a host reachable in mainland China rather than `raw.githubusercontent.com` or Google. Guidance on the parameter it applies to, so it costs nothing on a call that does not use it.
+- **A picture the agent adds lands in `fill`** — the same mode the recommended profile's seven use; `fit` letterboxed every wallpaper that was not already the window's shape, and this is the one path with no panel to correct it afterwards.
+
 - **Fix: "installing the profile turned my AI access back off"** — the profile is a LOOK (rules, wallpapers, interface numbers), and authorisation is not part of a look: it answers "may an agent change this", was given by hand, and no button may take it back. `recommendedConfig()` carried the shipped default of `false`, so installing a look silently revoked it.
 - **The other half of the same rule** — the profile still ships `agentAccess: false`, so that installing it cannot GRANT access; what is added here is the symmetric half, that installing it cannot REVOKE it either. It is the same sentence the import path already follows, which keeps the importing machine's own value rather than the file's.
 - **The grant is read before the wipe** — the same reason as the revision: after `resetStore` that config is gone, and reading late would always find the shipped default.

package/CHANGELOG.zh.md

@@ -4,6 +4,9 @@
 
 ## v0.12.0
 
+- **两个工具现在把"主题自己会决定的事"说清楚了** —— 不必为适配当前深浅模式特意挑图（深浅跟着壁纸自身的亮度走，深色浅色都能用）、用户没点名就不传颜色（图片会用自身配色去定主题）、找图优先选中国大陆能访问的站点而不是 `raw.githubusercontent.com` 或 Google。这些都写在对应的参数上，不传该参数的调用一分上下文都不多花。
+- **AI 加的图片落在「填充」** —— 和推荐配置那七张同一个模式；原来的「适应」会给所有不是窗口比例的壁纸加黑边，而这条路径之后没有面板可以补救。
+
 - **修掉"开着 AI 授权去用推荐配置，开关被关掉"** —— 推荐配置是**一份外观**（规则、壁纸、界面数值），而授权不是外观的一部分：它回答的是"AI 能不能改这套东西"，是用户亲手给的，没有任何按钮可以收回。之前 `recommendedConfig()` 带着出厂默认 `false`，于是"装一份外观"顺手把授权撤销了。
 - **同一条规则的另一面** —— 推荐配置出厂仍带 `agentAccess: false`，这样**安装它不能授予**权限；现在补上对称的一半：**安装它也不能撤销**。这和导入主题的处理是同一句话——导入时也保留**本机**的值，而不是文件里的。
 - **授权值在清空之前读** —— 和版本号同一个道理：`resetStore` 之后那份配置就没了，晚一步读到的永远是出厂默认。

package/README.md

@@ -146,6 +146,7 @@ The first card on the Config tab: one switch deciding whether **the AI may chang
 - **What the AI can do** — add, edit and remove rules; add an image to a rule from a URL; set per-image layout, opacity, brightness, blur and theme colour; set the global interface opacities and the switch effect; adjust rotation; and **install the recommended profile**.
 - **Installing the recommended profile asks separately** — it does exactly what the panel's button does (download seven pictures, empty the store, install seven rules), so the tool requires an explicit `confirm: true` and otherwise refuses **before touching anything**. Download first, wipe second: if any picture cannot be fetched, your rules are not touched at all.
 - **What it cannot do** — touch the holiday art (that slot is read-only), or read image bytes (the tools answer with slot names, never megabytes of base64).
+- **What it is told not to bother with** — matching a picture to the interface's current lightness (the scheme follows the wallpaper, so a dark one and a light one are equally fine), supplying a theme colour the user did not ask for (a picture's own palette is used instead), and sources that mainland China cannot reach. These live in the parameter they apply to, so a call that does not use one costs nothing for it.
 - **Edits land immediately** — the panel checks the config's revision on disk every 3 seconds, so an agent's change repaints without a reload.
 - **An export never carries the switch** — sending someone a theme file does not hand them "let the AI change my appearance", and a hand-edited file that says `true` is overruled by the **importing machine's** own value.
 - **The AI and you cannot silently overwrite each other** — every write names the revision it was computed from, a write that has fallen behind is **refused** instead of overwriting, and the panel then adopts the copy that won.
@@ -311,6 +312,7 @@ The effect is **Instant**, or the duration is `0` — an effect and a duration a
 ### v0.12.0
 
 - **The agent can change the appearance through two tools** — `background_theme` reads; `background_edit` writes (add/edit/remove rules and images, layout, opacity, brightness, blur, theme colour, the global interface opacities, the switch effect, rotation, and installing the recommended profile behind a `confirm`). Both call the same node-half operations the settings panel does.
+- **Their descriptions say what the theme decides for them** — a picture is not picked to suit the current light/dark interface (the scheme follows the wallpaper, so either works), no colour is passed unless the user named one, URLs come from hosts reachable in mainland China, and a picture the agent adds lands in `fill`.
 - **The switch ships off** — a new `agentAccess` in the config. While it is off the tools are **absent from the model's tool table**, costing no context and impossible to call; the recommended profile does not turn it on — and installing it does not turn one OFF either.
 - **An export never carries the grant** — a theme file describes an appearance; `agentAccess` and `rev` are stripped on the way out and the importing machine's own value wins on the way in.
 - **The config carries a revision, and a stale write is refused** — the panel and the tools cannot silently overwrite each other; the loser is handed the config that won and adopts it. A successful write must record the new revision, or the next save refuses itself and the edit visibly undoes itself ("click + once, the card flashes and disappears"). Installing the recommended profile is one round trip, not "wipe then write".

package/README.zh.md

@@ -146,6 +146,7 @@
 - **AI 能做** —— 增删改规则、给规则加图（按网址下载）、逐图改布局 / 透明度 / 亮度 / 模糊 / 主题色、改全局界面透明度与切换效果、改轮换设置，以及**换上推荐配置**。
 - **「换上推荐配置」要单独确认** —— 它和面板上那个按钮做同一件事（下载七张图、清空存储、装上七条规则），所以工具要求调用方显式带 `confirm: true`，否则**在动任何东西之前**就拒绝。先下载、后清空：任何一张图取不到，你的规则一个字节都没动。
 - **AI 不能做** —— 改节日画（那个槽位只读）、读图片字节（工具只回槽位名，不回几 MB 的 base64）。
+- **它被告知不必操心的事** —— 挑一张和当前界面深浅相配的图（深浅跟着壁纸走，深色浅色都行）、用户没点名就传主题色（会直接用图片自己的配色）、以及中国大陆访问不到的图源。这些都写在各自的参数上，不用该参数的调用不会为它多花上下文。
 - **改动即时生效** —— 面板每 3 秒核对一次磁盘上的配置版本号，AI 改完不用刷新页面。
 - **导出不带这个开关** —— 把主题文件发给别人，不会顺手把"允许 AI 改外观"也送给对方；对方手动改过的文件里写着 `true` 也没用，导入时一律以**本机**的值说了算。
 - **AI 和你同时改不会互相覆盖** —— 每次写入都带着"我基于哪个版本"，落后的一方会被**拒绝**而不是覆盖，然后面板自动接盘最新的那份。
@@ -311,6 +312,7 @@ pnpm test            # 构建 lib/、类型检查、跑十三道检查
 ### v0.12.0
 
 - **AI 可以通过两个工具改这套外观** —— `background_theme` 读，`background_edit` 写（增删改规则与图片、布局、透明度、亮度、模糊、主题色、全局界面透明度、切换效果、轮换，以及带 `confirm` 才执行的「换上推荐配置」）。它们调的是面板用的同一批 node 半边操作。
+- **工具描述写清了主题替它决定的事** —— 不必为适配当前深浅模式挑图（深浅跟着壁纸走，深色浅色都能用）、用户没点名就不传颜色、找图优先选中国大陆能访问的站点、AI 加的图片落在「填充」。
 - **授权开关默认关** —— 配置里新增 `agentAccess`。关着时工具**根本不在模型的工具表里**，不占上下文也不会被误调；推荐配置也不替你打开。
 - **导出不带授权** —— 主题文件只描述外观，`agentAccess` 与 `rev` 在导出时被剥掉，导入时以本机的值为准。
 - **配置带版本号，落后写入被拒绝** —— 面板与工具不能互相静默覆盖；被拒的一方拿到赢家的配置并接盘重绘。写入成功后必须记下新版本号，否则下一次保存会判自己陈旧、改动在画面上自己撤销（"点一次 + 卡片闪一下后消失"）。推荐配置是一个操作的往返，不是"清空再写"两步。

package/lib/index.js

@@ -8046,7 +8046,7 @@ function registerThemeTools(ctx, host) {
 	}), { when: () => host.permitted() });
 	ctx.tools.register(defineTool({
 		name: "background_edit",
-		description: "Change the user's wallpaper configuration. One action per call. Rules are matched against the model name top-down (first hit wins, rule 1 is the fallback) and an edit takes effect on the next repaint. Image bytes are addressed by slot; add_image downloads a URL into a new slot.",
+		description: "Change the user's wallpaper configuration. One action per call. Rules are matched against the model name top-down (first hit wins, rule 1 is the fallback) and an edit takes effect on the next repaint. Image bytes are addressed by slot; add_image downloads a URL into a new slot and lands it in fill.",
 		parameters: {
 			action: {
 				type: "string",
@@ -8081,7 +8081,7 @@ function registerThemeTools(ctx, host) {
 			},
 			matchColor: {
 				type: "string",
-				description: "set_rule: the RULE's own color as \"#rrggbb\", or \"system\" to follow the system theme. Only paints when the rule has no image."
+				description: "set_rule: the RULE's own color as \"#rrggbb\", or \"system\" to follow the system theme. Only paints when the rule has no image. Leave it out unless the user asked for a specific color."
 			},
 			slot: {
 				type: "string",
@@ -8090,7 +8090,7 @@ function registerThemeTools(ctx, host) {
 			layout: {
 				type: "string",
 				enum: BG_MODES,
-				description: "set_image: how the picture meets the viewport. fit letterboxes, fill crops, stretch distorts, tile repeats, center is unscaled."
+				description: "set_image: how the picture meets the viewport. fit letterboxes, fill crops, stretch distorts, tile repeats, center is unscaled. fill is the one to choose unless the user asks for another."
 			},
 			opacity: {
 				type: "number",
@@ -8106,11 +8106,11 @@ function registerThemeTools(ctx, host) {
 			},
 			imageColor: {
 				type: "string",
-				description: "set_image: this image's theme color as \"#rrggbb\", or \"system\"."
+				description: "set_image: overrides this image's theme color, as \"#rrggbb\" or \"system\". Omit it unless the user named a color: an image is themed from its own bytes when it arrives, and needs nothing supplied."
 			},
 			url: {
 				type: "string",
-				description: "add_image: an http(s) URL to download the picture from."
+				description: "add_image: an http(s) URL to download the picture from. Choose by subject, never by brightness: a dark picture and a light one both work, because the light/dark scheme follows the wallpaper rather than the other way round. Prefer a host reachable from mainland China — raw.githubusercontent.com and Google usually are not."
 			},
 			intervalSeconds: {
 				type: "number",
@@ -8178,7 +8178,7 @@ function registerThemeTools(ctx, host) {
 					if (rule !== void 0 && "error" in rule) return rule;
 					const target = rule ?? config.rules[0];
 					if (target === void 0) return { error: "there is no rule to add an image to; create one with set_rule first" };
-					target.images.push(defaultImage(got.slot));
+					target.images.push(defaultImage(got.slot, null, "fill"));
 					return `added image ${got.slot} to rule ${target.id}`;
 				});
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-background-by-model",
-  "version": "0.12.0-test.1",
+  "version": "0.12.0",
   "description": "Appearance plugin for DeepSeek Harness: an ordered list of model rules, each carrying its own wallpapers — every image with its own framing and theme color — plus layout mode, opacity, brightness and blur; the background follows the model you switch to, a rule can rotate through several images on its own rhythm, and an off-by-default switch lets the agent change any of it through two tools.",
   "keywords": [
     "deepseek-harness",