@dsh-plus/actual 0.1.0 → 0.1.2

package/lib/client.js

@@ -7,6 +7,110 @@ window.__ModuleLoader__.load({
 		let react_jsx_runtime = require("react/jsx-runtime");
 		let react = require("react");
 		require("@deepseek-ai/dsh-client-ui-primitives");
+		//#region ../shared/src/client/fields.tsx
+		/** 卡片按钮（与 CardChrome 页脚同一套类名与视觉）。 */
+		function Button(props) {
+			const p = props.prefix ?? "dshp";
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+				type: "button",
+				className: `${p}-btn ${props.variant === "primary" ? `${p}-btnPrimary` : `${p}-btnGhost`}`,
+				disabled: props.disabled === true,
+				onClick: props.onClick,
+				children: props.label
+			});
+		}
+		function TextField(props) {
+			const p = props.prefix ?? "dshp";
+			const invalid = props.invalid === true;
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: `${p}-field`,
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: `${p}-head`,
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("label", {
+							className: `${p}-label`,
+							htmlFor: props.id,
+							children: props.label
+						}), props.badge !== void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: `${p}-badge ${props.badge.set ? `${p}-badgeSet` : `${p}-badgeUnset`}`,
+							children: props.badge.text
+						}) : null]
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+						id: props.id,
+						className: `${p}-input${invalid ? ` ${p}-inputInvalid` : ""}`,
+						type: props.password === true ? "password" : "text",
+						inputMode: props.numeric === true ? "numeric" : void 0,
+						autoComplete: props.password === true ? "off" : void 0,
+						"aria-invalid": invalid || void 0,
+						value: props.value,
+						disabled: props.disabled === true,
+						onChange: (event) => props.onEdit(event.target.value)
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: invalid ? `${p}-invalid` : `${p}-hint`,
+						children: invalid ? props.invalidLabel ?? "" : props.hint ?? ""
+					})
+				]
+			});
+		}
+		/**
+		* 勾选行：自绘圆角扁平开关（switch），对齐官方 WebUI 无原生 checkbox 的
+		* 设计语言（官方选择类控件全走胶囊/菜单，见 cardCss 的 -switch 规则）。
+		* 语义保持 checkbox（无障碍树与表单语义不变），视觉自绘。
+		*/
+		function CheckRow(props) {
+			const p = props.prefix ?? "dshp";
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: `${p}-checkRow`,
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+					id: props.id,
+					type: "checkbox",
+					role: "switch",
+					"aria-checked": props.checked,
+					checked: props.checked,
+					disabled: props.disabled === true,
+					onChange: (event) => props.onEdit(event.target.checked)
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("label", {
+					htmlFor: props.id,
+					children: props.label
+				})]
+			});
+		}
+		function SelectField(props) {
+			const p = props.prefix ?? "dshp";
+			const invalid = props.invalid === true;
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: `${p}-field`,
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: `${p}-head`,
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("label", {
+							className: `${p}-label`,
+							htmlFor: props.id,
+							children: props.label
+						})
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("select", {
+						id: props.id,
+						className: `${p}-select${invalid ? ` ${p}-inputInvalid` : ""}`,
+						"aria-invalid": invalid || void 0,
+						value: props.value,
+						disabled: props.disabled === true,
+						onChange: (event) => props.onEdit(event.target.value),
+						children: props.options.map((option) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("option", {
+							value: option.value,
+							children: option.label
+						}, option.value))
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: invalid ? `${p}-invalid` : `${p}-hint`,
+						children: invalid ? props.invalidLabel ?? "" : props.hint ?? ""
+					})
+				]
+			});
+		}
+		//#endregion
 		//#region ../shared/src/client/card.tsx
 		const IDLE_STATUS = {
 			kind: "idle",
@@ -55,12 +159,12 @@ window.__ModuleLoader__.load({
 									className: `${p}-status${props.status.kind === "error" ? ` ${p}-statusError` : ""}`,
 									role: "status",
 									children: props.status.text
-								}) : null, props.actions.map((action) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-									type: "button",
-									className: `${p}-btn ${action.variant === "primary" ? `${p}-btnPrimary` : `${p}-btnGhost`}`,
-									disabled: action.disabled === true,
-									onClick: action.onClick,
-									children: action.label
+								}) : null, props.actions.map((action) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Button, {
+									prefix: p,
+									label: action.label,
+									variant: action.variant,
+									disabled: action.disabled,
+									onClick: action.onClick
 								}, action.key))]
 							})
 						]
@@ -181,99 +285,6 @@ window.__ModuleLoader__.load({
 			};
 		}
 		//#endregion
-		//#region ../shared/src/client/fields.tsx
-		function TextField(props) {
-			const p = props.prefix ?? "dshp";
-			const invalid = props.invalid === true;
-			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-				className: `${p}-field`,
-				children: [
-					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-						className: `${p}-head`,
-						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("label", {
-							className: `${p}-label`,
-							htmlFor: props.id,
-							children: props.label
-						}), props.badge !== void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-							className: `${p}-badge ${props.badge.set ? `${p}-badgeSet` : `${p}-badgeUnset`}`,
-							children: props.badge.text
-						}) : null]
-					}),
-					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
-						id: props.id,
-						className: `${p}-input${invalid ? ` ${p}-inputInvalid` : ""}`,
-						type: props.password === true ? "password" : "text",
-						inputMode: props.numeric === true ? "numeric" : void 0,
-						autoComplete: props.password === true ? "off" : void 0,
-						"aria-invalid": invalid || void 0,
-						value: props.value,
-						disabled: props.disabled === true,
-						onChange: (event) => props.onEdit(event.target.value)
-					}),
-					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-						className: invalid ? `${p}-invalid` : `${p}-hint`,
-						children: invalid ? props.invalidLabel ?? "" : props.hint ?? ""
-					})
-				]
-			});
-		}
-		/**
-		* 勾选行：自绘圆角扁平开关（switch），对齐官方 WebUI 无原生 checkbox 的
-		* 设计语言（官方选择类控件全走胶囊/菜单，见 cardCss 的 -switch 规则）。
-		* 语义保持 checkbox（无障碍树与表单语义不变），视觉自绘。
-		*/
-		function CheckRow(props) {
-			const p = props.prefix ?? "dshp";
-			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-				className: `${p}-checkRow`,
-				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
-					id: props.id,
-					type: "checkbox",
-					role: "switch",
-					"aria-checked": props.checked,
-					checked: props.checked,
-					disabled: props.disabled === true,
-					onChange: (event) => props.onEdit(event.target.checked)
-				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("label", {
-					htmlFor: props.id,
-					children: props.label
-				})]
-			});
-		}
-		function SelectField(props) {
-			const p = props.prefix ?? "dshp";
-			const invalid = props.invalid === true;
-			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-				className: `${p}-field`,
-				children: [
-					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-						className: `${p}-head`,
-						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("label", {
-							className: `${p}-label`,
-							htmlFor: props.id,
-							children: props.label
-						})
-					}),
-					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("select", {
-						id: props.id,
-						className: `${p}-select${invalid ? ` ${p}-inputInvalid` : ""}`,
-						"aria-invalid": invalid || void 0,
-						value: props.value,
-						disabled: props.disabled === true,
-						onChange: (event) => props.onEdit(event.target.value),
-						children: props.options.map((option) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("option", {
-							value: option.value,
-							children: option.label
-						}, option.value))
-					}),
-					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-						className: invalid ? `${p}-invalid` : `${p}-hint`,
-						children: invalid ? props.invalidLabel ?? "" : props.hint ?? ""
-					})
-				]
-			});
-		}
-		//#endregion
 		//#region ../shared/src/client/i18n.ts
 		/** 卡片通用文案（save/discard/unsaved/loading 等四插件共有键）。 */
 		const commonZh = {
@@ -567,16 +578,235 @@ ${extra}
 			};
 		}
 		//#endregion
+		//#region src/refs.ts
+		/**
+		* 凭据引用名字面量（纯常量，零依赖）。
+		*
+		* 宿主半（credentials.ts 的 seam 解析）与浏览器半（配置卡片的
+		* `remote.credentials` 读写）共用同一份取值；浏览器包不得经此路径拖入
+		* `@dsh-plus/actual-mcp` 的 node 侧实现（child_process 等），故字面量独立成模块。
+		*
+		* **必须与 `@dsh-plus/actual-mcp` 的 `SECRET_ENV` 逐字一致**：引用名与官方 CLI
+		* 原生读取的环境变量名同形（`ACTUAL_` 前缀亦符合《插件存储规范》的
+		* `<PLUGIN_ID>_` 大写约定），凭据文件里的一处配置才能同时被 seam 解析、
+		* 又被 CLI 自身继承环境读到。该一致性由 `tests/refs.test.ts` 钉住。
+		* @module @dsh-plus/actual/refs
+		*/
+		/** 服务器口令。 */
+		const REF_PASSWORD = "ACTUAL_PASSWORD";
+		/** 会话令牌（官方 CLI 优先于口令）。 */
+		const REF_SESSION_TOKEN = "ACTUAL_SESSION_TOKEN";
+		/** 端到端加密口令（仅加密预算需要）。 */
+		const REF_ENCRYPTION_PASSWORD = "ACTUAL_ENCRYPTION_PASSWORD";
+		/** 卡片展示与批量 describe 使用的引用清单（顺序即展示顺序）。 */
+		const CREDENTIAL_REFS = [
+			REF_PASSWORD,
+			REF_SESSION_TOKEN,
+			REF_ENCRYPTION_PASSWORD
+		];
+		//#endregion
+		//#region src/client/secrets.ts
+		/** 未答（或应答缺项）时的视图：按「未配置、可写」呈现。 */
+		const ABSENT_VIEW = {
+			configured: false,
+			writable: true
+		};
+		/** 取某引用的视图；应答缺项回落为 {@link ABSENT_VIEW}。 */
+		function viewOf(views, ref) {
+			return views[ref] ?? ABSENT_VIEW;
+		}
+		/** 应答信封的错误文案（成功为空串）。 */
+		function failureOf(result) {
+			return result.ok ? "" : result.error.message ?? "";
+		}
+		/** 提取异常文本。 */
+		function messageOf(error) {
+			return error instanceof Error ? error.message : String(error);
+		}
+		/**
+		* 订阅宿主凭据变更：只认本插件关心的引用，其余（别的插件写自己的密钥）
+		* 不触发重读。
+		*/
+		function useCredentialChanges(face, read) {
+			(0, react.useEffect)(() => face.onChange((ref) => {
+				if (CREDENTIAL_REFS.includes(ref)) read();
+			}), [face, read]);
+		}
+		/**
+		* 凭据行状态：挂载即 describe 一次，写入后重新 describe；
+		* 外部改动经 `credentials/reference-updated` 触发同一路径刷新。
+		*/
+		function useCredentials(face) {
+			const [views, setViews] = (0, react.useState)({});
+			const [busy, setBusy] = (0, react.useState)(false);
+			const [error, setError] = (0, react.useState)("");
+			const read = (0, react.useCallback)(async () => {
+				const result = await face.describe([...CREDENTIAL_REFS]);
+				if (!result.ok) {
+					setError(failureOf(result));
+					return;
+				}
+				setError("");
+				setViews(result.value);
+			}, [face]);
+			(0, react.useEffect)(() => {
+				read();
+			}, [read]);
+			useCredentialChanges(face, read);
+			const write = (0, react.useCallback)(async (run) => {
+				setBusy(true);
+				try {
+					const result = await run();
+					if (!result.ok) {
+						setError(failureOf(result));
+						return false;
+					}
+					setError("");
+					await read();
+					return true;
+				} catch (thrown) {
+					setError(messageOf(thrown));
+					return false;
+				} finally {
+					setBusy(false);
+				}
+			}, [read]);
+			return {
+				views,
+				busy,
+				error,
+				save: (0, react.useCallback)((ref, value) => write(() => face.set(ref, value)), [face, write]),
+				clear: (0, react.useCallback)((ref) => write(() => face.unset(ref)), [face, write])
+			};
+		}
+		//#endregion
+		//#region src/client/secrets-section.tsx
+		/**
+		* 「凭据」小节：三行密钥（服务器口令 / 会话令牌 / 端到端加密口令），
+		* 每行可写可清，右侧徽标显示「已配置 / 未配置」。
+		*
+		* 行内只做呈现与暂存：值一经保存即从输入框清空，不回显、不驻留 DOM；
+		* 引用被进程环境遮蔽（`writable:false`）时禁用编辑并说明原因——这正是
+		* 部署方把口令放进 systemd/shell 环境的场景，必须让用户看懂为什么改不了。
+		* @module @dsh-plus/actual/client/secrets-section
+		*/
+		/** 三行密钥的固定顺序（口令 → 令牌 → 加密口令）。 */
+		const SECRET_ROWS = [
+			{
+				ref: REF_PASSWORD,
+				labelKey: "secretPassword",
+				hintKey: "secretPasswordHint"
+			},
+			{
+				ref: REF_SESSION_TOKEN,
+				labelKey: "secretToken",
+				hintKey: "secretTokenHint"
+			},
+			{
+				ref: REF_ENCRYPTION_PASSWORD,
+				labelKey: "secretEncryption",
+				hintKey: "secretEncryptionHint"
+			}
+		];
+		/** 单行密钥：输入框 + 保存/清除，保存成功后清空输入。 */
+		function SecretRow(props) {
+			const { t, row, view, busy } = props;
+			const [text, setText] = (0, react.useState)("");
+			const locked = busy || !view.writable;
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: "act-secret",
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(TextField, {
+						prefix: "act",
+						id: `act-secret-${row.ref}`,
+						label: t(row.labelKey),
+						hint: t(row.hintKey),
+						password: true,
+						value: text,
+						disabled: locked,
+						badge: {
+							text: t(view.configured ? "secretSet" : "secretUnset"),
+							set: view.configured
+						},
+						onEdit: setText
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "act-secretActions",
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Button, {
+							prefix: "act",
+							variant: "primary",
+							label: t("save"),
+							disabled: locked || text === "",
+							onClick: () => {
+								props.onSave(row.ref, text).then((ok) => {
+									if (ok) setText("");
+								});
+							}
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Button, {
+							prefix: "act",
+							variant: "ghost",
+							label: t("secretClear"),
+							disabled: locked || !view.configured,
+							onClick: () => {
+								props.onClear(row.ref);
+							}
+						})]
+					}),
+					view.writable ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: "act-warn",
+						children: t("secretShadowed")
+					})
+				]
+			});
+		}
+		/** 凭据小节（读写经官方 `remote.credentials`）。 */
+		function SecretsSection(props) {
+			const { t, face } = props;
+			const { views, busy, error, save, clear } = useCredentials(face);
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: "act-section",
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: "act-sectionHead",
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("h3", {
+							className: "act-sectionTitle",
+							children: t("secretsTitle")
+						})
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: "act-sectionDesc",
+						children: t("secretsBody")
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: "act-sectionBody",
+						children: SECRET_ROWS.map((row) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SecretRow, {
+							t,
+							row,
+							view: viewOf(views, row.ref),
+							busy,
+							onSave: save,
+							onClear: clear
+						}, row.ref))
+					}),
+					error === "" ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("p", {
+						className: "act-warn",
+						children: [t("secretFailed"), error]
+					})
+				]
+			});
+		}
+		//#endregion
 		//#region src/client/card.tsx
 		/**
 		* 「Actual Budget 连接」配置卡片：经 injectPluginConfigCard 注册（插件页
 		* plugins.row.config / plugins.bundle.config，view 分发 summary/page）。
 		*
-		* 编辑范围只覆盖**非密钥**字段。密钥与高级字段没有编辑器，卡片内给出明确落点
-		* （见 i18n 的 secretsBody / advancedBody）——按《插件开发指南》，可配置项要么
-		* 有编辑器、要么写明为什么没有与改在哪里配。
+		* 编辑范围覆盖全部可公开字段与三行密钥：非密钥字段走 settings 草稿（脏判定 +
+		* 保存按钮），密钥走官方 credentials seam（各自即时保存，与草稿互不干扰）。
+		* 剩余无编辑器的字段在卡片内给出明确落点（见 i18n 的 advancedBody）——按
+		* 《插件开发指南》，可配置项要么有编辑器、要么写明为什么没有与改在哪里配。
 		*
-		* 字段按主题拆成两个小节组件，卡片本体只负责外壳、状态与保存动作。
+		* 字段按主题拆成小节组件，卡片本体只负责外壳、状态与保存动作。
 		* @module @dsh-plus/actual/client/card
 		*/
 		/** 模块级稳定函数：参与 useNamespaceDraft 的依赖比较。 */
@@ -600,24 +830,13 @@ ${extra}
 		function Note(props) {
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				className: "act-note",
-				children: [
-					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-						className: "act-noteTitle",
-						children: props.title
-					}),
-					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-						className: "act-noteBody",
-						children: props.body
-					}),
-					props.snippet !== void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", {
-						className: "act-snippet",
-						children: props.snippet
-					}) : null,
-					props.tail !== void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-						className: "act-noteBody",
-						children: props.tail
-					}) : null
-				]
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+					className: "act-noteTitle",
+					children: props.title
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+					className: "act-noteBody",
+					children: props.body
+				})]
 			});
 		}
 		/** 连接小节：服务器地址、预算、CLI 命令与版本策略。 */
@@ -712,7 +931,7 @@ ${extra}
 			] });
 		}
 		function ActualCard(props) {
-			const { t, scope, api } = props;
+			const { t, scope, api, credentials } = props;
 			const { draft, dirty, saving, status, disabled, edit, reset, save } = useNamespaceDraft({
 				scope,
 				api,
@@ -771,13 +990,11 @@ ${extra}
 						children: t("enabledHint")
 					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(ConnectionSection, { ...section }),
-					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(PolicySection, { ...section }),
-					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Note, {
-						title: t("secretsTitle"),
-						body: t("secretsBody"),
-						snippet: t("secretsSnippet"),
-						tail: t("secretsTail")
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(SecretsSection, {
+						t,
+						face: credentials
 					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(PolicySection, { ...section }),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Note, {
 						title: t("advancedTitle"),
 						body: t("advancedBody")
@@ -806,7 +1023,7 @@ ${extra}
 			serverUrlHint: "自托管默认 http://127.0.0.1:5006。服务端版本从 <地址>/info 读取，用于版本一致性告警。",
 			serverUrlInvalid: "必须是 http(s):// 开头的完整地址",
 			syncId: "预算 Sync ID",
-			syncIdHint: "Actual 客户端 → 设置 → 显示高级设置 → Sync ID。留空则读环境变量 ACTUAL_SYNC_ID。多数命令都需要它。",
+			syncIdHint: "Actual 客户端 → 设置 → 显示高级设置 → Sync ID，即 budgets list 里的 groupId；不要填同一条目里的 cloudFileId（填错会报 Budget not found）。留空则读环境变量 ACTUAL_SYNC_ID。",
 			cliCommand: "CLI 命令",
 			cliCommandHint: "留空 = 自动探测（ACTUAL_CLI 环境变量 → PATH 上的 actual → 包内 @actual-app/cli）。需要指定具体副本时填完整 argv，如 node /opt/actual/dist/cli.js（空格分隔，不支持引号）。",
 			cliCommandInvalid: "不支持引号：请直接以空格分隔各个参数",
@@ -821,10 +1038,19 @@ ${extra}
 			namePrefix: "工具名前缀",
 			namePrefixHint: "模型可见的工具名 = 前缀 + 命令族名（如 actual_accounts）。留空则直接用裸族名——query、server 等过于通用，不建议。",
 			namePrefixInvalid: "只允许字母、数字、下划线与连字符",
-			secretsTitle: "服务器口令",
-			secretsBody: "口令属密钥：它不进用户层配置，卡片也不提供输入框（写进来会被脱敏遮蔽，等于白填）。请在 profile 的 cordis.patch.yml 里做行级注入，口令本身放环境变量：",
-			secretsSnippet: "- id: dsh-plus-actual\n  config:\n    syncId: !!js process.env.ACTUAL_SYNC_ID\n    password: !!js process.env.ACTUAL_PASSWORD",
-			secretsTail: "把 ACTUAL_PASSWORD 放进 dsh 服务进程的环境（systemd 的 EnvironmentFile）。官方 CLI 还支持 ACTUAL_PASSWORD_FILE——更适合密钥文件；encrypted 预算另需 ACTUAL_ENCRYPTION_PASSWORD。改动环境变量后需重启 dsh 服务。",
+			secretsTitle: "凭据",
+			secretsBody: "密钥单独存放，不进入会话、提示词与配置流，保存后立即生效（下一次工具调用即用新值）。三行都可留空：口令与会话令牌二选一即可，加密口令仅加密预算需要。",
+			secretPassword: "服务器口令",
+			secretPasswordHint: "自托管部署的登录口令。ACTUAL_LOGIN_METHOD=password 时用它换会话令牌。",
+			secretToken: "会话令牌",
+			secretTokenHint: "已有的会话令牌（优先于口令）。从浏览器开发者工具的 X-Actual-Token 头可取。",
+			secretEncryption: "端到端加密口令",
+			secretEncryptionHint: "仅当预算启用了端到端加密时需要；普通预算留空。",
+			secretSet: "已配置",
+			secretUnset: "未配置",
+			secretClear: "清除",
+			secretShadowed: "该引用由 dsh 进程环境提供（只读层优先于凭据文件），卡片改不了：请改环境来源并重启 dsh。",
+			secretFailed: "凭据操作失败：",
 			advancedTitle: "其余字段",
 			advancedBody: "以下字段只在 profile 的 cordis.patch.yml 里配置：预算目录与超时（dataDir / cacheTtl / lockTimeout / toolCallTimeoutMs）、工具暴露与读写判定（allow / deny / readActions / alwaysAsk / readTools）、预设显示与提示词（name / description / order / personaPrefix / includeRuntimeContext）。"
 		};
@@ -838,7 +1064,7 @@ ${extra}
 			serverUrlHint: "Self-hosted default is http://127.0.0.1:5006. The server version is read from <url>/info for the version-mismatch warning.",
 			serverUrlInvalid: "Must be a full http(s):// URL",
 			syncId: "Budget sync ID",
-			syncIdHint: "Actual client → Settings → Show advanced settings → Sync ID. Empty falls back to the ACTUAL_SYNC_ID environment variable. Most commands need it.",
+			syncIdHint: "Actual client → Settings → Show advanced settings → Sync ID, i.e. the groupId in budgets list; not the cloudFileId of the same entry (a wrong value reports Budget not found). Empty falls back to ACTUAL_SYNC_ID.",
 			cliCommand: "CLI command",
 			cliCommandHint: "Empty = auto-detect (ACTUAL_CLI env → actual on PATH → bundled @actual-app/cli). To pin a specific copy, give the full argv, e.g. node /opt/actual/dist/cli.js (space-separated, no quotes).",
 			cliCommandInvalid: "Quotes are not supported: separate arguments with spaces",
@@ -853,10 +1079,19 @@ ${extra}
 			namePrefix: "Tool name prefix",
 			namePrefixHint: "Model-visible tool name = prefix + command family (e.g. actual_accounts). Empty uses bare family names — query, server and tags are too generic, so a prefix is advised.",
 			namePrefixInvalid: "Letters, digits, underscore and hyphen only",
-			secretsTitle: "Server password",
-			secretsBody: "The password is a secret: it never enters the user-layer configuration, and this card offers no input for it (a value written here is masked away — filling it in would do nothing). Inject it at the profile row in cordis.patch.yml and keep the value in the environment:",
-			secretsSnippet: "- id: dsh-plus-actual\n  config:\n    syncId: !!js process.env.ACTUAL_SYNC_ID\n    password: !!js process.env.ACTUAL_PASSWORD",
-			secretsTail: "Put ACTUAL_PASSWORD into the dsh service process environment (systemd EnvironmentFile). The official CLI also supports ACTUAL_PASSWORD_FILE, which suits secret files better; an encrypted budget additionally needs ACTUAL_ENCRYPTION_PASSWORD. Restart the dsh service after changing environment variables.",
+			secretsTitle: "Credentials",
+			secretsBody: "Secrets live separately — they never enter the conversation, the prompt or the settings stream, and a save applies immediately (the next tool call uses it). All three may stay empty: password and session token are alternatives, and the encryption password is only needed for encrypted budgets.",
+			secretPassword: "Server password",
+			secretPasswordHint: "The login password of your self-hosted deployment. Exchanged for a session token when ACTUAL_LOGIN_METHOD=password.",
+			secretToken: "Session token",
+			secretTokenHint: "An existing session token; it takes precedence over the password. Read it from the X-Actual-Token header in devtools.",
+			secretEncryption: "End-to-end encryption password",
+			secretEncryptionHint: "Only needed when the budget has end-to-end encryption enabled; leave empty otherwise.",
+			secretSet: "Configured",
+			secretUnset: "Not configured",
+			secretClear: "Clear",
+			secretShadowed: "This reference comes from the dsh process environment, which shadows the credentials file and cannot be edited here. Change the environment source and restart dsh.",
+			secretFailed: "Credential operation failed: ",
 			advancedTitle: "Remaining fields",
 			advancedBody: "These are configured only in the profile cordis.patch.yml: budget directory and timeouts (dataDir / cacheTtl / lockTimeout / toolCallTimeoutMs), tool exposure and read/write classification (allow / deny / readActions / alwaysAsk / readTools), and preset display and prompt (name / description / order / personaPrefix / includeRuntimeContext)."
 		};
@@ -866,7 +1101,7 @@ ${extra}
 		//#region src/client/styles.ts
 		/**
 		* 配置卡片样式：基础规则走 @dsh-plus/shared/client 的 cardCss('act')，
-		* 本文件只补插件特有规则（说明段落与代码片段）。
+		* 本文件只补插件特有规则（说明段落与凭据行）。
 		* 沿用官方 data-plugin / data-plugin-css 约定（HMR 据此卸载）。
 		* @module @dsh-plus/actual/client/styles
 		*/
@@ -875,7 +1110,8 @@ ${extra}
 .act-note{margin:14px 0 0;padding:10px 12px;border-radius:8px;background:var(--dsw-alias-bg-base);border:1px solid var(--dsw-alias-border-l2)}
 .act-noteTitle{margin:0 0 6px;font-size:13px;font-weight:600}
 .act-noteBody{margin:0;color:var(--dsw-alias-label-secondary);font-size:12px;line-height:1.6}
-.act-snippet{display:block;margin:8px 0 0;padding:8px 10px;border-radius:6px;background:var(--dsw-alias-bg-base);color:var(--dsw-alias-label-primary);font-family:var(--dsw-font-family-mono,monospace);font-size:11px;line-height:1.5;white-space:pre;overflow-x:auto}
+.act-secret{border-top:1px solid var(--dsw-alias-border-l2)}
+.act-secretActions{display:flex;gap:8px;padding:0 0 12px}
 `);
 		/** 幂等注入样式标签；返回标签（已存在或环境无 document 时为 null）。 */
 		function injectStyle() {
@@ -884,13 +1120,34 @@ ${extra}
 		//#endregion
 		//#region src/client/client.ts
 		const name = "dsh-plus-actual";
-		/** 浏览器半需要的 cordis 服务 key（loader 据此注入；package.json 的 dsh.client.inject 管包加载顺序）。 */
+		/**
+		* 浏览器半需要的 cordis 服务 key（loader 据此注入；package.json 的 dsh.client.inject 管包加载顺序）。
+		* `remote.credentials` 为硬依赖：卡片是密钥的唯一配置面，命名空间缺席时整张卡片
+		* 都不该挂（官方设置页同样如此声明）。
+		*/
 		const inject = [
 			"slots",
 			"locale",
 			"remote",
-			"remote.settings"
+			"remote.settings",
+			"remote.credentials"
 		];
+		/**
+		* 把官方 `remote.credentials` 收成窄面：只补一个把宿主事件包成订阅的方法，
+		* 让状态层不必认识 `$on` 的事件名与载荷形状。
+		*/
+		function credentialsFace(c) {
+			const remote = c.get("remote");
+			const { credentials } = remote;
+			return {
+				describe: (refs) => credentials.describe(refs),
+				set: (ref, value) => credentials.set(ref, value),
+				unset: (ref) => credentials.unset(ref),
+				onChange: (listener) => remote.$on("credentials/reference-updated", (ref) => {
+					if (typeof ref === "string") listener(ref);
+				})
+			};
+		}
 		function apply(ctx) {
 			const c = ctx;
 			const tag = injectStyle();
@@ -903,6 +1160,7 @@ ${extra}
 			}), "actual: locale");
 			const scope = createSettingsScope(c, SETTINGS_NS, "actual: settings scope");
 			const api = createNamespaceApi(c.get("remote").settings, SETTINGS_NS);
+			const credentials = credentialsFace(c);
 			injectPluginConfigCard(c.slots, {
 				ns: SETTINGS_NS,
 				rowId: "dsh-plus-actual",
@@ -911,7 +1169,8 @@ ${extra}
 				inject: () => ({
 					t: c.locale.bind(NS),
 					scope,
-					api
+					api,
+					credentials
 				})
 			});
 		}