@dsh-plus/actual 0.1.0 → 0.1.1

package/lib/index.js

@@ -1,6 +1,6 @@
 import { pluginDataPath, unwrapVolatile } from "@dsh-plus/shared";
 import z from "@deepseek-ai/schemastery";
-import { ActualCli, DEFAULT_ALWAYS_ASK, DEFAULT_ALWAYS_ASK as DEFAULT_ALWAYS_ASK$1, DEFAULT_READ_ACTIONS, DEFAULT_READ_ACTIONS as DEFAULT_READ_ACTIONS$1, DEFAULT_READ_TOOLS, DEFAULT_READ_TOOLS as DEFAULT_READ_TOOLS$1, actionOf, askDisplayReason, classifyAction, computeDrift, createActualMcpServer, createEntryInvoker, createNodeDeps, discover, parseJsonOrText, sanitize, toSettings, versionStatusOf } from "@dsh-plus/actual-mcp";
+import { ActualCli, DEFAULT_ALWAYS_ASK, DEFAULT_ALWAYS_ASK as DEFAULT_ALWAYS_ASK$1, DEFAULT_READ_ACTIONS, DEFAULT_READ_ACTIONS as DEFAULT_READ_ACTIONS$1, DEFAULT_READ_TOOLS, DEFAULT_READ_TOOLS as DEFAULT_READ_TOOLS$1, actionOf, askDisplayReason, classifyAction, computeDrift, configSecretsOf, createActualMcpServer, createEntryInvoker, createNodeDeps, discover, parseJsonOrText, sanitize, toSettings, versionStatusOf } from "@dsh-plus/actual-mcp";
 import { Service } from "@deepseek-ai/cordis";
 import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
 //#region src/ns.ts
@@ -26,10 +26,12 @@ const SETTINGS_NS = "dsh-plus-actual";
 * loader 以活动引用原位提交热更新——消费端必须 `unwrapVolatile` 现取即热
 * （见 service.ts 的 `current()`）。
 *
-* **密钥不进用户层**：`password` / `sessionToken` / `encryptionPassword` 标
-* `.role('secret')`，describe 视图剥除其值、写入用户层也会被遮蔽，因此配置卡片
-* 不提供编辑器——它们只允许 profile 行级注入（`!!js process.env.…`）。
-* 见《插件存储规范》：密钥走环境变量/官方凭据，不落 settings。
+* **密钥不落 settings**：`password` / `sessionToken` / `encryptionPassword` 标
+* `.role('secret')`，describe 视图剥除其值、写入用户层也会被遮蔽，因此不提供
+* settings 编辑器。它们的落点有二：① 配置卡片的「凭据」小节（走官方
+* credentials seam，写 `$DSH_HOME/.credentials.yaml`）；② profile 行级注入
+* （`!!js process.env.…`）。行级声明了任一种认证即整组生效，否则回落到 seam。
+* 见《插件存储规范》与 credentials.ts。
 * @module @dsh-plus/actual/config
 */
 const Config = z.object({
@@ -39,9 +41,9 @@ const Config = z.object({
 	order: z.number().description("预设名册排序位").default(11).volatile(),
 	serverUrl: z.string().description("Actual 同步服务器基址（服务端版本探测 <serverUrl>/info）").default("http://127.0.0.1:5006").volatile(),
 	syncId: z.string().description("预算 Sync ID（Actual 客户端 → 设置 → 显示高级设置 → Sync ID；空 = 用 ACTUAL_SYNC_ID）").default("").volatile(),
-	password: z.string().role("secret").description("服务器口令（空 = 用 ACTUAL_PASSWORD / ACTUAL_PASSWORD_FILE；与 sessionToken 二选一）——密钥不进用户层，仅 profile 行级注入").default("").volatile(),
-	sessionToken: z.string().role("secret").description("会话令牌（优先于 password；空 = 用 ACTUAL_SESSION_TOKEN）——仅 profile 行级注入").default("").volatile(),
-	encryptionPassword: z.string().role("secret").description("端到端加密口令（仅加密预算需要；空 = 用 ACTUAL_ENCRYPTION_PASSWORD）——仅 profile 行级注入").default("").volatile(),
+	password: z.string().role("secret").description("服务器口令（与 sessionToken 二选一）——不落 settings：卡片「凭据」小节写凭据文件，或在此行级注入").default("").volatile(),
+	sessionToken: z.string().role("secret").description("会话令牌（优先于 password）——同上，卡片的「凭据」小节或行级注入").default("").volatile(),
+	encryptionPassword: z.string().role("secret").description("端到端加密口令（仅加密预算需要）——同上，卡片的「凭据」小节或行级注入").default("").volatile(),
 	dataDir: z.string().description("CLI 本地缓存目录（空 = 插件数据目录 cli-data，与用户自有 CLI 隔离）").default("").volatile(),
 	cacheTtl: z.number().description("CLI 缓存有效期（秒，官方默认 60）").default(60).volatile(),
 	lockTimeout: z.number().description("预算目录锁等待上限（秒，官方默认 10）").default(10).volatile(),
@@ -175,6 +177,49 @@ function actualPresetDefinition(config) {
 	};
 }
 //#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";
+//#endregion
+//#region src/credentials.ts
+/** 解析单个引用；seam 缺席或未配置一律视为空串。 */
+async function resolveOne(seam, ref) {
+	if (seam === null) return "";
+	const found = await seam.resolve(ref);
+	return found === void 0 ? "" : found.value;
+}
+/**
+* 解析本次调用使用的密钥三元组。
+* @param seam - 凭据 seam；缺席（profile 未挂 dsh-credentials）时只用行级配置。
+* @param declared - 行级 Config 声明的密钥。
+* @returns 已定妥优先级的密钥三元组。
+*/
+async function resolveSecrets(seam, declared) {
+	const authDeclared = declared.password !== "" || declared.sessionToken !== "";
+	return {
+		password: declared.password !== "" ? declared.password : authDeclared ? "" : await resolveOne(seam, REF_PASSWORD),
+		sessionToken: declared.sessionToken !== "" ? declared.sessionToken : authDeclared ? "" : await resolveOne(seam, REF_SESSION_TOKEN),
+		encryptionPassword: declared.encryptionPassword !== "" ? declared.encryptionPassword : await resolveOne(seam, REF_ENCRYPTION_PASSWORD)
+	};
+}
+//#endregion
 //#region src/mcp-session.ts
 /**
 * 进程内 MCP 会话：把 `@dsh-plus/actual-mcp` 的 MCP 服务端用 InMemoryTransport
@@ -642,23 +687,27 @@ var ActualService = class extends Service {
 	/** 按当前配置装配一个运行时，并把清单变更转发给服务级订阅者。 */
 	build() {
 		const config = this.current();
+		const cli = {
+			cliCommand: [...config.cliCommand],
+			serverUrl: config.serverUrl,
+			password: config.password,
+			sessionToken: config.sessionToken,
+			syncId: config.syncId,
+			dataDir: config.dataDir !== "" ? config.dataDir : pluginDataPath("actual", "cli-data"),
+			encryptionPassword: config.encryptionPassword,
+			cacheTtl: config.cacheTtl,
+			lockTimeout: config.lockTimeout
+		};
 		const runtime = new ActualRuntime({
-			cli: {
-				cliCommand: [...config.cliCommand],
-				serverUrl: config.serverUrl,
-				password: config.password,
-				sessionToken: config.sessionToken,
-				syncId: config.syncId,
-				dataDir: config.dataDir !== "" ? config.dataDir : pluginDataPath("actual", "cli-data"),
-				encryptionPassword: config.encryptionPassword,
-				cacheTtl: config.cacheTtl,
-				lockTimeout: config.lockTimeout
-			},
+			cli,
 			allow: [...config.allow],
 			deny: [...config.deny],
 			cliVersionPolicy: config.cliVersionPolicy,
 			toolCallTimeoutMs: config.toolCallTimeoutMs
-		}, this.deps, this.logger);
+		}, {
+			...this.deps,
+			resolveSecrets: () => resolveSecrets(this.credentialsSeam(), configSecretsOf(cli))
+		}, this.logger);
 		return {
 			runtime,
 			detach: runtime.onChange((manifest) => {
@@ -705,6 +754,17 @@ var ActualService = class extends Service {
 		this.listeners.add(cb);
 		return () => this.listeners.delete(cb);
 	}
+	/**
+	* credentials seam：**可选探测**而非硬 inject。
+	*
+	* 本插件在没挂 `dsh-credentials` 的 profile（headless/dev 精简组合）里也要能
+	* 起来，只是密钥退回「行级 Config + CLI 自身继承环境」；且探测发生在每次操作，
+	* seam 比本插件晚激活也能自然接上，不必声明时序。
+	*/
+	credentialsSeam() {
+		const found = this.ctx.get("credentials");
+		return found === void 0 || found === null ? null : found;
+	}
 	dispose() {
 		this.listeners.clear();
 		this.detach();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/actual",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "dsh-plus service + UI plugin: Actual Budget 能力发现（@actual-app/cli help 树运行时派生 × 进程内 MCP tools/list）、actual agent 预设注册与配置卡片——零手工工具清单",
   "type": "module",
   "main": "lib/index.js",
@@ -32,8 +32,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/client": "2.3.0",
-    "@dsh-plus/shared": "0.1.34",
-    "@dsh-plus/actual-mcp": "0.1.0"
+    "@dsh-plus/actual-mcp": "0.1.1",
+    "@dsh-plus/shared": "0.1.35"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5-alpha.1",

package/src/client/card.tsx

@@ -2,11 +2,12 @@
  * 「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
  */
 
@@ -32,11 +33,14 @@ import {
   validateDraft,
 } from './draft.ts'
 import type { Translate } from './i18n.ts'
+import type { CredentialsRemoteFace } from './secrets.ts'
+import { SecretsSection } from './secrets-section.tsx'
 
 export interface CardProps extends PluginConfigViewProps {
   t: Translate
   scope: Scope
   api: NamespaceSettingsApi
+  credentials: CredentialsRemoteFace
 }
 
 /** 小节共用的 props。 */
@@ -69,18 +73,11 @@ function violationProps(
 }
 
 /** 说明段落（无编辑器的字段在此交代落点）。 */
-function Note(props: {
-  title: string
-  body: string
-  snippet?: string
-  tail?: string
-}): ReactElement {
+function Note(props: { title: string; body: string }): ReactElement {
   return (
     <div className="act-note">
       <p className="act-noteTitle">{props.title}</p>
       <p className="act-noteBody">{props.body}</p>
-      {props.snippet !== undefined ? <code className="act-snippet">{props.snippet}</code> : null}
-      {props.tail !== undefined ? <p className="act-noteBody">{props.tail}</p> : null}
     </div>
   )
 }
@@ -174,7 +171,7 @@ function PolicySection(props: SectionProps): ReactElement {
 }
 
 export function ActualCard(props: CardProps): ReactElement | string | null {
-  const { t, scope, api } = props
+  const { t, scope, api, credentials } = props
   const { draft, dirty, saving, status, disabled, edit, reset, save } = useNamespaceDraft<
     ConfigValue,
     Draft
@@ -217,13 +214,8 @@ export function ActualCard(props: CardProps): ReactElement | string | null {
       />
       <p className="act-noteBody">{t('enabledHint')}</p>
       <ConnectionSection {...section} />
+      <SecretsSection t={t} face={credentials} />
       <PolicySection {...section} />
-      <Note
-        title={t('secretsTitle')}
-        body={t('secretsBody')}
-        snippet={t('secretsSnippet')}
-        tail={t('secretsTail')}
-      />
       <Note title={t('advancedTitle')} body={t('advancedBody')} />
     </CardChrome>
   )

package/src/client/client.ts

@@ -4,7 +4,8 @@
  * plugins.bundle.config）。
  * 构建产物为 window.__ModuleLoader__.load({id, factory}) 形式的 CJS factory
  * （包装见 tsdown.config.ts）；样式沿用官方 data-plugin-css 约定，HMR 据此卸载。
- * 配置读写经 ctx.remote.settings 直连（scope/api 来自 @dsh-plus/shared/client）。
+ * 配置读写经 ctx.remote.settings 直连（scope/api 来自 @dsh-plus/shared/client），
+ * 密钥读写经 ctx.remote.credentials（官方 settings-controller 的凭据命名空间）。
  * @module @dsh-plus/actual/client
  */
 import type { Context } from '@deepseek-ai/cordis'
@@ -13,21 +14,56 @@ import {
   createSettingsScope,
   injectPluginConfigCard,
   type PluginClientContext,
+  type RemoteLike,
 } from '@dsh-plus/shared/client'
 
 import { SETTINGS_NS } from '../ns.ts'
 import { ActualCard } from './card.tsx'
 import { type DictKey, en, NS, zh } from './i18n.ts'
+import type { CredentialsRemoteFace } from './secrets.ts'
 import { injectStyle } from './styles.ts'
 
 export const name = 'dsh-plus-actual'
 
-/** 浏览器半需要的 cordis 服务 key（loader 据此注入；package.json 的 dsh.client.inject 管包加载顺序）。 */
-export const inject = ['slots', 'locale', 'remote', 'remote.settings'] as const
+/**
+ * 浏览器半需要的 cordis 服务 key（loader 据此注入；package.json 的 dsh.client.inject 管包加载顺序）。
+ * `remote.credentials` 为硬依赖：卡片是密钥的唯一配置面，命名空间缺席时整张卡片
+ * 都不该挂（官方设置页同样如此声明）。
+ */
+export const inject = [
+  'slots',
+  'locale',
+  'remote',
+  'remote.settings',
+  'remote.credentials',
+] as const
 
 /** 宿主窄面收编在 @dsh-plus/shared/client；TKey 传入本包 DictKey 使键名受检。 */
 type ClientContext = PluginClientContext<DictKey>
 
+/** `remote` 服务加上凭据命名空间（inject 已声明，故按存在处理）。 */
+type RemoteWithCredentials = RemoteLike & {
+  credentials: Omit<CredentialsRemoteFace, 'onChange'>
+}
+
+/**
+ * 把官方 `remote.credentials` 收成窄面：只补一个把宿主事件包成订阅的方法，
+ * 让状态层不必认识 `$on` 的事件名与载荷形状。
+ */
+function credentialsFace(c: ClientContext): CredentialsRemoteFace {
+  const remote = c.get('remote') as RemoteWithCredentials
+  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)
+      }),
+  }
+}
+
 export function apply(ctx: Context): void {
   const c = ctx as unknown as ClientContext
   const tag = injectStyle()
@@ -40,11 +76,12 @@ export function apply(ctx: Context): void {
   c.effect(() => c.locale.register(NS, { zh, en }), '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',
     pkg: '@dsh-plus/actual',
     component: ActualCard,
-    inject: () => ({ t: c.locale.bind(NS), scope, api }),
+    inject: () => ({ t: c.locale.bind(NS), scope, api, credentials }),
   })
 }

package/src/client/i18n.ts

@@ -50,13 +50,21 @@ const ownZh = {
     '模型可见的工具名 = 前缀 + 命令族名（如 actual_accounts）。留空则直接用裸族名——query、server 等过于通用，不建议。',
   namePrefixInvalid: '只允许字母、数字、下划线与连字符',
 
-  secretsTitle: '服务器口令',
+  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 服务。',
+    '密钥单独存放，不进入会话、提示词与配置流，保存后立即生效（下一次工具调用即用新值）。三行都可留空：口令与会话令牌二选一即可，加密口令仅加密预算需要。',
+  secretPassword: '服务器口令',
+  secretPasswordHint: '自托管部署的登录口令。ACTUAL_LOGIN_METHOD=password 时用它换会话令牌。',
+  secretToken: '会话令牌',
+  secretTokenHint: '已有的会话令牌（优先于口令）。从浏览器开发者工具的 X-Actual-Token 头可取。',
+  secretEncryption: '端到端加密口令',
+  secretEncryptionHint: '仅当预算启用了端到端加密时需要；普通预算留空。',
+  secretSet: '已配置',
+  secretUnset: '未配置',
+  secretClear: '清除',
+  secretShadowed:
+    '该引用由 dsh 进程环境提供（只读层优先于凭据文件），卡片改不了：请改环境来源并重启 dsh。',
+  secretFailed: '凭据操作失败：',
 
   advancedTitle: '其余字段',
   advancedBody:
@@ -105,13 +113,24 @@ const ownEn = {
     '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',
+  secretsTitle: 'Credentials',
   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.',
+    '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:

package/src/client/secrets-section.tsx

@@ -0,0 +1,126 @@
+/**
+ * 「凭据」小节：三行密钥（服务器口令 / 会话令牌 / 端到端加密口令），
+ * 每行可写可清，右侧徽标显示「已配置 / 未配置」。
+ *
+ * 行内只做呈现与暂存：值一经保存即从输入框清空，不回显、不驻留 DOM；
+ * 引用被进程环境遮蔽（`writable:false`）时禁用编辑并说明原因——这正是
+ * 部署方把口令放进 systemd/shell 环境的场景，必须让用户看懂为什么改不了。
+ * @module @dsh-plus/actual/client/secrets-section
+ */
+import { Button, TextField } from '@dsh-plus/shared/client'
+import { type ReactElement, useState } from 'react'
+
+import { REF_ENCRYPTION_PASSWORD, REF_PASSWORD, REF_SESSION_TOKEN } from '../refs.ts'
+import type { DictKey, Translate } from './i18n.ts'
+import {
+  type CredentialsRemoteFace,
+  type CredentialView,
+  useCredentials,
+  viewOf,
+} from './secrets.ts'
+
+/** 一行密钥的定义：引用名 + 文案键。 */
+interface SecretRowSpec {
+  ref: string
+  labelKey: DictKey
+  hintKey: DictKey
+}
+
+/** 三行密钥的固定顺序（口令 → 令牌 → 加密口令）。 */
+export const SECRET_ROWS: readonly SecretRowSpec[] = [
+  { ref: REF_PASSWORD, labelKey: 'secretPassword', hintKey: 'secretPasswordHint' },
+  { ref: REF_SESSION_TOKEN, labelKey: 'secretToken', hintKey: 'secretTokenHint' },
+  {
+    ref: REF_ENCRYPTION_PASSWORD,
+    labelKey: 'secretEncryption',
+    hintKey: 'secretEncryptionHint',
+  },
+]
+
+interface SecretRowProps {
+  t: Translate
+  row: SecretRowSpec
+  view: CredentialView
+  busy: boolean
+  onSave(ref: string, value: string): Promise<boolean>
+  onClear(ref: string): Promise<boolean>
+}
+
+/** 单行密钥：输入框 + 保存/清除，保存成功后清空输入。 */
+function SecretRow(props: SecretRowProps): ReactElement {
+  const { t, row, view, busy } = props
+  const [text, setText] = useState('')
+  const locked = busy || !view.writable
+
+  return (
+    <div className="act-secret">
+      <TextField
+        prefix="act"
+        id={`act-secret-${row.ref}`}
+        label={t(row.labelKey)}
+        hint={t(row.hintKey)}
+        password
+        value={text}
+        disabled={locked}
+        badge={{ text: t(view.configured ? 'secretSet' : 'secretUnset'), set: view.configured }}
+        onEdit={setText}
+      />
+      <div className="act-secretActions">
+        <Button
+          prefix="act"
+          variant="primary"
+          label={t('save')}
+          disabled={locked || text === ''}
+          onClick={() => {
+            void props.onSave(row.ref, text).then((ok) => {
+              if (ok) setText('')
+            })
+          }}
+        />
+        <Button
+          prefix="act"
+          variant="ghost"
+          label={t('secretClear')}
+          disabled={locked || !view.configured}
+          onClick={() => {
+            void props.onClear(row.ref)
+          }}
+        />
+      </div>
+      {view.writable ? null : <p className="act-warn">{t('secretShadowed')}</p>}
+    </div>
+  )
+}
+
+/** 凭据小节（读写经官方 `remote.credentials`）。 */
+export function SecretsSection(props: { t: Translate; face: CredentialsRemoteFace }): ReactElement {
+  const { t, face } = props
+  const { views, busy, error, save, clear } = useCredentials(face)
+  return (
+    <div className="act-section">
+      <div className="act-sectionHead">
+        <h3 className="act-sectionTitle">{t('secretsTitle')}</h3>
+      </div>
+      <p className="act-sectionDesc">{t('secretsBody')}</p>
+      <div className="act-sectionBody">
+        {SECRET_ROWS.map((row) => (
+          <SecretRow
+            key={row.ref}
+            t={t}
+            row={row}
+            view={viewOf(views, row.ref)}
+            busy={busy}
+            onSave={save}
+            onClear={clear}
+          />
+        ))}
+      </div>
+      {error === '' ? null : (
+        <p className="act-warn">
+          {t('secretFailed')}
+          {error}
+        </p>
+      )}
+    </div>
+  )
+}

package/src/client/secrets.ts

@@ -0,0 +1,132 @@
+/**
+ * 浏览器半的凭据面：官方 settings-controller 的 `remote.credentials` 命名空间
+ * （describe/set/unset），复用官方 credentials seam，不另开 HTTP 端点。
+ * **值只写不读**——describe 只回「已配置 / 来源 / 可写」，没有任何方法回传值。
+ *
+ * 凭据与 settings 草稿相互独立：它不进命名空间、不参与脏判定，保存即落
+ * `$DSH_HOME/.credentials.yaml` 并热生效（宿主每次工具调用重新 resolve），
+ * 因此改口令不需要保存卡片、也不需要 /reload 或重启。
+ * @module @dsh-plus/actual/client/secrets
+ */
+import type { RemoteResult } from '@dsh-plus/shared/client'
+import { useCallback, useEffect, useState } from 'react'
+
+import { CREDENTIAL_REFS } from '../refs.ts'
+
+/** 单个引用的安全视图：没有能承载值的字段。 */
+export interface CredentialView {
+  configured: boolean
+  source?: string
+  writable: boolean
+}
+
+/** 卡片用到的 `remote.credentials` 方法面。 */
+export interface CredentialsRemoteFace {
+  describe(refs: readonly string[]): Promise<RemoteResult<Record<string, CredentialView>>>
+  set(ref: string, value: string): Promise<RemoteResult<unknown>>
+  unset(ref: string): Promise<RemoteResult<unknown>>
+  /** 订阅引用变更（宿主提交写入或观察到凭据文件被外部编辑时触发）。 */
+  onChange(listener: (ref: string) => void): () => void
+}
+
+/** 未答（或应答缺项）时的视图：按「未配置、可写」呈现。 */
+export const ABSENT_VIEW: CredentialView = { configured: false, writable: true }
+
+/** 取某引用的视图；应答缺项回落为 {@link ABSENT_VIEW}。 */
+export function viewOf(views: Record<string, CredentialView>, ref: string): CredentialView {
+  return views[ref] ?? ABSENT_VIEW
+}
+
+/** 应答信封的错误文案（成功为空串）。 */
+export function failureOf(result: RemoteResult<unknown>): string {
+  return result.ok ? '' : (result.error.message ?? '')
+}
+
+/** 提取异常文本。 */
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/** 凭据读写的卡片状态。 */
+export interface CredentialsState {
+  views: Record<string, CredentialView>
+  /** 有写入在途（按钮禁用用）。 */
+  busy: boolean
+  /** 最近一次失败文案（空串 = 无）。 */
+  error: string
+  /** 写入成功返回 true（调用方据此决定是否清空输入框）。 */
+  save(ref: string, value: string): Promise<boolean>
+  clear(ref: string): Promise<boolean>
+}
+
+/**
+ * 订阅宿主凭据变更：只认本插件关心的引用，其余（别的插件写自己的密钥）
+ * 不触发重读。
+ */
+function useCredentialChanges(face: CredentialsRemoteFace, read: () => void): void {
+  useEffect(
+    () =>
+      face.onChange((ref) => {
+        if ((CREDENTIAL_REFS as readonly string[]).includes(ref)) read()
+      }),
+    [face, read],
+  )
+}
+
+/**
+ * 凭据行状态：挂载即 describe 一次，写入后重新 describe；
+ * 外部改动经 `credentials/reference-updated` 触发同一路径刷新。
+ */
+export function useCredentials(face: CredentialsRemoteFace): CredentialsState {
+  const [views, setViews] = useState<Record<string, CredentialView>>({})
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState('')
+
+  const read = useCallback(async (): Promise<void> => {
+    const result = await face.describe([...CREDENTIAL_REFS])
+    if (!result.ok) {
+      setError(failureOf(result))
+      return
+    }
+    setError('')
+    setViews(result.value)
+  }, [face])
+
+  useEffect(() => {
+    void read()
+  }, [read])
+  useCredentialChanges(face, read)
+
+  const write = useCallback(
+    async (run: () => Promise<RemoteResult<unknown>>): Promise<boolean> => {
+      setBusy(true)
+      try {
+        const result = await run()
+        if (!result.ok) {
+          setError(failureOf(result))
+          return false
+        }
+        setError('')
+        await read()
+        return true
+      } catch (thrown: unknown) {
+        setError(messageOf(thrown))
+        return false
+      } finally {
+        setBusy(false)
+      }
+    },
+    [read],
+  )
+
+  const save = useCallback(
+    (ref: string, value: string): Promise<boolean> => write(() => face.set(ref, value)),
+    [face, write],
+  )
+  const clear = useCallback(
+    (ref: string): Promise<boolean> => write(() => face.unset(ref)),
+    [face, write],
+  )
+
+  return { views, busy, error, save, clear }
+}

package/src/client/styles.ts

@@ -1,6 +1,6 @@
 /**
  * 配置卡片样式：基础规则走 @dsh-plus/shared/client 的 cardCss('act')，
- * 本文件只补插件特有规则（说明段落与代码片段）。
+ * 本文件只补插件特有规则（说明段落与凭据行）。
  * 沿用官方 data-plugin / data-plugin-css 约定（HMR 据此卸载）。
  * @module @dsh-plus/actual/client/styles
  */
@@ -12,7 +12,8 @@ const extraCss = `
 .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}
 `
 
 export const cardCssAll = cardCss('act', extraCss)