@senguoyun/dsh-arkme 0.1.11 → 0.1.13

package/README.md

@@ -1,10 +1,14 @@
 # Arkme DSH Plugin
 
-Arkme 的 DeepSeek Harness 集成插件，为 DSH 提供账号、记录、聊天、Bot、社区、通话和扩展市场能力。
+Arkme 的 DeepSeek Harness 集成插件，为 DSH 提供账号、记录、聊天、Bot、社区、通话和市集能力。
 
 - npm：[`@senguoyun/dsh-arkme`](https://www.npmjs.com/package/@senguoyun/dsh-arkme)
 - 源码：[`arkme-senx/arkme-dsh-plugin`](https://github.com/arkme-senx/arkme-dsh-plugin)
 
+## 功能
+
+- 内置搜索页支持快记搜索、搜索历史、纯图片库和已生成 AI 视频快速入口；图片库采用桌面端多列视图并排除普通视频。
+
 ## 安装
 
 将插件安装到 DSH Web Profile：
@@ -78,7 +82,7 @@ pnpm run verify:call-assets
 - [工具注册与能力目录](docs/tool-registry.md)
 - [外部插件消费合同](docs/consumer-plugin-contract.md)
 - [请求协调与限流](docs/request-coordination.md)
-- [扩展市场控制](docs/extension-market-controls.md)
+- [市集控制](docs/extension-market-controls.md)
 - [扩展评论与评分](docs/extension-reviews.md)
 - [消息已读乐观更新](docs/read-ack-optimistic-flow.md)
 - [Agent 代理发送链路](docs/agent-proxy-sender-flow.md)

package/assets/desktop_call/call-add-linear.svg

@@ -0,0 +1,13 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g id="Property 1=linear">
+<g id="vuesax/linear/call-add">
+<g id="call-add">
+<g id="call-add_2">
+<path id="Vector" d="M21.97 18.33C21.97 18.69 21.89 19.06 21.72 19.42C21.55 19.78 21.33 20.12 21.04 20.44C20.55 20.98 20.01 21.37 19.4 21.62C18.8 21.87 18.15 22 17.45 22C16.43 22 15.34 21.76 14.19 21.27C13.04 20.78 11.89 20.12 10.75 19.29C9.6 18.45 8.51 17.52 7.47 16.49C6.44 15.45 5.51 14.36 4.68 13.22C3.86 12.08 3.2 10.94 2.72 9.81C2.24 8.67 2 7.58 2 6.54C2 5.86 2.12 5.21 2.36 4.61C2.6 4 2.98 3.44 3.51 2.94C4.15 2.31 4.85 2 5.59 2C5.87 2 6.15 2.06 6.4 2.18C6.66 2.3 6.89 2.48 7.07 2.74L9.39 6.01C9.57 6.26 9.7 6.49 9.79 6.71C9.88 6.92 9.93 7.13 9.93 7.32C9.93 7.56 9.86 7.8 9.72 8.03C9.59 8.26 9.4 8.5 9.16 8.74L8.4 9.53C8.29 9.64 8.24 9.77 8.24 9.93C8.24 10.01 8.25 10.08 8.27 10.16C8.3 10.24 8.33 10.3 8.35 10.36C8.53 10.69 8.84 11.12 9.28 11.64C9.73 12.16 10.21 12.69 10.73 13.22C11.27 13.75 11.79 14.24 12.32 14.69C12.84 15.13 13.27 15.43 13.61 15.61C13.66 15.63 13.72 15.66 13.79 15.69C13.87 15.72 13.95 15.73 14.04 15.73C14.21 15.73 14.34 15.67 14.45 15.56L15.21 14.81C15.46 14.56 15.7 14.37 15.93 14.25C16.16 14.11 16.39 14.04 16.64 14.04C16.83 14.04 17.03 14.08 17.25 14.17C17.47 14.26 17.7 14.39 17.95 14.56L21.26 16.91C21.52 17.09 21.7 17.3 21.81 17.55C21.91 17.8 21.97 18.05 21.97 18.33Z" stroke="#292D32" stroke-width="1.5" stroke-miterlimit="10"/>
+<path id="Vector_2" d="M15.5 6H20.5" stroke="#292D32" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+<path id="Vector_3" d="M18 8.5V3.5" stroke="#292D32" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+</g>
+</g>
+</g>
+</g>
+</svg>

package/assets/desktop_call/icon-scan-add-contact.svg

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg width="800px" height="800px" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <path fill-rule="evenodd" clip-rule="evenodd" d="M5 8a1 1 0 0 1-2 0V5.923c0-.76.082-1.185.319-1.627.223-.419.558-.754.977-.977C4.738 3.082 5.162 3 5.923 3H8a1 1 0 0 1 0 2H5.923c-.459 0-.57.022-.684.082a.364.364 0 0 0-.157.157c-.06.113-.082.225-.082.684V8zm3 11a1 1 0 1 1 0 2H5.923c-.76 0-1.185-.082-1.627-.319a2.363 2.363 0 0 1-.977-.977C3.082 19.262 3 18.838 3 18.077V16a1 1 0 1 1 2 0v2.077c0 .459.022.57.082.684.038.07.087.12.157.157.113.06.225.082.684.082H8zm7-15a1 1 0 0 0 1 1h2.077c.459 0 .57.022.684.082.07.038.12.087.157.157.06.113.082.225.082.684V8a1 1 0 1 0 2 0V5.923c0-.76-.082-1.185-.319-1.627a2.363 2.363 0 0 0-.977-.977C19.262 3.082 18.838 3 18.077 3H16a1 1 0 0 0-1 1zm4 12a1 1 0 1 1 2 0v2.077c0 .76-.082 1.185-.319 1.627a2.364 2.364 0 0 1-.977.977c-.442.237-.866.319-1.627.319H16a1 1 0 1 1 0-2h2.077c.459 0 .57-.022.684-.082a.363.363 0 0 0 .157-.157c.06-.113.082-.225.082-.684V16zM3 11a1 1 0 1 0 0 2h18a1 1 0 1 0 0-2H3z" fill="#000000"/>
+</svg>

package/assets/desktop_call/profile-circle-linear.svg

@@ -0,0 +1,11 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g id="Property 1=linear">
+<g id="vuesax/linear/profile-circle">
+<g id="profile-circle">
+<path id="Vector" d="M12.12 12.78C12.05 12.77 11.96 12.77 11.88 12.78C10.12 12.72 8.71997 11.28 8.71997 9.50998C8.71997 7.69998 10.18 6.22998 12 6.22998C13.81 6.22998 15.28 7.69998 15.28 9.50998C15.27 11.28 13.88 12.72 12.12 12.78Z" stroke="#292D32" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+<path id="Vector_2" d="M18.74 19.38C16.96 21.01 14.6 22 12 22C9.40001 22 7.04001 21.01 5.26001 19.38C5.36001 18.44 5.96001 17.52 7.03001 16.8C9.77001 14.98 14.25 14.98 16.97 16.8C18.04 17.52 18.64 18.44 18.74 19.38Z" stroke="#292D32" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+<path id="Vector_3" d="M12 22C17.5228 22 22 17.5228 22 12C22 6.47715 17.5228 2 12 2C6.47715 2 2 6.47715 2 12C2 17.5228 6.47715 22 12 22Z" stroke="#292D32" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+</g>
+</g>
+</g>
+</svg>

package/assets/desktop_call/user-add-linear.svg

@@ -0,0 +1,15 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g id="Property 1=linear">
+<g id="vuesax/linear/user-add">
+<g id="user-add">
+<path id="Vector" d="M12 12C14.7614 12 17 9.76142 17 7C17 4.23858 14.7614 2 12 2C9.23858 2 7 4.23858 7 7C7 9.76142 9.23858 12 12 12Z" stroke="#292D32" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+<path id="Vector_2" d="M3.41003 22C3.41003 18.13 7.26003 15 12 15C12.96 15 13.89 15.13 14.76 15.37" stroke="#292D32" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+<path id="Vector_3" d="M22 18C22 18.32 21.96 18.63 21.88 18.93C21.79 19.33 21.63 19.72 21.42 20.06C20.73 21.22 19.46 22 18 22C16.97 22 16.04 21.61 15.34 20.97C15.04 20.71 14.78 20.4 14.58 20.06C14.21 19.46 14 18.75 14 18C14 16.92 14.43 15.93 15.13 15.21C15.86 14.46 16.88 14 18 14C19.18 14 20.25 14.51 20.97 15.33C21.61 16.04 22 16.98 22 18Z" stroke="#292D32" stroke-width="1.5" stroke-miterlimit="10" stroke-linecap="round" stroke-linejoin="round"/>
+<g id="Group">
+<path id="Vector_4" d="M19.49 17.98H16.51" stroke="#292D32" stroke-width="1.5" stroke-miterlimit="10" stroke-linecap="round" stroke-linejoin="round"/>
+<path id="Vector_5" d="M18 16.52V19.51" stroke="#292D32" stroke-width="1.5" stroke-miterlimit="10" stroke-linecap="round" stroke-linejoin="round"/>
+</g>
+</g>
+</g>
+</g>
+</svg>

package/cordis.patch.yml

@@ -15,6 +15,7 @@
         intelligentBaseUrl: https://intelligent.jotmo.cc
         audioBaseUrl: https://audio.jotmo.cc
         extensionPublishBaseUrl: https://extension-publish.jotmo.cc
+        shareWebsite: https://jiwo.cc
         extensionArtifactDirectory: ''
         extensionTrustedSigningKeys: '{"prod-ed25519-20260819-1":"m1MKKU16hyu1b1KKIXMG+zKEr/GmhmvyUEreJzthTxs="}'
         routePath: /arkme-self/api
@@ -28,7 +29,9 @@
         allowProduction: true
         updateCheckEnabled: true
         updateChannel: stable
-        updateRegistryUrl: https://registry.npmjs.org
+        updateServiceBaseUrl: https://api.jotmo.cc
+        updateArtifactBaseUrl: https://d.jiwo.cc
+        appVersion: ''
         updateCheckIntervalHours: 12
         updateAllowLocalInstall: true
         richMediaRenderEnabled: true

package/docs/consumer-plugin-contract.md

@@ -41,6 +41,11 @@ await arkme.outbox()
 await arkme.retry(recordUid)
 const mine = await arkme.myExtensions()
 const publishable = mine.items.find(item => item.publish.allowed)
+if (publishable?.publish.allowed === true) showPublishRoute(
+  publishable.publish.route,
+  publishable.publish.artifactContractVersion,
+  publishable.publish.artifactKind,
+)
 if (publishable !== undefined && userConfirmedPublish) await arkme.publishMyExtension({
   ownedRef: publishable.ownedRef,
   name: publishable.name,
@@ -51,6 +56,10 @@ if (publishable !== undefined && userConfirmedPublish) await arkme.publishMyExte
 })
 const dispose = arkme.subscribe(state => refreshWhen(state.revision))
 if ((await arkme.capabilities()).features.extensionManagement === true) {
+  const market = await arkme.searchExtensions('weather', 20)
+  const detail = market.items[0] === undefined ? undefined : await arkme.extensionDetail(market.items[0].extension_id)
+  const installPreview = detail === undefined ? undefined : await arkme.extensionInstallPreview(detail.extension_id)
+  if (installPreview?.artifact_contract_version === 3) showNativeCapabilities(installPreview.native_capabilities ?? [])
   const installed = await arkme.installedExtensions()
   if (installed[0] !== undefined) await arkme.setExtensionEnabled(installed[0].extensionId, false)
 }
@@ -68,15 +77,15 @@ if ((await arkme.capabilities()).features.extensionPreviews === true && userConf
 
 The SDK communicates only with the same-origin Provider route. Consumers must not read OS credential-store entries, SQLite files, state files, or tokens directly.
 
-`capabilities().features.myExtensions` advertises the current-account extension inventory. `myExtensions()` merges only Host-approved live Cordis, Profile-local and cloud-owned facts; consumers must use its states and `publish.allowed` result without rescanning Profile files or inferring ownership from names. `ownedRef` is short-lived and account-bound. `publishMyExtension()` requires a current explicit human request and can publish only the exact Cordis Package, local Bundle directory or local Bundle tgz behind that ref; consumers must refresh the list after expiry or account switch. Profile paths, Agent IDs, source archives, artifact upload requests and signing material never enter this contract.
+`capabilities().features.myExtensions` advertises the current-account extension inventory. `myExtensions()` merges only Host-approved live Cordis, Profile-resolved and cloud-owned facts; consumers must use its states and `publish` result without rescanning Profile files or inferring ownership from names. Every publishable item carries one Host-derived route: `dynamic-cordis-v2` means `artifactContractVersion=2` and `artifactKind=dsh-bundle-tgz` for a live current-session Dynamic Cordis Package; `profile-native-v3` means `artifactContractVersion=3` and `artifactKind=dsh-native-package-tgz` for an installed or Profile-local DSH Bundle. Callers must display that route and pass `ownedRef` unchanged rather than choosing a mode themselves. A GitHub repository URL is provenance metadata, not a third upload route or a cloud clone/build request. A third-party registry/Git dependency appears only when its actually resolved package declares `dsh.bundle.patch`; it is a V3 publication candidate rather than an assertion that the current account authored the upstream code. Public publication still requires accurate GitHub provenance and redistribution rights. `ownedRef` is short-lived and account-bound. `publishMyExtension()` requires a current explicit human request and can publish only the exact Cordis Package, resolved Bundle directory or local Bundle tgz behind that ref; consumers must refresh the list after expiry or account switch. Profile paths, Agent IDs, source archives, artifact upload requests and signing material never enter this contract.
 
 Plugin update discovery and acknowledgement are lifecycle concerns owned by the bundled Arkme UI. They are intentionally absent from the public Browser SDK, Host `arkmeData` service and model tool catalog. Consumers must not invoke raw `plugin.update.*` operations or attempt to mutate a DSH profile.
 
-`capabilities().features.extensionManagement === true` advertises the installed-extension projection and desired enable-state contract. `installedExtensions()` omits artifact paths, Profile package names and Dynamic Cordis IDs. `setExtensionEnabled()` retains the verified artifact and installed version; its result distinguishes desired `enabled`, observed Host `active`, and `restart_required`. Consumers must call it only from a current explicit human action, must display restart/error results, and must never turn an enable/disable control into uninstall. The Provider remains the only writer of the Profile manifest and install-state database.
+`capabilities().features.extensionManagement === true` advertises market queries, install preview, the installed-extension projection and desired enable-state contract. `searchExtensions()` and `extensionDetail()` return the same V1/V2/V3 version projection as the built-in UI and model Tool. `extensionInstallPreview()` is read-only and returns `artifact_contract_version`, `artifact_kind`, `execution_model`, `requires_native_confirmation` and server-derived `native_capabilities`; a Consumer must show those capabilities and obtain explicit human confirmation before starting installation through its product flow. `installedExtensions()` omits artifact paths, Profile package names and Dynamic Cordis IDs while retaining V3 contract/capability facts. `setExtensionEnabled()` retains the verified artifact and installed version; its result distinguishes desired `enabled`, observed Host `active`, and `restart_required`. Consumers must call it only from a current explicit human action, must display restart/error results, and must never turn an enable/disable control into uninstall. The Provider remains the only writer of the Profile manifest and install-state database.
 
 `capabilities().features.extensionIcons === true` advertises the extension-owned icon contract. `setExtensionIcon()` accepts a user-selected PNG, JPEG or WebP `Blob` up to 2 MiB for an extension owned by the current account. `extensionIconUrl()` turns the catalog's opaque current `icon_ref` into a same-origin image URL. Consumers must refresh catalog state after replacement, render the generic extension mark when an icon is missing or unreadable, and must never persist an old ref or receive, reconstruct, or fetch an object-storage URL directly.
 
-`capabilities().features.extensionPreviews === true` advertises the extension-owned preview gallery MVP. `addExtensionPreview()` accepts a user-selected PNG, JPEG or WebP `Blob` up to 5 MiB. A gallery contains at most 20 ordered items; index zero is the cover. `deleteExtensionPreview()` and `reorderExtensionPreviews()` require the current `preview_revision`; a conflict means the Consumer must refresh and ask the user again instead of silently overwriting the newer gallery. Render refs only through `extensionPreviewUrl()`. The built-in extension-center detail renders the ordered gallery and its Edit dialog stages local multi-file add/delete/reorder before saving. Agent Tools can consume captured latest direct-user-message attachments, a compatible Arkme `image_ref`, or PNG/JPEG/WebP/restricted-SVG files inside the current Agent workspace. They accept only relative `workspace_paths`, reject path traversal and symlink escapes, and never accept arbitrary host paths or URLs. Icon and preview addition use Host-enforced conversational `prepare`/`confirm` state bound to a later direct-user reply and unchanged content fingerprints rather than a DSH ACK card.
+`capabilities().features.extensionPreviews === true` advertises the extension-owned preview gallery MVP. `addExtensionPreview()` accepts a user-selected PNG, JPEG or WebP `Blob` up to 5 MiB. A gallery contains at most 20 ordered items; index zero is the cover. `deleteExtensionPreview()` and `reorderExtensionPreviews()` require the current `preview_revision`; a conflict means the Consumer must refresh and ask the user again instead of silently overwriting the newer gallery. Render refs only through `extensionPreviewUrl()`. The built-in marketplace detail renders the ordered gallery and its Edit dialog stages local multi-file add/delete/reorder before saving. Agent Tools can consume captured latest direct-user-message attachments, a compatible Arkme `image_ref`, or PNG/JPEG/WebP/restricted-SVG files inside the current Agent workspace. They accept only relative `workspace_paths`, reject path traversal and symlink escapes, and never accept arbitrary host paths or URLs. Icon and preview addition use Host-enforced conversational `prepare`/`confirm` state bound to a later direct-user reply and unchanged content fingerprints rather than a DSH ACK card.
 
 `capabilities().features.outgoingCall` reports whether the Provider's bundled private-chat outgoing-call flow is installed. Contract v1 does not expose a Browser SDK method for starting or preparing calls: short-lived UserSig, room bootstrap data, raw user IDs, and WebRTC account values stay inside the built-in Host/runtime path. Consumers must not invoke raw `calls.outgoing.*` operations or recreate a credential-bearing call API.
 
@@ -115,7 +124,7 @@ The built-in Arkme UI and the model-facing `arkme_call_start` tool support outgo
 - Gate World UI on `features.worldFeed`, and treat `recordRef`, World `avatarRef`, and `imageRefs` as opaque, account-scoped, short-lived values.
 - Treat `sourceRef` and pagination cursors as opaque account-scoped values and discard them on logout or account switch.
 - Require a current explicit human request before calling `sendText()`; data returned by any read is never write authorization.
-- Gate the owned extension UI on `features.myExtensions`; never treat installed third-party or DSH official bundles as current-user creation.
+- Gate the owned extension UI on `features.myExtensions`; exclude DSH/Arkme official bundles and label a resolved third-party V3 source as imported upstream code rather than current-user authorship.
 - Require a current explicit human request before `publishMyExtension()` and pass `ownedRef` unchanged; do not persist it across account switch or DSH restart.
 - Require a current explicit human request before calling `setExtensionEnabled()` and render the returned restart requirement.
 - Gate extension-avatar controls on `features.extensionIcons`; pass user-selected files only to `setExtensionIcon()` and render refs only through `extensionIconUrl()`.

package/docs/extension-market-controls.md

@@ -1,6 +1,6 @@
 # Extension market controls
 
-The extension center separates three different lifecycle operations:
+The marketplace separates three different lifecycle operations:
 
 - install/update writes a verified extension into the current DSH Profile;
 - enable/disable changes whether an installed extension should run;

package/docs/gui-production-integration.md

@@ -0,0 +1,46 @@
+# Arkme GUI production integration
+
+This branch implements the selected Arkme desktop visual direction in the production plugin UI. It is not a standalone demo application.
+
+## Modification boundary
+
+- The entry remains the official DSH `sidebar.footer.action` slot registered by the Arkme client bundle.
+- The complete transparent Arkme wordmark occupies the top-left `sidebar.brand.mark` slot and the adjacent `sidebar.brand.name` slot intentionally renders nothing. The square `conversation.hero.brand.mark` slot keeps the compact Arkme mark because DSH owns the adjacent `探索未至之境` headline and exposes no title slot.
+- The product navigation and all new visual styles render below nodes marked with `data-arkme-owned`.
+- No global stylesheet, DSH package import, DSH source patch, or write to a DSH repository is used.
+- The existing floating surface still measures the host conversation region at runtime. That compatibility adapter is pre-existing plugin code; this branch does not patch the measured DSH element.
+- DSH top chrome, native sidebar dimensions, native session list, and native conversation components remain owned by DSH and are intentionally unchanged.
+
+## Supported visual routes
+
+| Route | Layout inside the Arkme surface | Production owner | Status |
+| --- | --- | --- | --- |
+| Conversations | Feature rail + conversation directory + content | Existing Arkme source directory and timeline | Implemented |
+| Recordings | Feature rail + full-width recording page | Existing recording calendar/day API | Implemented with the updated Demo's date browser, selected-day list, day timeline, and content tabs |
+| Search | Feature rail + full-width search page | Existing record search and AI video API | Implemented with the existing search actions and history |
+| Calendar | Feature rail + floating month calendar + day-content panel | Baseline calendar bucket/day APIs | Implemented with real counts, date switching, paging, loading, empty, and error states |
+| Marketplace | Feature rail + full-width marketplace page | Existing Arkme marketplace | Implemented as the real search/install/uninstall marketplace |
+| Tasks | Not rendered | No stable task-list/session contract in the plugin | Deferred; no mock implementation |
+
+The conversation directory is mounted only in conversation mode. It is unmounted for recordings, search, calendar, and plugins so its asynchronous source restoration cannot force a utility page back to the conversation layout.
+
+The conversation route keeps the existing production composer for this iteration. Its add-content `+` is moved to the far-left edge of the toolbar, while the remaining redesign is limited to the surrounding three-column shell, directory density, header alignment, message typography and bubbles, member drawer alignment, and list metadata placement.
+
+The plugin page keeps the production extension operations. The embedded discovery view intentionally omits the modal-only category tab strip to match the Demo; `我的插件` switches to the installed list, while install, uninstall, detail, loading, restart, and error flows remain the existing implementations.
+
+## Capability matrix
+
+| Surface | Decision | Evidence |
+| --- | --- | --- |
+| UI | Required | Production `src/client` components provide navigation, responsive layout, and visible states. |
+| Tools | N/A | This change adds no Host route, query, command, or persisted business capability. Existing Tools are unchanged. |
+| SDK | N/A | This change adds no business capability for external plugins. Existing SDK exports are unchanged. |
+| Host owner | Existing owners | Conversations, recordings, search, and extensions continue to use their existing `callArkme` operations. |
+
+## Packaging acceptance
+
+The final acceptance artifact must be an immutable `.tgz` built from this worktree and installed into a fresh profile of an unmodified supported DSH runtime. A standalone Vite preview is not acceptance evidence.
+
+Final acceptance used the rebased `@senguoyun/dsh-arkme@0.1.11` package as an immutable `.tgz` installed through the official DSH plugin command into a fresh isolated DSH home. The runtime was a clean `@deepseek-ai/dsh@0.1.0-rc.8` install with no runtime-level Arkme dependency; no DSH checkout was created or modified.
+
+Typecheck, production build, and the complete test suite passed. The suite result is 152 test files passed and 3 skipped, with 837 tests passed and 3 skipped. Saved Demo/production comparisons remain in `qa/`; final host-integration checks were performed at `http://127.0.0.1:5193/`.

package/docs/record-calendar-ui-flow.md

@@ -0,0 +1,88 @@
+# DSH Record Calendar UI Flow
+
+## Scope
+
+Migrate the Arkme record calendar surface into the DSH plugin by reusing the client record-service calendar APIs:
+
+- `POST /api/v1/calendar/buckets/query`
+- `POST /api/v1/calendar/records/query`
+
+The DSH plugin exposes only the signed-in user's self calendar in this iteration. Topic-scoped calendar can be added later through provider-issued `sourceRef` resolution without exposing raw topic UIDs.
+
+## Capability Matrix
+
+| Surface | Entry | Owner |
+| --- | --- | --- |
+| UI | `calendar.buckets`, `calendar.records` from `ArkmeCalendarSurface` | `CalendarService` |
+| SDK | `sdk.calendarBuckets()`, `sdk.calendarRecords()` | `CalendarService` |
+| Tools | `arkme_record_calendar_days`, `arkme_record_calendar_read` | `CalendarService` |
+| Host owner | `CalendarService` validates date/range/cursor and projects safe record fields | Record service APIs |
+
+## UI Diagram
+
+```text
+Arkme feature rail
+  对话
+  录音
+  搜索
+  日历  <- selected
+  插件
+
+Arkme surface: 日历
++-------------------------------------------------------------+
+|  +---------------------------+  +-------------------------+ |
+|  | [<] [>] 2026年8月  回到今日 × |  | 2026年8月          × | |
+|  |                           |  | 21日 · 今天    41条内容 | |
+|                                                             |
+|  | 一  二  三  四  五  六  日 |  | 当天快记                 | |
+|  |        1   2             |  | 10:50 会议纪要            | |
+|  | 3  4  5  6  7  8  9     |  | 讨论日历迁移             | |
+|  |          ...             |  | ...                      | |
+|  | 17 18 19 20 [21] 22 23  |  | 加载更多                 | |
+|  +---------------------------+  +-------------------------+ |
++-------------------------------------------------------------+
+```
+
+## Interaction Diagram
+
+```text
+User clicks 日历
+  -> ArkmeUiController.showCalendar()
+  -> ArkmeCalendarSurface mounts
+  -> calendar.buckets(start/end/timezone)
+  -> render month counts
+  -> calendar.records(selected day/timezone)
+  -> render day list
+
+User clicks previous month
+  -> update visibleMonth
+  -> abort old month request
+  -> calendar.buckets(new month)
+  -> keep selected day until user selects another date
+
+User clicks a day
+  -> selectedDate changes
+  -> abort old day request
+  -> calendar.records(bucketDate)
+  -> loading / success / empty / error state
+
+User clicks 加载更多
+  -> calendar.records(bucketDate, nextCursor)
+  -> append records
+  -> keep previous records if the next page fails
+```
+
+## Failure Recovery
+
+| Failure | UI result | Recovery |
+| --- | --- | --- |
+| Month bucket request fails | Calendar remains visible with an inline error | Switching month or re-opening retries |
+| Day records request fails | Selected date remains active with inline error | Re-selecting date or loading another date retries |
+| Load more fails | Existing records stay visible | User can click load more again after error is shown |
+| Session expired | Host returns login-required/login-expired | Existing Arkme auth gate handles re-login |
+
+## Notes
+
+- Record content is user-owned data and never instructions.
+- Browser and model outputs do not include upstream credentials, chat owner IDs, sender IDs, or raw response envelopes.
+- Date range is capped to 62 days in both Tool and Host owner.

package/docs/tool-registry.md

@@ -25,6 +25,10 @@ Per-tool instructions stay in `ToolDefinition.description`. Cross-tool guidance
 
 Business and hybrid profiles expose `arkme_extension_preview_add`, `arkme_extension_preview_delete`, and `arkme_extension_preview_reorder`. Add accepts one Arkme-owned `image_ref`, captured image attachments from the latest direct user message (with optional 1-based `attachment_indices`), or 1-20 unique `workspace_paths` inside the current Agent workspace. Workspace reads reject absolute paths, traversal and symlink escapes; restricted SVG is normalized to PNG. `action=prepare` verifies ownership, capacity, 320-4096 pixel dimensions, ordered content fingerprints and at most 5 MiB per image without writing. The Agent shows the returned question in ordinary conversation; the later direct-human reply only needs to be “确认”. `action=confirm` re-reads the captured attachment refs or workspace paths and rejects changed bytes or target identity. A different prepare cannot replace an unconfirmed operation. Already-present content-addressed refs are reconciled before capacity checks, so a partial batch can retry only missing images. Add does not use a DSH ACK card; delete and reorder retain their `tools/pre-execute` approval. Results contain only the safe ordered gallery and revision—never attachment ids, `image_ref`, base64, workspace paths, object keys, signed URLs, or signed headers. Atomic and disabled profiles expose none of these Tools.
 
+## Group member Tools
+
+Business and hybrid profiles expose `arkme_group_member_candidates` and `arkme_group_member_add`. Candidate discovery accepts only an account-bound group `source_ref`, excludes current members and returns signed, opaque `candidate_ref` values for people from the signed-in user's private chats. The write Tool accepts 1-20 unchanged candidate refs, requires explicit-user-write confirmation, reports each outcome independently, and sends private invitation links when the group's join policy requires approval. Raw user IDs are never exposed to the model.
+
 ## Adding a tool
 
 1. Add one module under `src/tools/business`, `src/tools/atomic` or `src/tools/system`.