@dsh-plus/actual 0.1.0 → 0.1.1

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/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/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()