@dsh-plus/actual 0.1.0 → 0.1.2

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)

package/src/config.ts

@@ -9,10 +9,12 @@
  * 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
  */
 
@@ -61,22 +63,20 @@ export const Config = z.object({
     .string()
     .role('secret')
     .description(
-      '服务器口令（空 = 用 ACTUAL_PASSWORD / ACTUAL_PASSWORD_FILE；与 sessionToken 二选一）——密钥不进用户层，仅 profile 行级注入',
+      '服务器口令（与 sessionToken 二选一）——不落 settings：卡片「凭据」小节写凭据文件，或在此行级注入',
     )
     .default('')
     .volatile(),
   sessionToken: z
     .string()
     .role('secret')
-    .description('会话令牌（优先于 password；空 = 用 ACTUAL_SESSION_TOKEN）——仅 profile 行级注入')
+    .description('会话令牌（优先于 password）——同上，卡片的「凭据」小节或行级注入')
     .default('')
     .volatile(),
   encryptionPassword: z
     .string()
     .role('secret')
-    .description(
-      '端到端加密口令（仅加密预算需要；空 = 用 ACTUAL_ENCRYPTION_PASSWORD）——仅 profile 行级注入',
-    )
+    .description('端到端加密口令（仅加密预算需要）——同上，卡片的「凭据」小节或行级注入')
     .default('')
     .volatile(),
   dataDir: z

package/src/credentials.ts

@@ -0,0 +1,77 @@
+/**
+ * 凭据解析：Actual 的三个密钥走官方 credentials seam
+ * （`$DSH_HOME/.credentials.yaml`，经 `ctx.credentials`），**每次操作即时
+ * resolve、不跨操作缓存**——在配置卡片里改口令后，下一次工具调用即生效。
+ *
+ * 引用名即官方 CLI 原生读取的环境变量名（见 refs.ts 与 `@dsh-plus/actual-mcp`
+ * 的 `SECRET_ENV`）：`ACTUAL_` 前缀符合《插件存储规范》的 `<PLUGIN_ID>_` 大写
+ * 约定，同时让 seam 的继承环境层与 CLI 自己的环境读取指向同一处配置——
+ * 无论口令来自 `.credentials.yaml` 还是进程环境，两条路径都拿得到。
+ *
+ * 优先级：**行级 Config 声明了任一种认证即整组生效**。`role('secret')` 字段
+ * 是部署方在 profile 里的显式意图，不该被 seam 里的另一半悄悄改写；只有在
+ * 行级配置没声明认证时才去问 seam。端到端加密口令与认证正交，单独解析。
+ * @module @dsh-plus/actual/credentials
+ */
+
+import type { CliSecrets } from '@dsh-plus/actual-mcp'
+
+import { REF_ENCRYPTION_PASSWORD, REF_PASSWORD, REF_SESSION_TOKEN } from './refs.ts'
+
+/**
+ * credentials seam 的最小面。
+ *
+ * 只声明用到的 `resolve`：值的写入发生在浏览器半（官方 `remote.credentials`
+ * 命名空间），宿主半不需要 set/unset。
+ *
+ * 引用名以 `unknown` 收、按普通字符串传：`CredentialRef` 是
+ * `string & { readonly [BRAND]: B }` 的**纯编译期**品牌（`BRAND` 只有类型声明，
+ * 无运行期取值，官方文档亦声明 `brandString` 不改动值），故传裸环境变量名与
+ * 经 `credentialRef()` 品牌化在运行期完全等价。这样本插件不必依赖
+ * `@deepseek-ai/dsh-credentials` 的包树，在未挂该 seam 的 profile 里也能 load。
+ */
+export interface CredentialsFace {
+  /** 解析一个引用；未配置返回 undefined。 */
+  resolve(ref: unknown): Promise<{ value: string; source: string } | undefined>
+}
+
+/** 行级 Config 声明的密钥（空串 = 未声明）。 */
+export type DeclaredSecrets = CliSecrets
+
+/** 解析单个引用；seam 缺席或未配置一律视为空串。 */
+async function resolveOne(seam: CredentialsFace | null, ref: string): Promise<string> {
+  if (seam === null) return ''
+  const found = await seam.resolve(ref)
+  return found === undefined ? '' : found.value
+}
+
+/**
+ * 解析本次调用使用的密钥三元组。
+ * @param seam - 凭据 seam；缺席（profile 未挂 dsh-credentials）时只用行级配置。
+ * @param declared - 行级 Config 声明的密钥。
+ * @returns 已定妥优先级的密钥三元组。
+ */
+export async function resolveSecrets(
+  seam: CredentialsFace | null,
+  declared: DeclaredSecrets,
+): Promise<CliSecrets> {
+  // 行级 Config 是显式意图：声明了口令或令牌就整组作数，不再混入 seam 的另一半。
+  const authDeclared = declared.password !== '' || declared.sessionToken !== ''
+  const password =
+    declared.password !== ''
+      ? declared.password
+      : authDeclared
+        ? ''
+        : await resolveOne(seam, REF_PASSWORD)
+  const sessionToken =
+    declared.sessionToken !== ''
+      ? declared.sessionToken
+      : authDeclared
+        ? ''
+        : await resolveOne(seam, REF_SESSION_TOKEN)
+  const encryptionPassword =
+    declared.encryptionPassword !== ''
+      ? declared.encryptionPassword
+      : await resolveOne(seam, REF_ENCRYPTION_PASSWORD)
+  return { password, sessionToken, encryptionPassword }
+}

package/src/index.ts

@@ -40,10 +40,12 @@ export {
   actionOf,
   askDisplayReason,
   type ClassifySettings,
+  callToolResultOf,
   classifyAction,
   DEFAULT_ALWAYS_ASK,
   DEFAULT_READ_ACTIONS,
   DEFAULT_READ_TOOLS,
+  formatToolValue,
   toSettings,
 } from '@dsh-plus/actual-mcp'
 export { ACTUAL_PRESET_ID, actualPresetDefinition } from './definition.ts'

package/src/mcp-session.ts

@@ -3,8 +3,10 @@
  * 接到官方客户端上——**格式二（DSH 工具）由格式一（MCP tools/list）引出**，
  * 与思源「MCP 为主源、CLI 为兜底」同构，且不额外起进程。
  *
- * 工具调用的返回值经「JSON → 文本 → JSON」往返，与直连 CLI 路径形状一致；
- * 服务端已把工具失败表示为 `isError` 结果，这里转成异常上抛，绝不触发兜底重放
+ * 成功时**原样返回 canonical MCP 结果信封**（`CallToolResult`），不在此层解包：
+ * DSH 侧 `source: 'mcp'` 的条目由官方 `createMcpToolDefinition` 注册，它的
+ * `call` 必须返回该信封（裸值会被判为 invalid MCP result 或渲染成空内容）。
+ * 失败信封（`isError`）在此转成异常上抛，绝不触发 CLI 兜底重放
  * （写操作重放会造成重复记账）。
  * @module @dsh-plus/actual/mcp-session
  */
@@ -13,7 +15,6 @@ import {
   type CapabilityEntry,
   createActualMcpServer,
   type EntryInvoker,
-  parseJsonOrText,
 } from '@dsh-plus/actual-mcp'
 import { Client, InMemoryTransport } from '@modelcontextprotocol/client'
 
@@ -24,6 +25,7 @@ export interface McpSessionLike {
   connect(timeoutMs: number): Promise<void>
   /** `tools/list` → 能力条目（`source` 由调用方补齐）。 */
   listTools(): Promise<Pick<CapabilityEntry, 'name' | 'description' | 'inputSchema'>[]>
+  /** 执行一次工具：成功返回 canonical MCP 结果信封，失败（`isError`）抛错。 */
   callTool(
     name: string,
     args: Record<string, unknown>,
@@ -119,9 +121,9 @@ class InProcessSession implements McpSessionLike {
       }
     }
     const result = await client.callTool({ name, arguments: args }, requestOptions)
-    const text = textOf(result)
-    if ((result as { isError?: unknown }).isError === true) throw new Error(text)
-    return parseJsonOrText(text)
+    // 成功即原样交回信封；仅失败信封升级为异常（调用方据此报错，且不触发兜底重放）。
+    if ((result as { isError?: unknown }).isError === true) throw new Error(textOf(result))
+    return result
   }
 
   async close(): Promise<void> {

package/src/prompt.ts

@@ -18,7 +18,7 @@
 export const DEFAULT_PERSONA_PREFIX = `You are an Actual Budget operations agent powered by the {{model}} model. Your working directory is {{cwd}}. You operate a self-hosted Actual Budget server through the Actual tools auto-derived from the installed CLI version, plus the session's auxiliary ask/todo/web tools — there is no shell, generic file editing, or subagent capability here, and none is needed.
 
 ## Domain concepts
-- Budget: identified by a sync ID. The server is a CRDT sync relay that stores the budget file; all budget logic runs client-side. This session is bound to ONE budget — never switch to or download another one on your own.
+- Budget: identified by a sync ID. The server is a CRDT sync relay that stores the budget file; all budget logic runs client-side. This session is bound to ONE budget — never switch to or download another one on your own. If a command reports a missing budget, the configured sync ID is wrong: it must be the groupId listed by budgets list, not that same entry's cloudFileId. Say so and stop instead of switching budgets.
 - Amounts are ALWAYS integer cents in tool arguments and in raw JSON output: 5000 = 50.00, -12350 = -123.50. Table/CSV output decimalizes, JSON never does. Convert when talking to a human, and never pass a decimal amount.
 - Accounts are on-budget by default or off-budget (tracking only); closed accounts are hidden from lists unless requested. A balance is the signed sum of that account's transactions.
 - Categories belong to category groups; both can be hidden. category.name is null for uncategorized transactions.

package/src/refs.ts

@@ -0,0 +1,23 @@
+/**
+ * 凭据引用名字面量（纯常量，零依赖）。
+ *
+ * 宿主半（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
+ */
+
+/** 服务器口令。 */
+export const REF_PASSWORD = 'ACTUAL_PASSWORD'
+/** 会话令牌（官方 CLI 优先于口令）。 */
+export const REF_SESSION_TOKEN = 'ACTUAL_SESSION_TOKEN'
+/** 端到端加密口令（仅加密预算需要）。 */
+export const REF_ENCRYPTION_PASSWORD = 'ACTUAL_ENCRYPTION_PASSWORD'
+
+/** 卡片展示与批量 describe 使用的引用清单（顺序即展示顺序）。 */
+export const CREDENTIAL_REFS = [REF_PASSWORD, REF_SESSION_TOKEN, REF_ENCRYPTION_PASSWORD] as const

package/src/runtime.ts

@@ -13,6 +13,7 @@ import {
   type CapabilityEntry,
   type CliConfig,
   type CliDeps,
+  callToolResultOf,
   computeDrift,
   createEntryInvoker,
   discover,
@@ -137,6 +138,11 @@ export class ActualRuntime {
   /**
    * 执行一次能力调用：**MCP 优先，CLI 兜底**。
    *
+   * 返回值形状由 `entry.source` 决定（它同时决定子插件用哪个注册器）：
+   * `'mcp'` → canonical MCP 结果信封（官方 `createMcpToolDefinition` 要求）；
+   * `'cli'` → CLI 原始值（裸 ToolDefinition 自行渲染）。兜底路径也必须守这条
+   * 契约——否则会话掉线后同一个工具会因形状不同而失败。
+   *
    * 兜底只在 MCP 会话本身不可用时触发——工具失败已由服务端表示为错误结果并
    * 转成异常，绝不重放（写操作重放会造成重复记账）。
    */
@@ -150,7 +156,8 @@ export class ActualRuntime {
     }
     if (entry.cli !== undefined && this.cliInvoker !== undefined) {
       this.logger.warn(`Actual MCP 会话不可用，降级为 CLI 直连执行：${entry.name}`)
-      return await this.cliInvoker(entry, args, options)
+      const value = await this.cliInvoker(entry, args, options)
+      return entry.source === 'mcp' ? callToolResultOf(value) : value
     }
     throw new Error(
       `Actual MCP 不可达且该能力无 CLI 回退：${entry.name}（${this.lastError ?? '未连接'}）`,

package/src/service.ts

@@ -8,7 +8,10 @@
  * 后立即按新配置重新发现。纯展示/策略字段（name/description/order/persona 等）
  * 不触发重建，它们在下一次预设注册或工具注册时自然生效。
  *
- * 密钥只经子进程环境变量下发；日志与状态均经脱敏。数据目录默认落在插件数据
+ * 密钥解析每次操作即时进行：行级 Config 声明的优先，否则问官方 credentials
+ * seam（`$DSH_HOME/.credentials.yaml`，浏览器半经官方 `remote.credentials`
+ * 命名空间写入）——改口令后下一次工具调用即生效，无需 /reload 或重启。
+ * 日志与状态均经脱敏。数据目录默认落在插件数据
  * 目录（与用户自有 CLI 的 `~/.actual-cli/data` 隔离，避免缓存与迁移互相踩）。
  * @module @dsh-plus/actual/service
  */
@@ -19,11 +22,13 @@ import {
   type ActualStatus,
   type CapabilityEntry,
   type CliConfig,
+  configSecretsOf,
   createNodeDeps,
 } from '@dsh-plus/actual-mcp'
 import { pluginDataPath, unwrapVolatile } from '@dsh-plus/shared'
 
 import type { ActualConfig, ActualConfigFields } from './config.ts'
+import { type CredentialsFace, resolveSecrets } from './credentials.ts'
 import { createInProcessSession } from './mcp-session.ts'
 import {
   ActualRuntime,
@@ -102,7 +107,12 @@ export class ActualService extends Service {
       cliVersionPolicy: config.cliVersionPolicy,
       toolCallTimeoutMs: config.toolCallTimeoutMs,
     }
-    const runtime = new ActualRuntime(runtimeConfig, this.deps, this.logger)
+    // 密钥按调用即时解析：`cli` 随签名变化换代，闭包始终指向当前那一代配置。
+    const deps: RuntimeDeps = {
+      ...this.deps,
+      resolveSecrets: () => resolveSecrets(this.credentialsSeam(), configSecretsOf(cli)),
+    }
+    const runtime = new ActualRuntime(runtimeConfig, deps, this.logger)
     const detach = runtime.onChange((manifest) => {
       for (const listener of [...this.listeners]) listener(manifest)
     })
@@ -158,6 +168,18 @@ export class ActualService extends Service {
     return () => this.listeners.delete(cb)
   }
 
+  /**
+   * credentials seam：**可选探测**而非硬 inject。
+   *
+   * 本插件在没挂 `dsh-credentials` 的 profile（headless/dev 精简组合）里也要能
+   * 起来，只是密钥退回「行级 Config + CLI 自身继承环境」；且探测发生在每次操作，
+   * seam 比本插件晚激活也能自然接上，不必声明时序。
+   */
+  private credentialsSeam(): CredentialsFace | null {
+    const found = (this.ctx as unknown as { get(key: string): unknown }).get('credentials')
+    return found === undefined || found === null ? null : (found as CredentialsFace)
+  }
+
   dispose(): void {
     this.listeners.clear()
     this.detach()