@senguoyun/dsh-arkme 0.1.34 → 0.1.36

package/README.md

@@ -57,7 +57,7 @@ SHA256SUMS
 pnpm pack:runtime -- --output-dir /path/to/output
 ```
 
-脚本会运行插件现有构建流程，并校验包名、版本、Release Set 必需入口、归档路径和文件类型；校验失败时不会留下不完整制品。
+脚本会运行插件现有构建流程，并校验包名、版本、Release Set 必需入口、归档路径和文件类型；tar 条目顺序、mtime、owner/group 与权限均固定，在同一 Node.js/zstd 构建工具链下，同一源码重复构建会生成相同摘要。校验失败时不会留下不完整制品。
 
 ## 架构
 

package/assets/windows/manifest.json

@@ -3,7 +3,23 @@
   "platform": "win32",
   "arch": "x64",
   "file": "arkme-credential-helper.exe",
-  "sha256": "8b598f3f4facb0c785c3fbc29ccddb75a08e90528ba02a55fc6c996442ec4a16",
+  "sha256": "fbfb99a440b2f1fcb83e49f29bb752ae214c4c2fe14890609835b53a8438db58",
   "sourceSha256": "7e2267aa232d4fbe785d2ab88bd707ab6edacd88bd454fda7f8017ddfc0335b6",
-  "goVersion": "go version go1.25.5 darwin/arm64"
+  "goVersion": "go version go1.25.5 darwin/arm64",
+  "helperVersion": "1.0.0.0",
+  "pe": {
+    "CompanyName": "Senqisi (Wuhan) Technology Co., Ltd.",
+    "ProductName": "Arkme Credential Helper",
+    "FileDescription": "Arkme Windows Credential Manager Helper",
+    "InternalName": "arkme-credential-helper",
+    "OriginalFilename": "arkme-credential-helper.exe",
+    "FileVersion": "1.0.0.0",
+    "ProductVersion": "1.0.0.0"
+  },
+  "authenticode": {
+    "digestAlgorithm": "sha256",
+    "signerSubject": "CN=\"Senqisi (Wuhan) Technology Co., Ltd.\", O=\"Senqisi (Wuhan) Technology Co., Ltd.\", L=Wuhan, S=Hubei, C=CN",
+    "signerSha1": "00ADCF59ACCC45F4643B4A682E32620C206CE66B",
+    "timestampRequired": true
+  }
 }

package/cordis.patch.yml

@@ -26,6 +26,7 @@
         relatedRecordingsEnabled: true
         geetestCaptchaId: ec81315ab8b0f18a7bfa13602d01e307
         interwovenMomentsEnabled: true
+        recordingWorkbenchEnabled: true
         chatMemberJoinEventsEnabled: true
         allowNonLoopback: false
         allowProduction: true

package/docs/consumer-plugin-contract.md

@@ -141,6 +141,45 @@ Chat items returned by `readSource()` may include an opaque sender `avatarRef`.
 
 Timeline items may include `contentBlocks` for image, video, audio, and file content. Long articles use the owner contract's `templateKind: 8`; `displayKind: 1` remains accepted only as a compatibility signal for previously sent plugin records. Each block's `mediaRef` is account-bound and short-lived. Render it with `sdk.mediaUrl(mediaRef)`; never decode or persist it. `upload()` sends a browser file only to the same-origin plugin route and returns an Arkme asset descriptor for `sendRich()`.
 
+### Text background sound and location capture
+
+Background sound is an explicit role, never an audio-MIME heuristic. An ordinary `audio/*` asset passed in `sendRich().assets` remains an ordinary attachment. A direct rich send passes background assets separately:
+
+```ts
+const background = await arkme.upload(backgroundBlob, { fileName: 'background.m4a' })
+await arkme.sendRich(sourceRef, {
+  textContent: '这是一条带背景音的文字快记',
+  backgroundSound: { assets: [background], amplitudes: [0.1, 0.6, 0.3] },
+})
+```
+
+The direct `upload()` route reports audio as service `fileKind: 2`, while a locally staged generic file currently reports `fileKind: 4`; both are accepted as background audio only when they appear in the separate `backgroundSound` descriptor. Putting either asset in ordinary `assets` keeps `content_file_role=1`.
+
+For durable sends, stage every file first and pass every background ref in both `fileRefs` and `backgroundSound.fileRefs`. `sendFiles()` persists that descriptor with the task, uploads each local file at most once, and reuses the same uploaded asset and descriptor after a retry. A descriptor is rejected when refs are duplicated or not a subset, samples are non-finite or outside `0..1`, or a selected file is not an ordinary `audio/*` file (`fileKind: 4`).
+
+The Browser UI may also persist a send-scoped `location` on a durable task after the user has explicitly enabled location recording. The task owner applies it only after the final record UID is confirmed, including reconciliation. External SDK consumers must obtain the same explicit user authorization before supplying precise coordinates. Model-facing file Tools neither accept nor return this field.
+
+Gate background-sound sends on `capabilities().features.backgroundSound` so the same Consumer degrades cleanly on older Providers. The built-in message-detail owner remains authoritative for snapshot retrieval and display; this contract only extends that existing detail with optional background playback and the already-authorized location facts.
+
+Successful `sendText()`, `sendRich()` and durable `sendFiles()` confirmations may return the same Host-signed `messageActionRef` immediately, before an authoritative timeline refresh. Consumers may use it to enable message actions without waiting for projection convergence, but must treat omission as a compatibility/degraded state and wait for `readSource()`; they must never synthesize or weaken validation of the reference.
+
+The switch itself is an account-scoped server owner, not a browser-local preference. `backgroundSoundPreference()` reads `/api/v1/settings/background-voice/query` and the independent record-service membership owner; `updateBackgroundSoundPreference(enabled, signal?, expectedUserId?)` writes only `{ enabled }` to `/api/v1/settings/background-voice/update`. The built-in Host UI, SDK Consumer and confirmed Tool pass the `userId` captured from that verified read as `expectedUserId`; the owner rejects an account switch before the remote write. The Host verifies the returned `user_id` against the active session and returns `{ userId, found, enabled, eligible, memberType?, eligibilityReason, sourceVersion?, updatedAtMillis? }`. Free membership forces `enabled=false`; unknown membership also fails closed but remains distinguishable as `eligibilityReason=membership-unavailable`. Enabling is rejected before the settings write unless the membership owner confirms eligibility; disabling always remains available. A UI may update its local projection optimistically, but it must restore the previous value when the owner write fails. `found=false` means use the local default (`false`) without manufacturing a server fact.
+
+Calling `updateBackgroundSoundPreference(true)` is allowed only from a current explicit human UI/SDK action and still does not grant microphone permission; the interactive composer owns that separate browser permission request. Model Tools can read the preference or, after explicit write confirmation, disable it. They intentionally have no enable parameter, because a model must not turn on a recording-affecting preference or trigger a microphone flow.
+
+Do not derive subscription eligibility from `profile().accountType`; that field is an account classification, not the Flutter membership owner. `BackgroundSoundMembershipService` reads the authoritative `/api/v1/premium/get/member` `member_type` fact: `0` is free and ineligible, while positive member types are eligible. A failed or malformed membership read is `membership-unavailable`, not proof that the account is free.
+
+Capability matrix:
+
+| Surface | Entry | Contract and safety boundary |
+| --- | --- | --- |
+| Built-in UI | Settings switch, composer capture and message snapshot dialog | The switch is a reversible local projection of the account owner. One input-capture owner submits the explicit background descriptor; the snapshot dialog reads the same Host detail owner. |
+| Browser SDK | `backgroundSoundPreference()`, `updateBackgroundSoundPreference()`, `sendRich()`, `sendFiles()` | Typed same-origin calls; no credentials, storage paths, implicit microphone grant, raw record id, or inferred background role. Enabling requires a current explicit human action. |
+| DSH Tool | `arkme_background_sound_status`, `arkme_background_sound_disable`, `arkme_files_send` | Disable/file send remain `explicit-user-write`; no Tool can enable or open the microphone. File send reuses only staged opaque refs and never exposes precise location. |
+| Host owner | `BackgroundSoundMembershipService`, `BackgroundSoundPreferenceService`, `ChatService.sendSourceRich()` and the existing snapshot detail owner | The settings owner validates current-account identity. One payload builder merges ordinary assets, mentions and background items. Background refs use `file_type=5`, `content_file_role=4`, `binding_type=4`, `render_role=1`; only-background text keeps the plain-text template. Existing account, source, permission and idempotency checks remain authoritative. |
+
+Snapshot `backgroundSound=available` requires an identified media row (`file_asset_uid`, `uid`, `media_id`, or compatible file ID) carrying role `content_file_role=4`, `binding_type=4`, or legacy `file_type/type=5`. Waveform amplitudes without such a file remain `not-recorded`; an ordinary audio MIME never supplies the role.
+
 `capabilities().features.forwardContent === true` advertises expanded `readSource()` forward snapshots. `forwardRecords.items` may contain `sourceType`, `segments` (speaker, full text, relative start/end milliseconds), `contentBlocks` and `mediaUnavailable`. Segment audio also uses `contentBlocks`, never raw URLs. The same snapshot is returned to the built-in UI and `arkme_source_read`. Missing optional fields on older Providers mean text-only rendering, not an error. Unknown source types remain `unknown`; filenames must not determine recording type. No original chat name or source access is implied. A transcript with no attachment is not playable. `truncated` marks bounded output (100 flattened records, nesting depth four; up to 500 segments per record / 2000 total; 32 attachments per record). Display it as partial, never silently claim a complete archive.
 
 Consumers retain no additional resources for a one-shot `readSource()`. If they call `subscribe()`, invoke its returned unsubscribe function on disposal. Refresh the received timeline when a media reference expires; do not query the private original recording or cache/decode its reference. Unsupported `contractVersion` is rejected by `capabilities()`; an absent optional `forwardContent` feature falls back to the existing text snapshot.

package/docs/plugin-release.md

@@ -4,7 +4,9 @@
 
 该工作流会自动创建 `release/v<版本号>` 发版 PR，并在其中更新版本号、插件内更新说明和 GitHub Release 链接，随后执行完整测试、类型检查和构建。
 
-合并该发版 PR 后，发布工作流会再次验证代码，发布 npm 包、创建 `v<版本号>` Git Tag，并生成 GitHub Release。
+合并该发版 PR 后，发布工作流会再次验证代码，发布 npm 包、创建 `v<版本号>` Git Tag，并生成 GitHub Release。随后由独立的 production workflow 校验 npm、Tag、GitHub Release 与发布 SHA，检出该精确 SHA，构建 `tar.zst`，通过 Backend 获取单对象 STS 上传 OSS，并在 Runtime 校验通过后自动激活。
+
+`pre-release` 分支的每次 push 会走同一套 Runtime 发布链路，但不会发布 npm。测试版本由稳定基准版本的下一补丁与 GitHub run number 组成，例如 `0.1.34` 在 run `128` 中生成 `0.1.35-pre.128`；版本修改只存在于 Action 临时工作区。
 
 ## 一次性配置
 
@@ -16,6 +18,17 @@
 
 Trusted Publisher 配置完成后，GitHub Actions 通过短期身份凭据发布 npm，不需要把 npm Token 保存到 GitHub Secrets。
 
+另外需要分别在 `production` 和 `pre-release` GitHub Environment 中配置：
+
+- `ARKME_BACKEND_BASE_URL`：对应环境 Backend 的 HTTPS origin。
+- `ARKME_CI_TRIGGER_SECRET`：对应环境 Backend 的 CI Bearer Secret。
+
+OSS bucket、直传 endpoint、CDN origin 与对象前缀只配置在对应 Backend 中，不进入 GitHub Secrets。测试环境使用 `/app/arkme/test/plugin/`，生产环境使用 `/app/arkme/prod/plugin/`；Backend 会去掉首尾斜杠后生成 OSS Object Key。production 与 pre-release Runtime workflow 都使用全局串行 concurrency，且不会取消正在运行的发布。
+
+`pre-release` 分支必须通过 GitHub Ruleset 禁止直接 push，要求 PR 和 CODEOWNERS 审批；`pre-release` Environment 也必须限制为该受保护分支。工作流会在无 Secret 的 job 中构建触发提交，再由持密 job 从受保护的 `master` 检出发布工具和锁定依赖，下载并重新校验制品后发布。
+
+对应 OSS bucket 必须为各环境规范化后的 `object-prefix` 启用 Bucket 级覆盖保护规则：测试环境为 `app/arkme/test/plugin/`，生产环境为 `app/arkme/prod/plugin/`。GitHub Actions 上传时也会发送 `x-oss-forbid-overwrite: true`，但 Bucket 级规则才是对临时 STS 凭据的服务端强制约束；未完成该配置前不得启用 `arkme-plugin-ci`。
+
 ## 版本选择
 
 - `patch`：修复和小优化，如 `0.1.19 → 0.1.20`。