@senguoyun/dsh-arkme 0.1.29 → 0.1.31

package/docs/consumer-plugin-contract.md

@@ -93,7 +93,41 @@ Plugin update discovery and acknowledgement are lifecycle concerns owned by the
 
 `capabilities().features.callHistory === true` advertises Browser-safe call-history access. `callHistory()` returns recent call records with opaque account-scoped `callRef` values, display metadata, result labels, summary status and summary previews. `callDetail(callRef)` accepts only an unchanged `callRef` from the Provider and returns safe metadata, participants, summary and transcript text. `retryCallSummary(callRef)` is a write-like operation and must only run from a current explicit human request to retry or regenerate that call summary. Consumers must never expect or reconstruct raw room IDs, WebRTC credentials, recording URLs, video URLs, signed media URLs or upstream tokens from this contract.
 
-`profile()` exposes only UI-safe fields: display name, nickname, avatar reference, Arkme ID, optional one-time Arkme ID change availability, account type, creation time, binding flags, and masked phone/email. Raw phone, raw email, real name, and credentials are intentionally excluded from contract v1. The model-facing `arkme_id_set` tool owns the one-time write workflow; the Browser SDK does not expose a profile mutation method.
+`profile()` exposes only UI-safe fields: display name, nickname, avatar reference, Arkme ID, optional one-time Arkme ID change availability, account type, creation time, binding flags, optional third-party display names such as bound WeChat nickname, and masked phone/email. Raw phone, raw email, real name, OAuth code, and credentials are intentionally excluded from contract v1.
+
+`capabilities().features.accountSettings === true` advertises the current-account settings migration from the Flutter client. Built-in UI shows the Arkme ID, generates the personal QR code from the same World share URL rule used by Flutter (`<shareWebsite>/<arkmeId>`), and can run the phone bind/rebind SMS flow through `auth.phone.send` and `auth.phone.verify`. `checkArkmeIdAvailability()` and `setArkmeIdOnce()` expose the same one-time Arkme ID owner used by the model-facing `arkme_id_set` tool; callers must obtain explicit human confirmation before `setArkmeIdOnce()`. `sendPhoneCode()` requires a Geetest captcha result from a current human browser action, and `verifyPhoneCode()` refreshes auth/profile state after success. WeChat binding remains a Flutter-native AppBridge OAuth flow: Flutter opens WeChat, receives an OAuth code, then calls `/api/v1/auth/wechat-bind`. The plugin contract currently exposes only WeChat binding status and safe nickname; Consumer SDKs and model Tools must not fabricate a WeChat bind/rebind flow without a Host-provided OAuth bridge.
+
+Account settings capability matrix:
+
+| Capability | UI | SDK | Tool | Host owner |
+| --- | --- | --- | --- | --- |
+| Show Arkme ID and bindings | `ArkmeSettingsSurface` account info rows | `profile()` | `arkme_user_profile` | `ProfileService.refreshProfileForSession()` |
+| Personal QR and copy profile link | Built-in QR dialog | `profile()` + Consumer-generated URL from `shareWebsite` | N/A, display-only | Client config + safe profile projection |
+| Check/set Arkme ID once | Built-in ID dialog | `checkArkmeIdAvailability()`, `setArkmeIdOnce()` | `arkme_id_set` with human confirmation | `ProfileService.checkArkmeIdAvailability()` / `setArkmeIdOnce()` |
+| Phone bind/rebind | Built-in SMS dialog | `sendPhoneCode()`, `verifyPhoneCode()` | Blocked: human captcha and SMS code must not be model-driven | `AuthService.sendPhoneCode()` / `verifyPhoneCode()` |
+| WeChat bind/rebind | Status only, explicit unavailable feedback | Blocked until a Host OAuth bridge exists | Blocked until a Host OAuth bridge exists | Flutter AppBridge only today |
+
+UI structure:
+
+```text
+设置页
+  账户概览
+    头像 + 名称 + Arkme ID + Arkme ID 旁二维码图标入口
+  账户
+  账号信息
+    Arkme ID：当前 ID / 暂未获取到账号 ID -> 设置账号 ID 弹窗
+    手机号：脱敏号码 / 未绑定 -> 绑定或更换手机号弹窗
+    微信：绑定昵称 / 已绑定 / 未绑定 -> DSH OAuth 能力缺失反馈
+```
+
+Interaction flow:
+
+```text
+点击 Arkme ID -> 本地格式校验 -> Host 可用性校验 -> 人类确认 -> Host 写入 -> 刷新 profile -> 关闭弹窗
+点击 Arkme ID 旁二维码图标 -> 用 shareWebsite + arkmeId 生成二维码 -> 打开二维码弹窗 -> 复制链接 -> 状态反馈
+点击手机号 -> 极验验证 -> 发送短信 -> 输入验证码 -> Host 验证绑定 -> 刷新 auth/profile -> 关闭弹窗
+点击微信 -> 显示 Flutter AppBridge OAuth 缺失说明，不发起伪请求
+```
 
 `readImage(avatarRef)` resolves an opaque image reference returned by `profile()` or `listSources()`. Private chats expose one optional `avatarRef`. Groups expose the preferred additive `groupAvatar` presentation plus legacy `avatarRefs`: `groupAvatar.slots` preserves the server-selected order for up to five members, including safe phone-default or generic fallbacks when a real image is absent, while legacy `avatarRefs` contains only resolvable real images. `memberCount`, `strategy`, and `computedAtMillis` describe the snapshot without exposing member or session identities. The Provider refreshes an authorized public profile image before downloading it and returns bounded PNG/JPEG/WebP/GIF base64 bytes; signed URLs, STS credentials and bearer tokens never enter the browser contract. Consumers must use `imageDataUrl()` (or decode the payload themselves) instead of concatenating OSS URLs or fetching an avatar reference directly.
 

package/docs/file-flow-parity.md

@@ -0,0 +1,213 @@
+# File lifecycle parity
+
+Baseline: official master `3af3554949e8d47f2fcb8f3962e2da1aced0ba73`
+(v0.1.28), rebased on 2026-08-27 before this correction.
+
+Client reference (read-only): native frontend remote `pre-release`
+`0fc133450`, inspected on 2026-08-27. Only the Arkme plugin is changed; no
+client or DSH source is changed.
+
+## Product reference, not internal capability names
+
+The client input toolbar has exactly two actions: 添加照片和文件 and 写长文
+(`features/chat/presentation/input_toolbar.dart`, lines 714–731 at the reference).
+Local file staging is an implementation detail, not a 本地附件 menu or library.
+The client preview uses 接收文件 / 打开 in the file panel and a download icon at
+the bottom; it does **not** have an 另存为 button. The icon invokes a destination
+picker before receiving/copying bytes (`features/file/presentation/desktop/desktop_image_preview.dart`,
+lines 999–1054, 1485–1554 and 2214–2247).
+
+The bottom download icon is visible **before reception**, while receiving and
+after reception, unless that page has already been saved successfully in the
+current preview. This condition is independent of the original-file cache
+(`desktop_image_preview.dart`, lines 99–112 and 2214–2247;
+`test/features/file/desktop_image_preview_open_file_test.dart`, lines 357–379).
+The center action changes from 接收文件 to percentage progress, then hands the
+completed local original to the operating system and closes the preview. Opening
+the same cached original later shows 打开. These statements describe the remote
+desktop source, not a driven native-app acceptance test.
+
+File icons use the user-selected **B: Untitled UI File Icons / Solid** set,
+pinned to `@untitledui/file-icons@0.0.9`. All 12 SVGs retain upstream geometry
+and default colors; see [asset provenance and license](file-icon-licenses.md).
+This intentionally replaces the previous native-client assets. The shared icon
+keeps MIME-first classification, adding a dedicated DMG icon; Markdown uses
+the same set's code icon and unknown files its empty icon. Drafts use 32px,
+message/search cards 40px, and the information panel 64px. The Solid preview
+icon is intentionally smaller than the previous 120px native-style sizing,
+following visual feedback; card/draft sizes and transfer actions are unchanged.
+Assets are embedded
+in the client bundle, with no external image requests or new dependency.
+This is UI-only: Host, SDK and Tools are N/A for this icon change because no
+business capability, transfer logic or button visibility rule changes.
+
+| User step | Plugin behavior following the client |
+| --- | --- |
+| Add files | Existing picker, clipboard files or drop; prepare locally, spinner in add button |
+| Pending attachments | Preview/remove and drag order; keyboard Alt+arrows without extra visible controls |
+| Send | Accept a fixed message with attachments, clear that draft, allow the next input while uploading |
+| Upload | Per-file overlay/progress; completing capped at 99%; failure removes a stale progress overlay |
+| Retry | Keep the message identity and already uploaded siblings; never overwrite a newer draft |
+| Open a remote generic file | 接收文件, shared percentage progress, then automatically open with the system default application |
+| Open a cached generic file | Show 打开 and hand the account-bound local original to the system default application |
+| Open browser media/text | Reuse original bytes; supported media and Markdown keep the existing inline renderer |
+| Download | Client download icon; native browser picker first where supported, cancellation has no download side effect |
+| Search | Existing file scene; reuse the same file card, receiver and viewer |
+
+Image, video and generic-file presentation are separate after classification.
+Real filename/MIME format wins over a stale upstream `file_kind=4`, so JPG,
+MP4 and MP3 records do not flash or remain in a generic file card. Presentation
+classification is separate from browser decoding: HEIC and SVG remain images,
+and MKV remains video, even when the Web host cannot render their bytes inline.
+Those formats use a media-shaped receive/download fallback instead of being
+relabeled as files. Legacy visual metadata is still rejected when the real
+filename has a non-media suffix, preventing old `.dmg` records from being
+decoded as images. PDF, Office documents, archives, installers and unknown
+types remain generic files. Recorded voice messages continue to use the audio
+flow.
+
+If an image or transient video resource fails to load, the message keeps an
+image- or video-shaped failure tile with a retry action. It does not temporarily
+replace that media with a generic file card. Retrying uses a fresh URL, and a
+newer record version clears stale failure state. A browser-declared unsupported
+image or video format instead offers 接收图片 or 接收视频 and opens the existing
+receive/download flow; it does not promise that retrying the same bytes will work. This prevents
+the observed `image -> file text/card -> image` flash while preserving explicit
+files.
+
+The retry/status UI is a plugin recovery adaptation, not a claim that every
+client surface has an identical retry control. Unknown server acknowledgement
+is reconciled against recent messages and is never blindly resent with new IDs.
+
+## Contract before implementation
+
+Select/import prepares account-bound local files only. Accepting a send persists
+the message and its local references before releasing the composer. Cloud upload
+progress belongs to message attachments; uploaded bytes are not a sent message.
+Retries retain successful assets and the original record/relation identifiers.
+An uncertain message acknowledgement must not be silently retried with new IDs.
+
+Drafts, messages and file search share a file viewer. Original-file reception is
+distinct from browser download/save; a thumbnail is never an original fallback.
+File search uses existing scene 4. Existing upload()/sendRich() consumers retain
+their synchronous completion contract.
+
+| Consumer | Required implementation | Verification |
+| --- | --- | --- |
+| Host | Single account-bound file owner: local staging, MIME normalization, durable send state, upload progress, original reception and validated local open | Owner, account-isolation, API-proxy and route failure/recovery tests |
+| UI | Local attachment strip, preview/reorder/remove, optimistic files, per-file progress, retry; distinct visual/file rendering; generic receive/open state machine | Interactive and rendering tests, actual Web acceptance |
+| SDK | Public typed stage/send/status/retry/receive plus `openLocalFile(fileRef)`; paths never cross the API | External consumer compile and contract tests |
+| Tools | Existing `arkme_file_task` adds confirmed `open-local` for opaque current-account file refs; no arbitrary filesystem read | Formal catalog/grant registration and official DSH session invocation |
+
+DSH public seams: WebServer.register() owns HTTP response lifecycle and returns a
+disposer. Existing Arkme HTTP adapters remain responsible for Origin/auth checks.
+The Host resolves an opaque Arkme file ref and calls the public `ctx.apiProxy.host.openPath`
+gateway, which owns Finder / Explorer / xdg-open handoff. Before that handoff,
+the owner creates an account-scoped hard-link alias with a sanitized original
+file name and extension. This lets the OS recognize PDF, ZIP, Office and other
+generic formats while the canonical cache remains opaque. Both paths stay
+Host-side and aliases are removed with their cached originals. DSH attachment v1 supports images only, not generic files. No private
+DSH imports, custom shell-open commands or new remote upload/search services are introduced.
+
+## Acceptance
+
+- Selection performs no cloud upload; importing failure preserves valid siblings.
+- Local acceptance releases input; each file has actual upload progress capped
+  below completion until complete-upload succeeds.
+- Partial upload failure retains completed assets; message failure never replaces
+  a newer draft; source/account changes cannot rebind a pending send.
+- Same record ID is idempotent; uncertain acknowledgement is shown explicitly.
+- Original reception is shared, validates length, and never promotes partial data.
+- Cache/staging references remain account-bound and do not expose paths or URLs.
+- Generic files show 接收文件, real percentage progress, automatically open on
+  successful reception, and an already received file card opens the account-local
+  original directly without showing a second confirmation dialog.
+- When an authoritative remote message replaces its local pending send row, the
+  current-account task rebinds each matching `fileAssetUid` to its opaque local
+  file ref. A file selected on this device therefore never regresses to 未下载.
+- Browser download fallback reports only handoff, never unverified disk-save success.
+- With a supported save picker, success is reported only after the writable file closes.
+- Feature remains plugin-only; running user profiles are not replaced.
+
+## Verification and remaining boundaries
+
+Typecheck, the complete media/file interaction matrix and the production build
+passed on macOS. The full suite passed 1917 product tests and skipped 5; its
+remaining package-list harness uses an npm flag that npm 11 no longer parses,
+including the B / Solid icon replacement. File icon tests pin all 12 SVG hashes,
+check inactive/self-contained assets, retain MIME precedence and verify the
+shared draft/card/preview mapping, including DMG. No new Host, SDK or Tool
+behavior is introduced by this visual correction.
+
+The file viewer uses a 64px icon and places its close control inside the
+top-right corner, with a 32px hit target and 12px inset. Information and content
+views both reserve space above their content. Click and Escape dismissal remain
+covered; the latter stops propagation so a parent detail view stays open.
+
+The Web adaptation shows actual reception percentages on the reference client's
+220px-wide, 4px-high rounded track, with no invented percentage when total bytes
+are unknown. A received browser-previewable image, video, audio or supported text
+file offers Preview. A stale generic-file marker cannot override a real media
+format. PDF, XML, Office documents, installers, archives and unknown formats use
+the native generic-file flow: 接收文件, percentage progress, automatic system open,
+then 打开 for the cached original. PDF is never placed in a blank browser iframe.
+Clicking an already received generic-file card bypasses the information panel and
+hands the cached original directly to the native opener. The panel remains the
+receive/progress/retry surface for files that are missing, receiving or failed.
+The bottom download control remains a separate optional disk-copy action and does
+not replace the central receive/open state. No native-application limitation text
+or central save-success state is shown.
+
+The mounted message view now retains its last usable attachment display when
+the Host explicitly reports a media lookup failure for the same record version.
+It keeps the existing failure notice and replaces references on recovery. It
+does not retain media across source/record changes, unknown/newer versions,
+deleted records, or a successful response that removes attachments. The
+regression sequence (complete, unavailable, recovered) formerly rendered
+attachment counts `1 -> 0 -> 1`; it now renders `1 -> 1 -> 1`. This reproduces
+one deterministic failure path, not every possible live intermittent symptom.
+
+Native copy remains blocked: the desktop reference's `_copyImage` first calls
+`Pasteboard.writeFiles`, with an image fallback (lines 956–997). It copies a
+file, not its name or a URL. DSH rc.7 exposes `writeClipboard(text: string)`;
+the inspected browser bridges cover app updates/notifications/calls, not native
+file clipboard writes. Standard browser clipboard formats are not an
+equivalent OS file-list contract. No shell-on-Host workaround, misleading
+copy-name fallback, or nonfunctional copy button is added. A client-side native
+file-clipboard bridge with explicit permission is needed for full parity.
+Owner/SDK route tests cover account isolation, Origin, range reads, local staging,
+durable identity, partial upload failure, unknown acknowledgement, cache reuse,
+truncated reception, validated native opening, save cancellation and failed disk writes. UI tests also
+cover original-menu-only, drag order, shared card reception, formatted Markdown
+and the absence of invented file-library/Save-As controls.
+
+An isolated official DSH rc.7 installation loaded the immutable package on a
+fresh Profile. Its Host reported `canOpenPath=true`; the real Web conversation
+rendered a remote PDF with 接收文件 as the central action and the separate download
+icon. The file Tool owner/action and conversational confirmation are covered by
+registration and dispatch tests; no automated acceptance opened a user file.
+A separate external consumer compiled against the packaged public SDK and its
+exported `ArkmeFileOpenResult`. These checks do not prove authenticated upstream
+upload/send behavior. The interactive fixture uses real plugin components and
+file owner, but simulated upstream upload/send ports; it never sends to a real
+user's conversation.
+
+Still **not full native-client parity**:
+
+- Native opening is available only when this DSH Host reports its official native
+  opener capability. The plugin uses that Host seam and never invents a remote
+  browser-open claim. Native file clipboard copy remains unavailable: the public
+  clipboard primitive accepts text, not an OS file list, so no misleading copy
+  fallback is added.
+- Browser save dialogs, clipboard file availability, video codecs and PDF viewer
+  support depend on the browser. Native OS dialogs and Windows/Linux behavior
+  have not been validated. The current receive/preview presentation is not a
+  pixel-identical client clone.
+- File size remains bounded by Host configuration (default 100 MiB); image limit
+  is at most 50 MiB and attachment limit is 9. Do not promise the client's 200 MiB
+  non-image limit or dynamic VIP quota without an authoritative capability.
+- Real-account upload, private/group/self/topic delivery, weak-network behavior
+  and the full native client reference flow still require end-to-end acceptance.
+- Native client code was inspected at the remote reference; the Flutter client
+  itself was not driven through this flow. Passing plugin tests is not proof
+  that the two products are completely aligned.

package/docs/file-icon-licenses.md

@@ -0,0 +1,54 @@
+# Third-party file icon attribution
+
+The bundled file icons use **Untitled UI File Icons, Solid**, version 0.0.9.
+
+- Official project: https://www.untitledui.com/react/resources/file-icons
+- Package: https://www.npmjs.com/package/@untitledui/file-icons/v/0.0.9
+- Upstream author, as declared in package metadata: Dilshod Turobov.
+- Upstream declared license: MIT. The published package does not include a
+  separate LICENSE file or dated copyright notice; the attribution above
+  preserves its supplied author information. The MIT terms are reproduced below.
+- Archive: https://registry.npmjs.org/@untitledui/file-icons/-/file-icons-0.0.9.tgz
+- Verified archive SHA-512 (base64):
+  `wz3btNnSSv2hTujgyxEFL21oyjPtGTj3osU8ZEMe8nwdlmLQEILLe96NMg9b1ciiOC5UOWNDeYIt7IfxEM6qtg==`
+
+Static SVGs were extracted from the package's `dist/solid/*.mjs` element trees,
+using default size 40 and theme light without executing upstream modules.
+Only serialization changed; paths, fills and proportions are unchanged.
+The UI scales them to 32/40/64px. No remote resources or active SVG content are
+used. This attribution is shipped in the plugin package alongside the bundle.
+
+| Local asset suffix | Upstream Solid module |
+| --- | --- |
+| audio | audio.mjs |
+| csv | csv.mjs |
+| default | empty.mjs |
+| dmg | dmg.mjs |
+| excel | xls.mjs |
+| md | code.mjs |
+| pdf | pdf.mjs |
+| ppt | ppt.mjs |
+| txt | txt.mjs |
+| video | video.mjs |
+| word | doc.mjs |
+| zip | zip.mjs |
+
+## MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/docs/group-ai-polish-member-enablement.md

@@ -0,0 +1,49 @@
+# Group AI polish management
+
+Group AI polish is a shared group capability. Any active member may manage it when the chat service returns `can_manage: true`; clients must not infer permission from owner/admin roles or require a group-member-list request.
+
+## Capability matrix
+
+| Surface | Contract |
+| --- | --- |
+| Tools | `arkme_group_ai_polish_manage` resolves an exact group name, reads status, previews a generated or saved rule, and performs an enable/disable write only after explicit confirmation. |
+| SDK | External plugins discover `features.groupAiPolish` and use public methods to query settings, generate or select a rule, and prepare/confirm enable or disable operations. |
+| UI | The group header shows the active state and rule. The existing three-dot menu opens a centered rules dialog and conversational rule editor. |
+| Host owner | `GroupAiPolishService` owns permission checks, rule selection, confirmation expiry, concurrency control, persistence, cache invalidation, and fresh readback verification for every adapter. |
+
+## Permission and confirmation contract
+
+- The server-provided `can_manage` value is authoritative for every read-modify-write flow.
+- Permission is checked again immediately before a confirmed write. A revoked membership or permission cannot reuse an earlier preview.
+- Confirmation references are opaque, scoped to the current account, action, and group, and expire after ten minutes.
+- A natural-language requirement always generates a preview. It must not silently select an existing rule.
+- Enabling a saved rule does not regenerate or upsert it. When selection is ambiguous, the caller must request an exact rule name or opaque rule reference.
+- Editing an existing rule records its version at preview time and rejects a concurrent edit instead of overwriting it.
+- Saving and enabling are treated as a recoverable two-step operation. If saving succeeds but enabling or verification fails, a retry reuses the saved rule rather than creating a duplicate.
+- A positive write response is not sufficient. The Host invalidates cached settings and verifies the enabled state, active rule, and approved rule content with a fresh read.
+- Server denial is reported as a permission failure, never as an inability to fetch group members.
+
+## Desktop interaction
+
+- The enabled state and active rule are visible beneath the group title.
+- The only settings entry is `AI 表达润色` inside the existing group three-dot menu.
+- The centered dialog supports selecting a saved rule, disabling polish, and opening a conversational editor for a new or existing rule.
+- Loading, retryable failure, read-only permission, confirmation, success, and partial-write recovery remain scoped to the selected group.
+- The editor persists mobile-compatible `rule_thread_messages`, so mobile and desktop can continue the same rule conversation.
+- Settings changes replace only the selected group's AI-polish snapshot; they do not reload the conversation timeline.
+
+## Conversation rendering reliability
+
+- A confirmed send replaces only its optimistic message row and writes the same result into the selected conversation cache before the conversation summary advances.
+- Realtime deltas merge into the latest rendered timeline instead of replacing restored history with the delta alone.
+- Identical in-flight timeline reads are shared. Switching sources or requesting a different page still cancels obsolete work.
+- Expected request cancellation is silent. Transient idempotent reads use bounded retries and persistent failures settle into an actionable error state.
+- Outgoing message rows retain their existing right-aligned container while text wrapping remains inside the bubble.
+
+## Verification requirements
+
+- Cover ordinary-member success, server denial, revoked permission, ambiguous selection, stale preview, retry after partial success, and fresh readback mismatch at the Host owner.
+- Cover Tool discovery, grant, schema, preview/confirmation behavior, and the absence of member-list lookup.
+- Compile and exercise the public SDK consumer contract without private imports.
+- Cover menu, dialog, editor, row-only send reconciliation, retained timeline history, request single-flight, retry, and error settlement in UI tests.
+- Before delivery, run related tests, typecheck, the complete test suite, production build, immutable `.tgz` inspection, and installation into an unmodified official DSH with a fresh temporary Profile.