dsh-primer 0.4.3 → 0.4.5

package/references/official-docs/docs/subsystems/credentials.zh.md

@@ -32,13 +32,12 @@ interface ResolvedCredential {
 
 ## 描述
 
-`describe(ref)` 在绝不暴露值的前提下回应配置界面：引用当前是否可解析、来自哪一层、`set` 当前能否成功。本地提供方将其管理的文件排在启动环境之前，因此保存值总会成为生效且可写的那一层；移除后会重新使用启动环境或 `.env` 后备值。
+`describe(ref)` 在绝不暴露值的前提下回应配置界面：引用当前是否可解析、来自哪一层、`set` 当前能否成功。可选的 `masked` 字段携带提供方生成的脱敏预览，不包含完整凭据。本地提供方将其管理的文件排在启动环境之前，因此保存值总会成为生效且可写的那一层；移除后会重新使用启动环境或 `.env` 后备值。
 
 ```ts type-equiv
 /**
- * Source and writability facts for one reference, safe for configuration UIs —
- * never the value. The view has no slot a value could ride in, which is what
- * lets the whole read half cross the Remote wire.
+ * Configuration facts and an optional provider-masked preview for one
+ * reference. The full credential is never part of this view.
  */
 interface CredentialInfo {
   /** Whether resolving the reference would currently return a value. */
@@ -47,6 +46,8 @@ interface CredentialInfo {
   source?: string
   /** Whether the active provider can write this reference. */
   writable: boolean
+  /** Provider-generated masked preview of a stored value; never the full value. */
+  masked?: string
 }
 ```
 
@@ -56,7 +57,7 @@ interface CredentialInfo {
 
 ## 内嵌 Platform 凭证
 
-PlatformSession 是 getPlatformSession 返回的仅限 Host 快照：origin 指定所配置的 Platform 签发来源，token 包含其已存账号凭证。userId 复制最近一次成功 getProfile 得到的稳定账号 ID；尚无一次成功读取或资料不含 ID 时为 null。快照复用该 ID，不自行发起资料请求，因此 ID 未知时只会让 userId 为 null，而不会延迟调用方；资料读取首次取得稳定 ID 或该 ID 变化时仅通知使用 `watch(signal, true)` 的 Host 订阅者，供标识使用方重新读取快照。使用方以 origin 和 userId 作为持久化浏览器存储的键，为 null 时退回临时存储。账号已退登或读取凭证期间凭证变化时不返回快照；签发来源不匹配时失败。原生使用方负责在凭证变化时使文档失效。账号控制器 RPC、AccountView 和 AccountDetails 均不包含此快照。
+PlatformSession 是 getPlatformSession 返回的仅限 Host 快照：origin 指定所配置的 Platform 签发来源，token 包含其已存账号凭证。userId 复制最近一次成功 getProfile 得到的稳定账号 ID；尚无一次成功读取或资料不含 ID 时为 null。快照复用该 ID，不自行发起资料请求，因此 ID 未知时只会让 userId 为 null，而不会延迟调用方；资料读取首次取得稳定 ID 或该 ID 变化时仅通知使用 `watch(signal, true)` 的 Host 订阅者，供标识使用方重新读取快照。使用方以 origin 和 userId 作为持久化浏览器存储的键，为 null 时退回临时存储。账号已退登或读取凭证期间凭证变化时不返回快照；签发来源不匹配时失败。原生使用方负责在凭证变化时使文档失效。账号 Remote API、AccountView 和 AccountDetails 均不包含此快照。
 
 AccountDetails.balance 将充值钱包投影为 value、赠送钱包投影为 bonusWallets，分别保留币种和十进制余额字符串。查询失败不包含钱包数组。
 
@@ -154,9 +155,9 @@ abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>
 
 /**
  * Describe one reference for configuration surfaces without exposing the
- * value.
+ * full value.
  * @param ref - the reference to describe.
- * @returns configured state, supplying source, and writability.
+ * @returns configured state, supplying source, writability, and optional masked preview.
  */
 abstract describe(ref: CredentialRef): Promise<CredentialInfo>
 
@@ -228,7 +229,7 @@ Source: [`packages/credentials/credentials/src/index.ts`](../../packages/credent
 
 ### `ctx.credentialsController` — `CredentialsController`
 
-Host service backing the generated `ctx.remote.credentials` namespace. It carries every wire obligation the credential seam itself does not: the batch fan-out bound, the field-by-field view projection, the reference-grammar guard, and the refusal mapping. Secret values cross in one direction only — no method here returns one.
+Host service backing the generated `ctx.remote.credentials` namespace. It carries every wire obligation the credential seam itself does not: the batch fan-out bound, the field-by-field view projection, the reference-grammar guard, and the refusal mapping. Full secret values cross in one direction only — no method here returns one.
 
 ```ts cordis-catalog
 /**
@@ -261,18 +262,18 @@ Host service backing the generated `ctx.remote.credentials` namespace. It carrie
 
 Source: [`packages/api/settings-controller/src/credentials.ts`](../../packages/api/settings-controller/src/credentials.ts)
 
-<a id="ctxdeepseekaccount--deepseekaccount-abstract-seam"></a>
+<a id="ctxdeepseekaccount--deepseekaccount"></a>
 
-### `ctx.deepseekAccount` — `DeepSeekAccount` (abstract seam)
+### `ctx.deepseekAccount` — `DeepSeekAccount`
 
-Account operations; only Host consumers can obtain a request credential.
+Account login, credentials, and client-safe Remote operations.
 
 ```ts cordis-catalog
 /**
  * Read stored-account presence and the latest login attempt.
  * @returns a snapshot without credentials or PKCE secrets.
  */
-abstract getState(): Promise<AccountView>
+@Remote async getState(): Promise<AccountView>
 
 /**
  * Query Platform profile independently of wallet balances.
@@ -281,30 +282,65 @@ abstract getState(): Promise<AccountView>
  * @param client - identity of the requesting UI for this call.
  * @returns profile outcome, or null if signed out or the grant changed during the query.
  */
-abstract getProfile(client: AccountClientMetadata): Promise<AccountDetails['profile'] | null>
+@Remote async getProfile(client: AccountClientMetadata): Promise<AccountDetails['profile'] | null>
 
 /**
  * Query Platform recharge and bonus wallet balances independently of profile data.
  * @param client - identity of the requesting UI for this call.
  * @returns balance outcome, or null if signed out or the grant changed during the query.
  */
-abstract getBalance(client: AccountClientMetadata): Promise<AccountDetails['balance'] | null>
+@Remote getBalance(client: AccountClientMetadata): Promise<AccountDetails['balance'] | null>
 
 /**
- * Query the granted bonuses Platform has not yet recorded as displayed.
+ * Query unconsumed account notifications in server order without reading profile data.
  * @param client - identity of the requesting UI for this call; its language selects the server-authored message.
- * @returns bonuses with their account, or null if signed out or the grant changed during the query.
+ * @returns notifications with their next query delay, or null if signed out or the grant changed during the query.
  */
-abstract getUnnotifiedBonuses(client: AccountClientMetadata): Promise<AccountBonusBatch | null>
+@Remote async getNotifications(client: AccountClientMetadata): Promise<AccountNotificationBatch | null>
 
 /**
- * Record one displayed bonus as notified for the account it belongs to.
- * @param accountId - account the notification was read for; a different current account is never acknowledged.
- * @param orderId - granted bonus order the user saw.
+ * Query localized content of a notification, including one already consumed.
+ * @param id - notification whose content is requested.
+ * @param client - identity of the requesting UI; its language selects the localized content.
+ * @returns content without changing consumption, or null if signed out or the grant changed.
+ */
+@Remote async getNotificationContent(id: AccountNotificationId, client: AccountClientMetadata): Promise<AccountNotification | null>
+
+/**
+ * Report a notification interaction; the backend decides consumption.
+ * @param id - notification the user interacted with.
+ * @param event - displayed frame, non-dismiss action click, or explicit dismissal.
  * @param client - identity of the requesting UI for this call.
- * @returns true once Platform records the acknowledgement; false if signed out or the account changed.
+ * @returns true once the server accepts the event; false if signed out or credentials changed during the call.
+ */
+@Remote async reportNotificationEvent(id: AccountNotificationId, event: AccountNotificationEvent, client: AccountClientMetadata): Promise<boolean>
+
+/**
+ * Remove an inference-rejected token only while it still matches the stored login.
+ * @param token - token captured by the rejected inference request.
+ * @returns after matching credentials are removed and the expiry notification is emitted.
+ */
+async rejectToken(token: string): Promise<void>
+
+/**
+ * Read existing login identity without creating a device or returning credentials.
+ * @returns optional device/account identifiers and the provider's OS version string.
+ */
+async getDeviceIdentity(): Promise<{ deviceId?: string; userId?: AccountUserId; osVersion: string }>
+
+/**
+ * Read credentials for the configured embedded-page origin, bound to their account environment, and
+ * pair them with the account ID from the last successful profile read; no profile request is made.
+ * @returns a Host-only snapshot, or null while signed out or when the credential changed during the read.
+ */
+async getPlatformSession(): Promise<PlatformSession | null>
+
+/**
+ * Resolve a credential only for the inference origin allowed by the provider.
+ * @param url - actual request destination or API base URL.
+ * @returns stored token, or undefined for other origins or a signed-out account.
  */
-abstract ackBonusNotified(accountId: AccountUserId, orderId: AccountBonusOrderId, client: AccountClientMetadata): Promise<boolean>
+async resolveToken(url: string): Promise<string | undefined>
 
 /**
  * Join an active attempt or start browser authorization.
@@ -313,56 +349,49 @@ abstract ackBonusNotified(accountId: AccountUserId, orderId: AccountBonusOrderId
  * @param loginSource - initiating UI, used to return from a failed exchange.
  * @returns the initial snapshot without waiting for browser approval.
  */
-abstract startSignIn(client: AccountClientMetadata, callbackOrigin: string, loginSource: 'web' | 'desktop'): Promise<AccountView>
+@Remote async startSignIn(client: AccountClientMetadata, callbackOrigin: string, loginSource: 'web' | 'desktop'): Promise<AccountView>
 
 /**
  * Cancel only the named attempt; committing attempts settle before returning.
- * @param id - attempt identity from this Host.
+ * @param attemptId - attempt identity from this Host.
  * @returns state after cancellation or an already-started commit.
  */
-abstract cancelSignIn(id: SignInAttemptId): Promise<AccountView>
+@Remote async cancelSignIn(attemptId: SignInAttemptId): Promise<AccountView>
 
 /**
  * Remove the local grant while retaining API keys; the provider revokes it in the background.
  * @param client - identity of the requesting UI, captured for the background revocation retries.
  * @returns the signed-out state after local removal; remote failures never restore the grant.
  */
-abstract signOut(client: AccountClientMetadata): Promise<AccountView>
+@Remote signOut(client: AccountClientMetadata): Promise<AccountView>
 
 /**
- * Subscribe to snapshots including a complete initial state.
- * @param signal - subscription lifetime; ending it never cancels login.
- * @param includeIdentityChanges - also notify when cached Platform identity changes; defaults to false.
- * @returns complete snapshots as account state changes.
+ * Inspect running work before sign-out.
+ * @returns whether a running task's latest request uses the account route; false when the optional agents service is absent.
  */
-abstract watch(signal: AbortSignal, includeIdentityChanges?: boolean): AsyncIterable<AccountView>
+@Remote hasRunningAccountTasks(): boolean
 
 /**
- * Resolve a credential only for the inference origin allowed by the provider.
- * @param url - actual request destination or API base URL.
- * @returns stored token, or undefined for other origins or a signed-out account.
+ * Subscribe to live credential expiry without replay.
+ * @param signal - subscription lifetime; provider disposal also ends it.
+ * @returns expiry notifications emitted during the subscription.
  */
-abstract resolveToken(url: string): Promise<string | undefined>
+@Remote({ mode: 'stream' }) async *watchExpiry(signal: AbortSignal): AsyncIterable<'session-expired'>
 
 /**
- * Remove an inference-rejected token only while it still matches the stored login.
- * @param token - token captured by the rejected inference request.
- * @returns after matching credentials are removed and the expiry notification is emitted.
- */
-abstract rejectToken(token: string): Promise<void>
-
-/**
- * Read credentials for the configured Platform origin, bound to their issuing environment, and
- * pair them with the account ID from the last successful profile read; no profile request is made.
- * @returns a Host-only snapshot, or null while signed out or when the credential changed during the read.
+ * Subscribe to ordered updates including a complete initial snapshot.
+ * @param signal - subscription lifetime; ending it never cancels login.
+ * @param includeIdentityChanges - also notify when cached Platform identity changes; defaults to false.
+ * @returns complete state with snapshot or credentials-changed event type; credential changes take priority when updates coalesce.
  */
-abstract getPlatformSession(): Promise<PlatformSession | null>
+watch(signal: AbortSignal, includeIdentityChanges: boolean = false): AsyncIterable<AccountUpdate>
 
 /**
- * Read existing login identity without creating a device or returning credentials.
- * @returns optional device/account identifiers and the provider's OS version string.
+ * Stream account state without the Host-only identity subscription option.
+ * @param signal - subscription lifetime.
+ * @returns initial state, login progress, and credential-change updates.
  */
-abstract getDeviceIdentity(): Promise<{ deviceId?: string; userId?: AccountUserId; osVersion: string }>
+@Remote({ name: 'watch', mode: 'stream' }) watchState(signal: AbortSignal): AsyncIterable<AccountUpdate>
 ```
 
 Source: [`packages/credentials/deepseek-account/src/index.ts`](../../packages/credentials/deepseek-account/src/index.ts)
@@ -488,6 +517,6 @@ Local grant removal has completed.
 Source: [`packages/credentials/deepseek-account/src/index.ts`](../../packages/credentials/deepseek-account/src/index.ts)
 <!-- END GENERATED cordis-surface -->
 
-账号服务定义提供 getState、getProfile、getBalance、getUnnotifiedBonuses、ackBonusNotified、startSignIn、cancelSignIn、signOut、watch 及仅限 Host 的 resolveToken 和 getPlatformSession。平台提供者使用 AuthorizationFlow 和私有 GrantRecord 实现这些操作。AccountView 区分本地存在与服务器验证；尝试 ID 将取消绑定到单次本地流程。参见[账号包](../../packages/credentials/deepseek-account/README.zh.md)。
+账号服务定义提供 getState、getProfile、getBalance、getNotifications、getNotificationContent、reportNotificationEvent、startSignIn、cancelSignIn、signOut、watch 及仅限 Host 的 resolveToken 和 getPlatformSession。平台提供者使用 AuthorizationFlow 和私有 GrantRecord 实现这些操作。AccountView 区分本地存在与服务器验证；尝试 ID 将取消绑定到单次本地流程。AccountUpdate 的 state 携带完整 AccountView，type 为 snapshot 时表示首次或进度更新，为 credentials-changed 时表示凭据写入或删除。待发送的凭据变化优先于进度更新。参见[账号包](../../packages/credentials/deepseek-account/README.zh.md)。
 
 `AccountClientMetadata` 携带调用方 `DSH_CLIENT_VERSION` 提供的 `version`、当前界面 `locale`，以及操作发起时采样的 `timezoneOffsetSeconds`。偏移为本地时间减 UTC 的秒数：UTC+8 对应 `28800`。其中不含凭证。登录申请在兑换及取消期间保留发起时的元数据；退出操作为撤销重试保留其元数据。

package/references/official-docs/docs/subsystems/deliverables.i18n.yaml

@@ -3,8 +3,8 @@
 # After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/deliverables.md
 /deliverables:
-  en: a5ce6d07597594ec
-  zh: 72639c6033d66f41
+  en: b7a2665f103d3e99
+  zh: ee642ed0d3385f67
 /deliverables/presentedfile-one-declared-delivery:
   en: bf10a8aa233c61d9
   zh: fdab894f8448c843

package/references/official-docs/docs/subsystems/deliverables.md

@@ -6,6 +6,8 @@ What a turn hands to the user, owned by the [deliverables package group](../../p
 
 Sources: [`packages/deliverables/tool-present/src/types.ts`](../../packages/deliverables/tool-present/src/types.ts), [`packages/deliverables/workspace-changes/src/types.ts`](../../packages/deliverables/workspace-changes/src/types.ts)
 
+Patch calls use the same summary and comparison APIs. For paths outside Git coverage, a move contributes a deleted source and an added destination; a stopped commit contributes only actual net file changes. The [capture rules](../../packages/deliverables/workspace-changes/README.md#use-this-package) define path selection and observation behavior.
+
 ## `PresentedFile` — one declared delivery
 
 ```ts type-equiv

package/references/official-docs/docs/subsystems/deliverables.zh.md

@@ -6,6 +6,8 @@
 
 源码：[`packages/deliverables/tool-present/src/types.ts`](../../packages/deliverables/tool-present/src/types.ts)、[`packages/deliverables/workspace-changes/src/types.ts`](../../packages/deliverables/workspace-changes/src/types.ts)
 
+补丁调用使用相同的摘要与对比 API。对于 Git 覆盖之外的路径，移动形成源删除与目标新增；停止的提交只贡献实际文件净变化。[采集规则](../../packages/deliverables/workspace-changes/README.zh.md#use-this-package)定义路径选择与观察行为。
+
 ## `PresentedFile`：一条声明的交付
 
 ```ts type-equiv

package/references/official-docs/docs/subsystems/filesystem.i18n.yaml

@@ -3,17 +3,20 @@
 # After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/filesystem.md
 /filesystem:
-  en: 9085200a1975c5cd
-  zh: 48af21e513f7dc25
+  en: 7f7941ec6f70a8b8
+  zh: 450937984b6a8748
 /filesystem/target-identity-and-metadata-provider-contract:
-  en: 345def8a8e6c58e0
-  zh: 01d6e2f0f22daf9d
+  en: 1e55f1c74f0ade3f
+  zh: faecf389a2fb0a93
+/filesystem/patch-syntax-records:
+  en: 3ab3a02918d41178
+  zh: 78ff80be8599ba43
 /filesystem/write-and-edit-guards-provider-contract:
-  en: 067137c8b8181c98
-  zh: 0a9c8282789d147f
+  en: a7c449176367a0d6
+  zh: ecb49a885304db62
 /filesystem/the-fs-policy-events-provider-contract-vocabulary:
-  en: 5dd0bdff9508350d
-  zh: 74d846f58fe561c9
+  en: b25951ca185a890e
+  zh: 42a1344a2cc860a9
 /filesystem/execution-context-policy-plugin:
   en: a23c12fc81bb4786
   zh: 9dc12d18f9c97e6a
@@ -21,14 +24,17 @@
   en: 9315d84e53db33e9
   zh: 86426ffbfa487504
 /filesystem/observed-file-state-policy-plugin:
-  en: 93e8d93a5049b67f
-  zh: b50db8c745baa5fe
+  en: cfa56ed5d1eb2ff9
+  zh: 04be764f3dc8a48c
+/filesystem/patch-execution-consumer:
+  en: 7b462db42ab89b10
+  zh: 968219ded2b55d69
 /filesystem/error-taxonomy-provider-contract:
-  en: 0785de8395fef24f
-  zh: 0fc173dff1fe4658
+  en: dbab88fbb60fcb8f
+  zh: f90be1352b1e05f8
 /filesystem/no-timeouts-on-file-io:
   en: ae18af906f3f7e50
   zh: 24a1aa6f903fe08d
 /filesystem/the-service-and-the-plugin:
-  en: 6dcd1f39906d785e
-  zh: e2b4b104bad31144
+  en: a5e2474038c20e73
+  zh: 0b8c7a9f504226b8