diff --git a/.agents/notes/README.i18n.yaml b/.agents/notes/README.i18n.yaml index 1fa95a5e2d..4b6ef324b9 100644 --- a/.agents/notes/README.i18n.yaml +++ b/.agents/notes/README.i18n.yaml @@ -12,8 +12,8 @@ en: 055a5e49f9af3dc2 zh: 9f7c78409cccfded /agent-notes/archiving-and-deletion: - en: 6c393c7058c787d7 - zh: 70ce9ca3bd9c2133 + en: 57ccc5fec461ebb0 + zh: 69e8f9e79abc53aa /agent-notes/when-to-write-one: en: 2beb1b94d8fb633c zh: 889b5542bb771205 diff --git a/.agents/notes/README.md b/.agents/notes/README.md index 6872de0a13..8cee939fcf 100644 --- a/.agents/notes/README.md +++ b/.agents/notes/README.md @@ -39,7 +39,7 @@ Delete an implemented Agent Note that only describes small UI adjustments or pur The archive is path-encoded as `archived/{class}/yyyy-mm-dd-topic-title.md`; `implemented` is deliberately absent because only implemented notes can enter it. An archival change moves the complete English/Chinese/sidecar triplet, retains `Status: implemented`, inserts the same `Archived: YYYY-MM-DD` line immediately below that status in both language files, re-records the sidecar, and repairs or deletes inbound links. These are the only permitted content changes during archival. Existing title punctuation, blank-line layout, and language-switcher wording do not block archival; preserve them with the body. -Once sealed, every archived triplet is permanently frozen. Do not edit, translate, reformat, update, move, or delete it, and do not treat it as authority for current behavior. Documentation gates skip archived sources, including their outbound links; active prose may still link into an archived note when it intentionally cites history. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) enforces the closed class tree, complete triplets, archive metadata, sidecar hashes, and the append-only frozen-content manifest. The [archive-policy Agent Note](implemented/process/2026-07-26-frozen-agent-note-archive.md) owns the rationale. +Once sealed, every archived triplet is permanently frozen. Do not edit, translate, reformat, update, move, or delete it, and do not treat it as authority for current behavior. Documentation gates skip archived sources, including their outbound links; active prose may still link into an archived note when it intentionally cites history. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) enforces the closed class tree, complete triplets, archive metadata, sidecar hashes, and the append-only frozen-content manifest, except for the exact seal transitions documented in [archive instructions](archived/AGENTS.md). The [archive-policy Agent Note](implemented/process/2026-07-26-frozen-agent-note-archive.md) owns the rationale. ## When to write one diff --git a/.agents/notes/README.zh.md b/.agents/notes/README.zh.md index ced81f77fa..6339f56f7c 100644 --- a/.agents/notes/README.zh.md +++ b/.agents/notes/README.zh.md @@ -41,7 +41,7 @@ 归档路径编码为 `archived/{class}/yyyy-mm-dd-topic-title.md`；其中有意省略 `implemented`，因为只有 implemented Agent Note 可以进入归档。归档变更会移动完整的英文、中文和伴随记录三个文件，保留 `Status: implemented`，在两种语言的文件中紧接该状态行插入相同的 `Archived: YYYY-MM-DD` 行，重新记录伴随记录，并修复或删除入站链接。归档时只允许对内容做这些更改。 既有标题标点、空行布局和语言切换栏措辞不阻止归档；与正文一起保留。 -封存后，每组归档文件都永久冻结。禁止编辑、翻译、重新格式化、更新、移动或删除，也不得将其视为当前行为的权威依据。文档门禁会跳过归档源文件，包括其中的出站链接；当活跃文档有意引用历史时，仍可链接到归档 Agent Note。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 强制执行封闭的类别目录树、完整的三文件配对、归档元数据、伴随记录 hash，以及仅追加的冻结内容 manifest（元数据清单）。[归档政策 Agent Note](implemented/process/2026-07-26-frozen-agent-note-archive.zh.md) 记录了设计依据。 +封存后，每组归档文件都永久冻结。禁止编辑、翻译、重新格式化、更新、移动或删除，也不得将其视为当前行为的权威依据。文档门禁会跳过归档源文件，包括其中的出站链接；当活跃文档有意引用历史时，仍可链接到归档 Agent Note。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 强制执行封闭的类别目录树、完整的三文件配对、归档元数据、伴随记录 hash，以及仅追加的冻结内容 manifest（元数据清单），但[归档说明](archived/AGENTS.md)中记录的精确封存哈希转换除外。[归档政策 Agent Note](implemented/process/2026-07-26-frozen-agent-note-archive.zh.md) 记录了设计依据。 diff --git a/.agents/notes/archived/AGENTS.md b/.agents/notes/archived/AGENTS.md index 2ac4518a6a..d013ed068e 100644 --- a/.agents/notes/archived/AGENTS.md +++ b/.agents/notes/archived/AGENTS.md @@ -5,3 +5,5 @@ Archived Agent Note triplets under the kind directories are frozen historical sn The archival change may only relocate a complete English/Chinese/sidecar triplet, insert the identical `Archived: YYYY-MM-DD` line below both `Status: implemented` lines, re-record the sidecar, and repair or delete inbound links. Do not inspect, verify, or repair links out of archived notes. Run the [`dsh-archive-agent-notes`](../../skills/dsh-archive-agent-notes/SKILL.md) workflow and append new artifact hashes with `pnpm run verify-archived-agent-notes --write`. The normal verifier rejects changed or missing sealed artifacts, incomplete triplets, unknown kind folders, and invalid archive metadata. + +The authorized Figma-link removal from `feature/2026-08-10-durable-workflow-runs-in-chat` has three exact old-to-new seal exceptions in `scripts/archived-agent-notes.ts` for its English, Chinese, and pairing files. These exceptions permit no other content change, reversal, or deletion. diff --git a/.agents/notes/archived/architecture/2026-09-24-web-default-schedule-composition.i18n.yaml b/.agents/notes/archived/architecture/2026-09-24-web-default-schedule-composition.i18n.yaml new file mode 100644 index 0000000000..b5321c036f --- /dev/null +++ b/.agents/notes/archived/architecture/2026-09-24-web-default-schedule-composition.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write +2026-09-24-web-default-schedule-composition.md: 3f27bb09ebc00d42c32563e17a1de82c8e525be1 +2026-09-24-web-default-schedule-composition.zh.md: 9e0e1fb77ce89b579e1bc8b0d4d0a1b9f4e9fea5 diff --git a/.agents/notes/implemented/architecture/2026-09-24-web-default-schedule-composition.md b/.agents/notes/archived/architecture/2026-09-24-web-default-schedule-composition.md similarity index 99% rename from .agents/notes/implemented/architecture/2026-09-24-web-default-schedule-composition.md rename to .agents/notes/archived/architecture/2026-09-24-web-default-schedule-composition.md index 91f533950a..3f27bb09eb 100644 --- a/.agents/notes/implemented/architecture/2026-09-24-web-default-schedule-composition.md +++ b/.agents/notes/archived/architecture/2026-09-24-web-default-schedule-composition.md @@ -1,6 +1,7 @@ # Agent Note: Schedule in the shipped Web composition Status: implemented +Archived: 2026-09-25 English | [中文](2026-09-24-web-default-schedule-composition.zh.md) diff --git a/.agents/notes/implemented/architecture/2026-09-24-web-default-schedule-composition.zh.md b/.agents/notes/archived/architecture/2026-09-24-web-default-schedule-composition.zh.md similarity index 99% rename from .agents/notes/implemented/architecture/2026-09-24-web-default-schedule-composition.zh.md rename to .agents/notes/archived/architecture/2026-09-24-web-default-schedule-composition.zh.md index af561fe63e..9e0e1fb77c 100644 --- a/.agents/notes/implemented/architecture/2026-09-24-web-default-schedule-composition.zh.md +++ b/.agents/notes/archived/architecture/2026-09-24-web-default-schedule-composition.zh.md @@ -1,6 +1,7 @@ # Agent Note: 默认 Web 组合中的 Schedule Status: implemented +Archived: 2026-09-25 [English](2026-09-24-web-default-schedule-composition.md) | 中文 diff --git a/.agents/notes/archived/feature/2026-08-10-durable-workflow-runs-in-chat.i18n.yaml b/.agents/notes/archived/feature/2026-08-10-durable-workflow-runs-in-chat.i18n.yaml index 284f43658a..871a8eefb8 100644 --- a/.agents/notes/archived/feature/2026-08-10-durable-workflow-runs-in-chat.i18n.yaml +++ b/.agents/notes/archived/feature/2026-08-10-durable-workflow-runs-in-chat.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/archived/feature/2026-08-10-durable-workflow-runs-in-chat.md -2026-08-10-durable-workflow-runs-in-chat.md: 01c59ef25996d6349ab2904f148bf4e72fdd5f09 -2026-08-10-durable-workflow-runs-in-chat.zh.md: 5f6b39b59beca5e2363261605ec58fbdcf71ea6f +2026-08-10-durable-workflow-runs-in-chat.md: a49cb75e44bd65ef694679eeb295cfef564c7545 +2026-08-10-durable-workflow-runs-in-chat.zh.md: 753e02238cd8c00d0494cb673ba9896d61ff4cd8 diff --git a/.agents/notes/archived/feature/2026-08-10-durable-workflow-runs-in-chat.md b/.agents/notes/archived/feature/2026-08-10-durable-workflow-runs-in-chat.md index 01c59ef259..a49cb75e44 100644 --- a/.agents/notes/archived/feature/2026-08-10-durable-workflow-runs-in-chat.md +++ b/.agents/notes/archived/feature/2026-08-10-durable-workflow-runs-in-chat.md @@ -25,7 +25,7 @@ The renderer gives each level a distinct visual responsibility. The run uses a 3 Navigation is derived from two current authorities rather than persisted. A member row is interactive only while its durable member state is running and the current ordinary Session list contains the same id with `origin: 'subagent'`, `parentId` equal to the displayed parent, and `running: true`. Underlined member text is the only visible affordance; keyboard focus draws a two-pixel business-primary ring around the name area, and the fixed status label remains the lifecycle word rather than an action instruction. The renderer invokes only the injected ordinary `sessions.open(id)` callback. Addressed-only, remote, wrong-parent, and terminal members remain visible but static. -The [seven-state Figma reference](https://www.figma.com/design/tguwzZRmHCjbq58mfsqT0M?node-id=5-2) fixes the information hierarchy for running expanded/collapsed, completed history/expanded, failed plus cancelled, interrupted recovery, and dark narrow presentation. Repository `DisclosureRow`, `StateDot`, icons, semantic tokens, and keyed-node behavior remain the implementation authority; the reference introduces no runtime field or state owner. +The seven-state Figma reference fixes the information hierarchy for running expanded/collapsed, completed history/expanded, failed plus cancelled, interrupted recovery, and dark narrow presentation. Repository `DisclosureRow`, `StateDot`, icons, semantic tokens, and keyed-node behavior remain the implementation authority; the reference introduces no runtime field or state owner. ## Verification diff --git a/.agents/notes/archived/feature/2026-08-10-durable-workflow-runs-in-chat.zh.md b/.agents/notes/archived/feature/2026-08-10-durable-workflow-runs-in-chat.zh.md index 5f6b39b59b..753e02238c 100644 --- a/.agents/notes/archived/feature/2026-08-10-durable-workflow-runs-in-chat.zh.md +++ b/.agents/notes/archived/feature/2026-08-10-durable-workflow-runs-in-chat.zh.md @@ -25,7 +25,7 @@ renderer 为每一层分配不同视觉职责。运行使用 32 像素 module-pl 导航从两个当前权威派生，不写入持久记录。只有持久成员状态仍为运行中，且当前普通 Session 列表包含同一 id、`origin: 'subagent'`、`parentId` 等于当前父 Session、`running: true` 时，成员行才可交互。带下划线的成员文字是唯一可见提示；键盘聚焦时，名称区显示 2 像素 business-primary 焦点环，固定状态列继续只表达生命周期，而不写动作说明。renderer 只调用注入的普通 `sessions.open(id)` 回调。仅地址化、远程、父级不符或终态成员继续可见，但保持静态。 -[七状态 Figma 参考](https://www.figma.com/design/tguwzZRmHCjbq58mfsqT0M?node-id=5-2)固定运行展开／收起、完成历史／展开、失败与取消、恢复后中断以及暗色窄列的信息层级。仓库的 `DisclosureRow`、`StateDot`、图标、语义 token 和 keyed-node 行为仍是实现权威；参考稿不引入运行时字段或状态 owner。 +七状态 Figma 参考固定运行展开／收起、完成历史／展开、失败与取消、恢复后中断以及暗色窄列的信息层级。仓库的 `DisclosureRow`、`StateDot`、图标、语义 token 和 keyed-node 行为仍是实现权威；参考稿不引入运行时字段或状态 owner。 ## 验证 diff --git a/.agents/notes/archived/manifest.json b/.agents/notes/archived/manifest.json index 5ed6850038..44178cc0ec 100644 --- a/.agents/notes/archived/manifest.json +++ b/.agents/notes/archived/manifest.json @@ -376,6 +376,9 @@ "architecture/2026-09-11-wasm-preview-font-and-image-budgets.i18n.yaml": "sha256:af027c7dae53a181e4d73fd2309f69e9ae3c48df0d3b1dfc53cae274aa60d69e", "architecture/2026-09-11-wasm-preview-font-and-image-budgets.md": "sha256:44dd52839cdb67644c0dbcbc4beb6f36802628c4a8d17a0aad11db1f9be649ed", "architecture/2026-09-11-wasm-preview-font-and-image-budgets.zh.md": "sha256:8285432ee1676be8b79a05953c4b6ac4a7ca5d8e701173b3a2b533608b584d0a", + "architecture/2026-09-24-web-default-schedule-composition.i18n.yaml": "sha256:8c3d5c614924d0e81f361a299427ac697aefc6189c41eb3f4151f5c42e371ca0", + "architecture/2026-09-24-web-default-schedule-composition.md": "sha256:3a139593ade13f95cbb67094c1eec66cb0a2c14bcc154512799803b2a7d22ab4", + "architecture/2026-09-24-web-default-schedule-composition.zh.md": "sha256:59908f7987058742d1226dc8a801d03c265c84d51172249ba51716b91f084f0c", "bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml": "sha256:8be5b0afd8820c593e2ec254d35fb8c384267814104f6234bb9af824c5f974ba", "bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md": "sha256:861e6130e893489271478def5f54f212a106a1580b744e6e40f56356f73c7e10", "bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md": "sha256:3549257e06f074591de580ebfaa71284c7c384fb0ffb1963c30258d7a7c26db7", @@ -1264,9 +1267,9 @@ "feature/2026-08-10-creator-guidance-introduce-cue.i18n.yaml": "sha256:74f519839f0cf82c7304bdeae41ae1cab8bb930bfb94f79ab44708acd3b72128", "feature/2026-08-10-creator-guidance-introduce-cue.md": "sha256:3e25409dda498de150de18943ee332e1760963e377a40a365902b66f667fdc9f", "feature/2026-08-10-creator-guidance-introduce-cue.zh.md": "sha256:203847010cab9e9d13c3969f17921d3a5aa0d69377eccfef555c7ff96572f162", - "feature/2026-08-10-durable-workflow-runs-in-chat.i18n.yaml": "sha256:0db3c21a3c8785e56d5d7b90df990b158069cd1cea664e62fc4786c6d7588450", - "feature/2026-08-10-durable-workflow-runs-in-chat.md": "sha256:f9f5290cd880908d17b1080ae5776f22e182f5253471f90cf8bead418b33b502", - "feature/2026-08-10-durable-workflow-runs-in-chat.zh.md": "sha256:f4ffd2700bc9c2a0cc4b9d90f84e1d0a576939e2e6f0b130c5b142fd8cd518b0", + "feature/2026-08-10-durable-workflow-runs-in-chat.i18n.yaml": "sha256:03eadb60c8ba4fde262cd61e3f911d8cd68ea4a58f57adeb8dd7bb9a97d08ca2", + "feature/2026-08-10-durable-workflow-runs-in-chat.md": "sha256:6018de4a89ca99d6cbfd618aff1c8136b23d8e4854a30f7b12a602f0417cbdc2", + "feature/2026-08-10-durable-workflow-runs-in-chat.zh.md": "sha256:0080859221773122022d5880efa3d52f29c0872b52d63e170250d94f214ff37a", "feature/2026-08-10-minimal-read-image-tool.i18n.yaml": "sha256:2311b6453b90a1f81d4fcbdaa723ab233cc0998f34393956364c8b92bc4d1213", "feature/2026-08-10-minimal-read-image-tool.md": "sha256:debe6b570d11634f57a80eaa5891e4fd1e7a5aac19f10fb7dd1683c316515150", "feature/2026-08-10-minimal-read-image-tool.zh.md": "sha256:572d080340682b354cb1f8a0f74af153d6542bd3dffbe3b72b32591e5d5d3baf", diff --git a/.agents/notes/implemented/architecture/2026-09-16-host-schedule-storage.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-16-host-schedule-storage.i18n.yaml index 159fee0bf9..8bc4eaeaa5 100644 --- a/.agents/notes/implemented/architecture/2026-09-16-host-schedule-storage.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-16-host-schedule-storage.i18n.yaml @@ -15,5 +15,5 @@ en: 21d7ec9a9ff3cbf2 zh: 93d03b8b3012aa7e /agent-note-host-owned-scheduled-messages/consequences: - en: 0358aab730e4bf56 - zh: 61e89e0374891f8a + en: a48f13f89a1944b1 + zh: f8fa677122ce2e12 diff --git a/.agents/notes/implemented/architecture/2026-09-16-host-schedule-storage.md b/.agents/notes/implemented/architecture/2026-09-16-host-schedule-storage.md index 79a4f72071..3d90e8ad7e 100644 --- a/.agents/notes/implemented/architecture/2026-09-16-host-schedule-storage.md +++ b/.agents/notes/implemented/architecture/2026-09-16-host-schedule-storage.md @@ -58,7 +58,7 @@ Session inbox persistence and the task put occur in separate persistence systems **Keep the mock's hourly choice out of the stored vocabulary.** The approved mock lists 每小时整点 beside the daily, weekly and one-shot choices. Hourly and fixed-rate intervals are the same elapsed-time rule, so the card maps that menu slot onto the existing interval kind instead of adding a persisted kind. A dedicated hourly kind would need a new durable variant, its decoder, its target resolution, and its tool schema, all to express what an interval already expresses. -Task discovery and timers do not depend on loaded Sessions. The after, absolute-time, and fixed-rate selectors retain their semantics alongside Daily, Weekly, and Cron; reading existing saved tasks does not rewrite them. The Host must have its ordinary Session persistence and recovery services available, and the Web bundle mounts Schedule in its host row list. Explicit deletion stops future delivery and removes the task from `list` and `catalog` without deleting conversation messages; the removed row takes its saved receipts with it. History is pruned to the configured window and record cap when an acknowledgment is appended, loaded into Host memory, and rewritten with the task on each acknowledgment. Pagination limits the returned record count; the plugin configuration (`deliveryHistoryDays`, default 30, and `deliveryHistoryRecords`, default 200) limits storage growth. Earlier overwritten receipts and deliveries whose task write failed cannot be reconstructed. Pause and execution-history operations remain unsupported. +Task discovery and timers do not depend on loaded Sessions. The after, absolute-time, and fixed-rate selectors retain their semantics alongside Daily, Weekly, and Cron; reading existing saved tasks does not rewrite them. The Host must have its ordinary Session persistence and recovery services available, and enabling the optional experimental bundle `@deepseek-ai/dsh-experimental-schedule-bundle` mounts Schedule; the Web composition carries its row disabled. Explicit deletion stops future delivery and removes the task from `list` and `catalog` without deleting conversation messages; the removed row takes its saved receipts with it. History is pruned to the configured window and record cap when an acknowledgment is appended, loaded into Host memory, and rewritten with the task on each acknowledgment. Pagination limits the returned record count; the plugin configuration (`deliveryHistoryDays`, default 30, and `deliveryHistoryRecords`, default 200) limits storage growth. Earlier overwritten receipts and deliveries whose task write failed cannot be reconstructed. Pause and execution-history operations remain unsupported. Required coverage includes startup from stored tasks, missing-status normalization, cold Session restoration, latest-only catch-up, inactive-task retention without repeat dispatch, real message receipts, deletion across restart, removal of a deleted task's saved deliveries, queue/persistence failures, and disposal. Wall-clock obligations include gaps and skipped dates, earlier-only overlaps, fractional seconds, UTC-range edges, committed-target and alias preservation, and post-restoration clock rollback. Weekly adds weekday normalization and validation, next-target selection across a gap and an overlap, and stored set preservation. Historical decoders must reject Daily, Weekly, and Cron while Host storage accepts them. Client coverage includes every recurring kind, exact rule time, zone, and weekday set, All/Enabled/Inactive status filters, retained inactive details and original-Session navigation, authoritative refresh after confirmed deletion and notification, empty lists, reconnect, and late responses. Presentation coverage includes the page's New action starting a Session, the transcript card's narrowing of persisted result JSON including an incomplete or replayed result, the header clock's direct open for exactly one task and its count label, the idle-only row mark with the hover-card two-task limit and omission line. History coverage includes legacy byte preservation, append and restart, immutable sent instructions, strict latest-receipt consistency, stable cursor pagination, binding checks, failed persistence, and late page replies during refresh or task changes. Cross-store crash duplication remains an explicit limitation rather than a completion claim. diff --git a/.agents/notes/implemented/architecture/2026-09-16-host-schedule-storage.zh.md b/.agents/notes/implemented/architecture/2026-09-16-host-schedule-storage.zh.md index 393a773fa0..f7b9a8f889 100644 --- a/.agents/notes/implemented/architecture/2026-09-16-host-schedule-storage.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-16-host-schedule-storage.zh.md @@ -58,7 +58,7 @@ Session 收件箱持久化和任务 put 发生在两个持久化系统中。收 **不把 mock 的「每小时整点」引入持久词表。** 设计稿把它与每天、每周、仅一次并列。每小时整点与固定间隔在语义上是同一种按经过时间计量的规则，因此详情里的该项直接映射到既有的间隔类型，而不是新增一个持久种类。若真要新增，需要新的持久变体、解码器、目标解析与工具 schema，而它表达的能力现有间隔已经覆盖。 -任务发现和 timer 不依赖已加载的 Session。延迟、绝对时间和固定速率选择器在与 Daily、Weekly、Cron 并存时保留自身语义；读取已有任务不会重写它们。Host 必须提供普通 Session 持久化和恢复服务，Web bundle 在其宿主行列表中挂载 Schedule。显式删除会阻止后续投递，并将任务从 `list` 和 `catalog` 中移除，不删除对话消息；被移除的行会带走其已保存回执。历史在追加确认时按配置的窗口与条数上限裁剪，随后加载到 Host 内存，并在每次确认时随任务一起重写。分页限制返回记录数量，不限制存储增长或指令字节数。此前被覆盖的回执，以及任务写入失败的投递记录，无法重建。暂停和执行历史操作仍不受支持。 +任务发现和 timer 不依赖已加载的 Session。延迟、绝对时间和固定速率选择器在与 Daily、Weekly、Cron 并存时保留自身语义；读取已有任务不会重写它们。Host 必须提供普通 Session 持久化和恢复服务，而挂载 Schedule 需要启用可选实验 bundle `@deepseek-ai/dsh-experimental-schedule-bundle`；Web 组合以禁用状态携带其条目。显式删除会阻止后续投递，并将任务从 `list` 和 `catalog` 中移除，不删除对话消息；被移除的行会带走其已保存回执。历史在追加确认时按配置的窗口与条数上限裁剪，随后加载到 Host 内存，并在每次确认时随任务一起重写。分页限制返回记录数量，不限制存储增长或指令字节数。此前被覆盖的回执，以及任务写入失败的投递记录，无法重建。暂停和执行历史操作仍不受支持。 必要覆盖范围包括从已存储任务启动、缺失状态规范化、冷 Session 恢复、仅补发最新发生时点、保留未运行任务且不重复投递、真实消息回执、重启后的删除结果、删除会移除已保存发送记录、排队或持久化失败，以及销毁。钟表规则的验证要求包括缺口和跳过的日期、仅选择较早时点的重叠、小数秒、UTC 范围边缘、已提交目标和别名保留，以及恢复后的时钟回拨。Weekly 另需覆盖星期集合的规范化与校验、跨缺口与重叠的下一目标选择，以及已存集合的保留。历史解码器必须拒绝 Daily、Weekly 与 Cron，而宿主存储接受它们。客户端覆盖范围包括每种重复规则、精确规则时间、时区和星期集合、全部/已开启/未运行状态筛选、保留未运行任务详情和原 Session 导航、确认删除和通知后的权威刷新、空列表、重新连接和晚到响应。呈现覆盖范围包括页面“新建”操作打开新会话、transcript 卡片从不完整或回放的结果 JSON 中收窄任务、页头时钟在恰好一个任务时直接打开并给出数量标签、仅空闲行标记及其悬浮卡片两个任务上限与遗漏行。历史覆盖范围包括旧文件字节保留、追加与重启、不可变的发送指令、最近回执一致性严格校验、稳定游标分页、绑定校验、持久化失败，以及刷新或切换任务期间晚到的分页响应。跨存储崩溃导致的重复投递仍是明确限制，不能被表述为完成保证。 diff --git a/.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-optional-bundles.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-optional-bundles.i18n.yaml index e8573b2e72..521567dd7e 100644 --- a/.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-optional-bundles.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-optional-bundles.i18n.yaml @@ -9,11 +9,11 @@ en: 2ba6c43b20a3d347 zh: 5647179ddaa38ad9 /agent-note-ship-experimental-capabilities-as-optional-bundles/decision: - en: 1c5a43b3ce2d3056 - zh: b59f549a12cf67d1 + en: fdd54ede661f7a83 + zh: a41ed1a872bb8ba3 /agent-note-ship-experimental-capabilities-as-optional-bundles/alternatives-considered: en: a65d84004e48b3ef zh: 17221f08e7a8a89b /agent-note-ship-experimental-capabilities-as-optional-bundles/consequences: - en: d52ed0a248131a37 - zh: 779b8d415281c5da + en: e7fb2a93a89ba9b6 + zh: 37ed9f0a3ca44583 diff --git a/.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-optional-bundles.md b/.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-optional-bundles.md index a2a83645c9..b7139f6d9a 100644 --- a/.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-optional-bundles.md +++ b/.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-optional-bundles.md @@ -10,7 +10,7 @@ The Web plugin page offered two optional bundles, Agent Teams and voice input. A ## Decision -`OPTIONAL_BUNDLES` lists Agent Teams, voice input, and Auto review. Every optional bundle declares `icon` and exports `./locale/*.json` with `meta.title` and `meta.description`, so the Official group renders a localized title, description, and image; `verify-default-product-isolation` rejects an optional bundle without them. The Inspector's `cordis.patch.yml` names the package instead of a built-artifact path, so the same file is the bundle patch and the `--patch` overlay for a built Web launch. +`OPTIONAL_BUNDLES` lists Agent Teams, voice input, Auto review, and the Schedule bundle. Every optional bundle declares `icon` and exports `./locale/*.json` with `meta.title` and `meta.description`, so the Official group renders a localized title, description, and image; `verify-default-product-isolation` rejects an optional bundle without them. The Inspector's `cordis.patch.yml` names the package instead of a built-artifact path, so the same file is the bundle patch and the `--patch` overlay for a built Web launch. An optional bundle is a runtime dependency of the installation, so its dependency graph is downloaded by every `dsh` install. The list therefore admits only packages whose graph is already in the installation's closure; Auto review adds nothing. The Inspector stays available through explicit installation and does not appear in the default plugin list. The browser-use and computer-use providers stay explicit compositions: Playwright MCP, Chrome DevTools MCP, and the native Cua Driver runtime binaries add about 85 MB and 21 packages to every install whether or not the bundle is enabled, and a shipped Cua Driver MCP switch would offer a capability whose executable the installation does not carry. Those provider packages keep locale display metadata for their component rows. Two more packages stay out for other reasons: `ptc-runtime-python` replaces the PTC runtime, and `workflow-ptc` rejects a non-TypeScript runtime at load while the Web presets carry `workflow-ptc` rows a bundle patch cannot reach; `browser-use-stagehand-native` requires a native model name and API key at schema validation with no configuration form on the page. @@ -22,4 +22,4 @@ An optional bundle is a runtime dependency of the installation, so its dependenc ## Consequences -The Official group grows from two to three entries, each tagged experimental by its experimental name. The runtime dependency closure of the installation is unchanged. A browser-use or computer-use provider still needs its Service Definition and the provider in a profile patch or composition. +The Official group carries four optional-bundle entries, each tagged experimental by its experimental name. The runtime dependency closure of the installation is unchanged. A browser-use or computer-use provider still needs its Service Definition and the provider in a profile patch or composition. diff --git a/.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-optional-bundles.zh.md b/.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-optional-bundles.zh.md index 62e248e5ae..af4048bc5e 100644 --- a/.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-optional-bundles.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-optional-bundles.zh.md @@ -10,7 +10,7 @@ Web 插件页只提供两个可选 bundle：Agent Teams 与语音输入。Auto r ## 决策 -`OPTIONAL_BUNDLES` 列出 Agent Teams、语音输入与 Auto review。每个可选 bundle 都声明 `icon` 并导出带 `meta.title` 与 `meta.description` 的 `./locale/*.json`，官方分组因此能渲染本地化标题、描述和图片；`verify-default-product-isolation` 会拒绝缺少这些声明的可选 bundle。Inspector 的 `cordis.patch.yml` 直接写包名而非构建产物路径，所以同一文件既是 bundle patch，也是已构建 Web 启动的 `--patch` overlay。 +`OPTIONAL_BUNDLES` 列出 Agent Teams、语音输入、Auto review 与 Schedule bundle。每个可选 bundle 都声明 `icon` 并导出带 `meta.title` 与 `meta.description` 的 `./locale/*.json`，官方分组因此能渲染本地化标题、描述和图片；`verify-default-product-isolation` 会拒绝缺少这些声明的可选 bundle。Inspector 的 `cordis.patch.yml` 直接写包名而非构建产物路径，所以同一文件既是 bundle patch，也是已构建 Web 启动的 `--patch` overlay。 可选 bundle 是安装的运行时依赖，其依赖图会随每次 `dsh` 安装一起下载。因此名单只接纳依赖图已在安装闭包内的包；Auto review 不增加任何依赖。Inspector 保留显式安装方式，不在默认插件列表中显示。浏览器操作与电脑操作提供方仍保持显式组合：Playwright MCP、Chrome DevTools MCP 与原生 Cua Driver 运行时二进制会让每次安装多出约 85 MB、21 个包，无论 bundle 是否启用；而随附的 Cua Driver MCP 开关会提供一个安装本身并不携带其可执行文件的能力。这些提供方包保留 locale 显示元数据，供组件行使用。另有两个包因其他原因不纳入：`ptc-runtime-python` 会替换 PTC 运行时，而 `workflow-ptc` 在加载时拒绝非 TypeScript 运行时，且 Web preset 内含 bundle patch 无法触及的 `workflow-ptc` 行；`browser-use-stagehand-native` 在 schema 校验时就要求原生模型名称与 API 密钥，而插件页没有对应的配置表单。 @@ -22,4 +22,4 @@ Web 插件页只提供两个可选 bundle：Agent Teams 与语音输入。Auto r ## 后果 -官方分组从两项增至三项，每项都因实验包名而带实验性标签。安装的运行时依赖闭包保持不变。浏览器操作或电脑操作提供方仍需在 profile patch 或组合中同时挂载其 Service Definition 与提供方。 +官方分组包含四个可选 bundle 条目，每项都因实验包名而带实验性标签。安装的运行时依赖闭包保持不变。浏览器操作或电脑操作提供方仍需在 profile patch 或组合中同时挂载其 Service Definition 与提供方。 diff --git a/.agents/notes/implemented/architecture/2026-09-24-schedule-opt-in-optional-bundle.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-24-schedule-opt-in-optional-bundle.i18n.yaml new file mode 100644 index 0000000000..ca6497cb81 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-24-schedule-opt-in-optional-bundle.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-09-24-schedule-opt-in-optional-bundle.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-24-schedule-opt-in-optional-bundle.md +/agent-note-schedule-as-an-opt-in-optional-bundle: + en: 8c2381fd778a9888 + zh: 8877255cb980eea1 +/agent-note-schedule-as-an-opt-in-optional-bundle/problem: + en: bb23c2f7f93a462b + zh: 9fb600fc8e203323 +/agent-note-schedule-as-an-opt-in-optional-bundle/decision: + en: 483d1dd51b9cc073 + zh: b069e2e2385c8132 +/agent-note-schedule-as-an-opt-in-optional-bundle/alternatives-considered: + en: 8e5f4d8fa8c2e78d + zh: 3353c7042c6a1d6b +/agent-note-schedule-as-an-opt-in-optional-bundle/consequences: + en: 36cd0eb71abeedbe + zh: 7c134095cc19fcfd diff --git a/.agents/notes/implemented/architecture/2026-09-24-schedule-opt-in-optional-bundle.md b/.agents/notes/implemented/architecture/2026-09-24-schedule-opt-in-optional-bundle.md new file mode 100644 index 0000000000..865f97848d --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-24-schedule-opt-in-optional-bundle.md @@ -0,0 +1,35 @@ +# Agent Note: Schedule as an opt-in optional bundle + +Status: implemented + +English | [中文](2026-09-24-schedule-opt-in-optional-bundle.zh.md) + +## Problem + +Schedule adds four tool schemas to every live root Agent request and one durable clock message per eligible step, so the shipped Web composition must not mount it by default. A person using the shipped Web profile still needs a product-surface switch to turn it on; a profile patch layer or a `--patch` overlay is a configuration file that person cannot reach. + +## Decision + +`packages/bundle/web-app/cordis.patch.yml` carries none of `time-context`, `schedule`, and `ui-schedule`, so the shipped Web composition exposes no Schedule surface: no `schedule_*` tools, no Session reminder catalog, no Automation tasks page, and no per-step clock reading. + +`@deepseek-ai/dsh-experimental-schedule-bundle` (`packages/experimental/schedule-bundle/`) inserts the three rows in its `cordis.patch.yml` and depends on their packages, as every other optional bundle inserts the rows it ships. `OPTIONAL_BUNDLES` in `packages/boot/app-boot/src/profile.ts` names the package, and `apps/cli` declares it as a runtime dependency, so every installation ships it switched off. The [experimental-as-optional-bundles decision](2026-09-21-experimental-capabilities-as-optional-bundles.md) owns the `OPTIONAL_BUNDLES` conventions and the localized `icon` and `meta.title` / `meta.description` metadata the Web Plugins page renders in its Official group. + +Enabling the bundle inserts `time-context` (a per-step clock reading with the sampled instant, the browser zone attached to the open request, and the elapsed time since the preceding model-visible message), `schedule` (durable reminders plus `schedule_create`, `schedule_list`, `schedule_update`, and `schedule_delete` on live root Agents), and `ui-schedule` (the Session reminder catalog and the Automation tasks page). The bundle carries `time-context` with `schedule` because a reminder request states a wall-clock target: the sampled instant is what lets the model turn a request such as "tomorrow at nine" into an offset-bearing `at` value. The [Schedule subsystem](../../../../docs/subsystems/schedule.md) owns the durable records, delivery, and management operations; the [Web bundle](../../../../packages/bundle/web-app/README.md) owns the composition the bundle adds the rows to. Disabling the bundle restores the shipped composition, and the Host stops scheduling while the `schedule` row is absent; stored task records remain in the Schedule domain. + +## Alternatives considered + +**Ship Schedule on by default.** Every Web session then pays four tool schemas in each request header and one durable user message per eligible step, and a conversation that never creates a reminder pays both costs. The arrangement also left the capability without an off switch on the product surface. + +**Keep a `--patch` overlay file.** An overlay is a launch-time argument rather than a product-surface switch, so a person using the shipped Web profile cannot reach it. Re-declaring the rows through its `insert` list does not override them: `applyEntryPatches` appends that list without de-duplicating ids, and the Loader collapses the composed list to one entry per id with the last declaration winning, so the overlay replaces the Web bundle's rows instead of setting fields on them. + +**Keep the rows in the Web composition with `disabled: true` and switch them on with id-targeted patches.** The bundle would then set fields on existing rows, but the plugin manager lists only the rows a bundle inserts, so the bundle's page reported no components and needed a second listing path for overridden rows, while every other optional bundle inserts its rows. A profile that also declares one of the ids resolves the same way as for any other bundle: the Loader keeps the last declaration. + +**Lock the three rows to the bundle switch.** A bundle manifest field that makes the plugin manager refuse to switch the rows one by one adds a plugin-manager concept only this bundle would use. The bundle's page offers a switch per row, as for every other bundle, and the bundle README records that the three rows work only together. + +## Consequences + +- A default `dsh web` session carries no Schedule tool schemas, no Session reminder catalog, no Automation tasks page, and no per-step clock reading. An installation that wants them enables the optional bundle from the Plugins page or lists the package in a profile's `dsh.profile.bundles`. +- An enabled installation adds four tool schemas to every live root Agent and one durable clock message per eligible step; the reading is model-visible and durable, so it replays, compacts, and appears in exported Session logs like any other user message. +- The Plugins page lists the three rows under the bundle with the titles their packages' `locale/*.json` declare, their state, and, while the bundle is on, a switch per row; switching one of them off leaves Schedule without that part. +- A profile patch or `--patch` overlay that targets one of the three ids matches no row while the bundle is not selected, and the loader warns `patch: entry not found` for it; selecting the bundle replaces switching the rows on by id. +- The switch is configuration-only: `src/index.ts` is an empty module, the patch carries the runtime content, and the package owns no mutable runtime state, so it publishes no invariant companion. diff --git a/.agents/notes/implemented/architecture/2026-09-24-schedule-opt-in-optional-bundle.zh.md b/.agents/notes/implemented/architecture/2026-09-24-schedule-opt-in-optional-bundle.zh.md new file mode 100644 index 0000000000..a90516606a --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-24-schedule-opt-in-optional-bundle.zh.md @@ -0,0 +1,35 @@ +# Agent Note: Schedule 作为按需开启的可选 bundle + +Status: implemented + +[English](2026-09-24-schedule-opt-in-optional-bundle.md) | 中文 + +## Problem + +Schedule 会给每个活跃根 Agent 的请求增加四个工具 schema，并在每个符合条件的步骤追加一条持久时钟消息，因此随发行版交付的 Web 组合不能默认挂载它。使用随发行版 Web profile 的人仍需要产品界面上的开关来打开它；profile patch 层或 `--patch` overlay 都是这个人无法触及的配置文件。 + +## Decision + +`packages/bundle/web-app/cordis.patch.yml` 不含 `time-context`、`schedule` 与 `ui-schedule` 中的任何一行，因此随发行版交付的 Web 组合不提供任何定时能力：没有 `schedule_*` 工具、没有 Session 提醒目录、没有自动化任务页面，也没有逐步时钟读数。 + +`@deepseek-ai/dsh-experimental-schedule-bundle`（`packages/experimental/schedule-bundle/`）在其 `cordis.patch.yml` 中插入这三行并依赖它们的包，与其他可选 bundle 插入各自随附的行相同。`packages/boot/app-boot/src/profile.ts` 的 `OPTIONAL_BUNDLES` 列出该包，`apps/cli` 将其声明为运行时依赖，因此每次安装都随包携带且默认关闭。[实验性能力作为可选 bundle 的决策](2026-09-21-experimental-capabilities-as-optional-bundles.zh.md)负责 `OPTIONAL_BUNDLES` 的约定，以及 Web 插件管理页在“官方”分组中渲染的本地化 `icon` 与 `meta.title` / `meta.description` 元数据。 + +启用该 bundle 会插入 `time-context`（每个步骤的时钟读数，包含采样瞬时、附加到当前开放请求的浏览器时区，以及自前一条模型可见消息以来的经过时长）、`schedule`（持久提醒，以及每个活跃根 Agent 上的 `schedule_create`、`schedule_list`、`schedule_update` 与 `schedule_delete`）与 `ui-schedule`（Session 提醒目录与自动化任务页面）。该 bundle 把 `time-context` 与 `schedule` 一起携带，因为提醒请求给出的是挂钟时间目标：采样瞬时正是让模型把“明天九点”这类请求转换成带偏移量的 `at` 值的依据。持久记录、投递与管理操作由 [Schedule 子系统](../../../../docs/subsystems/schedule.zh.md)负责；该 bundle 向其加入这些行的组合由 [Web bundle](../../../../packages/bundle/web-app/README.zh.md) 负责。禁用该 bundle 会恢复随发行版交付的组合，`schedule` 行不存在期间 Host 不再调度；已存储的任务记录保留在 Schedule domain 中。 + +## Alternatives considered + +**默认发布 Schedule。** 那样每个 Web 会话都要在每个请求头中带上四个工具 schema，并在每个符合条件的步骤追加一条持久 user 消息，从不创建提醒的对话也要承担这两项成本。这种安排还让该能力在产品界面上没有关闭开关。 + +**保留一个 `--patch` overlay 文件。** overlay 是启动时的参数，而不是产品界面上的开关，因此使用随发行版 `web` profile 的人无法触及它。通过它的 `insert` 列表重新声明这些条目并不能覆盖它们：`applyEntryPatches` 追加该列表时不对 id 去重，而 Loader 会把组合出的列表按 id 收敛为一个条目、最后一个声明生效，因此该 overlay 会替换 Web Bundle 的条目，而不是给它们设值。 + +**把这三行以 `disabled: true` 留在 Web 组合中，用按 id 定位的 patch 打开。** 这样 bundle 只是给已有的行设值，但插件管理器只列出 bundle 插入的行，因此该 bundle 的页面显示不含任何组件，需要为被覆盖的行另建一条列出路径；而其他可选 bundle 都插入各自的行。某个 profile 若也声明了其中某个 id，处理方式与任何其他 bundle 相同：Loader 保留最后一份声明。 + +**把这三行锁定在 bundle 开关上。** 让插件管理器拒绝逐行开关的 bundle 清单字段，会给插件管理器增加一个只有这个 bundle 使用的概念。该 bundle 的页面像其他所有 bundle 一样为每行提供开关，由 bundle README 说明这三行只能一起工作。 + +## Consequences + +- 默认的 `dsh web` 会话不带 Schedule 工具 schema、Session 提醒目录、自动化任务页面与逐步时钟读数。需要它们的安装可从插件管理页启用该可选 bundle，或把该包列进 profile 的 `dsh.profile.bundles`。 +- 启用后的安装会给每个活跃根 Agent 增加四个工具 schema，并在每个符合条件的步骤追加一条持久时钟消息；该读数对模型可见且持久，因此它与其他 user 消息一样参与回放、压缩，并出现在导出的 Session 日志中。 +- 插件管理页在该 bundle 下列出这三行，显示各自包的 `locale/*.json` 声明的标题、它们的状态，并在 bundle 打开时为每行提供开关；关掉其中一行会让 Schedule 缺少这一部分。 +- 未选中该 bundle 时，按 id 定位这三行之一的 profile 补丁或 `--patch` overlay 匹配不到任何条目，加载器会为它报告 `patch: entry not found` 警告；选中该 bundle 即可取代按 id 打开这些行。 +- 该开关只涉及配置：`src/index.ts` 是空模块，运行时内容由 patch 承载，包本身不拥有可变的运行时状态，因此不发布不变量伴随模块。 diff --git a/.agents/notes/implemented/architecture/2026-09-24-web-default-schedule-composition.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-24-web-default-schedule-composition.i18n.yaml deleted file mode 100644 index fec9a85467..0000000000 --- a/.agents/notes/implemented/architecture/2026-09-24-web-default-schedule-composition.i18n.yaml +++ /dev/null @@ -1,22 +0,0 @@ -# Bilingual-pair consistency record for 2026-09-24-web-default-schedule-composition.md (docs/i18n/README.md): per heading -# section, a hash of its English and Chinese blocks outside code blocks and generated regions. -# After editing either side, bring the other along and re-record with: -# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-24-web-default-schedule-composition.md -/agent-note-schedule-in-the-shipped-web-composition: - en: 39229d7ab6ed433b - zh: 54287471d371a11c -/agent-note-schedule-in-the-shipped-web-composition/problem: - en: 2871fd5ed881c007 - zh: d03c78d402d186da -/agent-note-schedule-in-the-shipped-web-composition/decision: - en: bb19ad12b2ab0ffc - zh: 971f33e95474a36c -/agent-note-schedule-in-the-shipped-web-composition/recorded-sessions: - en: 5539a42052f4ddb7 - zh: 98cc190ae63b4549 -/agent-note-schedule-in-the-shipped-web-composition/alternatives-considered: - en: ca032a407c2ee8cb - zh: 748a4fcf2485a3da -/agent-note-schedule-in-the-shipped-web-composition/consequences: - en: 4f23bda8fda37987 - zh: 9f7c4a3538bd2979 diff --git a/.agents/notes/implemented/architecture/2026-09-25-session-log-otel-byte-limits.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-25-session-log-otel-byte-limits.i18n.yaml new file mode 100644 index 0000000000..15f69188be --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-25-session-log-otel-byte-limits.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-09-25-session-log-otel-byte-limits.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-25-session-log-otel-byte-limits.md +/agent-note-session-log-otlp-strings-and-bounded-requests: + en: 041f7e2b55202ea3 + zh: e01834ae6c9fc7bc +/agent-note-session-log-otlp-strings-and-bounded-requests/problem: + en: 20f659a15fb55352 + zh: 49d39c95da1b8aa5 +/agent-note-session-log-otlp-strings-and-bounded-requests/decision: + en: 0f0866232326658b + zh: aa608d17ba712d8a +/agent-note-session-log-otlp-strings-and-bounded-requests/alternatives-considered: + en: 0dc933b18a1a3573 + zh: 77655740322c4e45 +/agent-note-session-log-otlp-strings-and-bounded-requests/consequences: + en: 3859569c9cdea30c + zh: 517449b8c49807f6 diff --git a/.agents/notes/implemented/architecture/2026-09-25-session-log-otel-byte-limits.md b/.agents/notes/implemented/architecture/2026-09-25-session-log-otel-byte-limits.md new file mode 100644 index 0000000000..57fbe72dc5 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-25-session-log-otel-byte-limits.md @@ -0,0 +1,29 @@ +# Agent Note: Session-log OTLP strings and bounded requests + +Status: implemented + +English | [中文](2026-09-25-session-log-otel-byte-limits.zh.md) + +## Problem + +Session logs contain nested JSON and large tool results. The product collector accepts named records with string content and limits request size; count-only SDK batching cannot bound bytes after UTF-8 encoding and JSON escaping. + +## Decision + +The shared `otel` Cordis plugin owns ordinary-event and Session-log transport implementations. Business adapters inject it and create independent caller-owned channels; their existing UI/RPC entry points retain authorization, redaction, identity, configuration, and bounded shutdown. Mounting the shared service creates no unused queues. Each canonical event becomes `eventName: "session-log"`, with `sessionId` and JSON-stringified event values in `content`; serialization does not preserve JSONL key ordering. Redaction runs before serialization and the copied envelope excludes the payload. + +Session logs use a separate provider and byte/count queue. Each record is measured once with the SDK serializer including a full envelope; the sum conservatively bounds a combined request. Greedy packing avoids full-candidate serialization and recursive re-encoding. Single oversized records receive one diagnostic and do not block later events. One HTTP request owns the transport slot until settlement, even after its watchdog fires; shutdown expiry stops the remaining queue. Scope name/version and explicit transport options remain owned by the backend. + +The [telemetry revival](../feature/2026-07-23-session-telemetry-otel-revival.md) remains authoritative for redaction, capture, and best-effort handoff. This decision replaces its SDK-only queue/batching rule: SDK batch deadlines cannot own an operation split into multiple HTTP requests. The shared Session-log channel schedules complete requests; the SDK still owns transport/retry. Feedback authorization and the separate DeepSeek model-request contribution remain unchanged. + +## Alternatives considered + +**One string for the entire Session.** Rejected because one large Session would exceed the request ceiling even when each event fits. One event per record preserves event identity and permits batching. + +**Truncate oversized records or add client-only fragments.** Rejected because truncation loses content and fragments require a collector reassembly protocol. Explicit rejection retains the one-event-per-record meaning. + +**Count compressed bytes or characters.** Rejected because collector limits can apply after decompression, and characters omit UTF-8 and escaping overhead. Measuring full uncompressed requests gives a conservative bound. + +## Consequences + +Product and Session records never share a request or queue, and neither package imports the other. Conservative per-record envelope accounting can produce smaller batches than exact combined accounting. Queue overflow, oversize rejection, exit, and transport failure can lose data; no durable outbox or acknowledgement is added. Tests cover byte limits, linear measurement, slow-request serialization, metadata, redaction-copy isolation, and feedback-authorized replay. diff --git a/.agents/notes/implemented/architecture/2026-09-25-session-log-otel-byte-limits.zh.md b/.agents/notes/implemented/architecture/2026-09-25-session-log-otel-byte-limits.zh.md new file mode 100644 index 0000000000..f6e8306978 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-25-session-log-otel-byte-limits.zh.md @@ -0,0 +1,29 @@ +# Agent Note: Session 日志的 OTLP 字符串与有界请求 + +Status: implemented + +[English](2026-09-25-session-log-otel-byte-limits.md) | 中文 + +## 问题 + +Session 日志包含嵌套 JSON 和大型工具结果。产品采集端接收带名称和字符串内容的记录，并限制请求大小；仅按数量分批的 SDK 无法约束 UTF-8 编码与 JSON 转义后的字节数。 + +## 决策 + +共享 `otel` Cordis 插件负责普通事件和 Session 日志的传输实现。业务适配器注入它并创建独立、由调用方持有的通道；现有 UI/RPC 入口保留授权、脱敏、身份、配置和有期限的关闭。只挂载共享服务不会创建无用队列。每条规范事件转换为 `eventName: "session-log"`，带有 `sessionId` 和在 `content` 中 JSON 字符串化的事件值；序列化不保留 JSONL 键顺序。脱敏先于序列化，复制的 envelope 不包含 payload。 + +Session 日志使用独立 provider 和字节/条数队列。每条记录使用 SDK 序列化器计量一次，包含完整 envelope；其总和保守约束合并请求大小。顺序组包避免候选批次的完整序列化和递归重复编码。单条超限记录只产生一次诊断，不阻塞后续事件。每个 HTTP 请求在结束前始终占有传输槽位，即使其监测期限已经触发；关闭期限到期后停止剩余队列。scope 名称/版本和显式传输选项仍由后端拥有。 + +[遥测恢复决策](../feature/2026-07-23-session-telemetry-otel-revival.zh.md) 继续约束脱敏、捕获和尽力交接。本决策替代其仅使用 SDK 队列/聚合的规则：SDK 批次期限无法拥有拆成多个 HTTP 请求的操作。共享 Session 日志通道调度完整请求，SDK 仍负责传输和重试。反馈授权和独立的 DeepSeek 模型请求附加路径不变。 + +## 考虑过的替代方案 + +**整个 Session 合为一个字符串。** 拒绝，因为即使每条事件都能放入请求，大型 Session 仍会超过请求上限。每条事件对应一条记录，既保留事件身份又允许分批。 + +**截断超限记录或仅在客户端分片。** 拒绝，因为截断会丢失内容，而分片需要采集端重组协议。显式拒绝保留一条事件对应一条记录的含义。 + +**计算压缩字节数或字符数。** 拒绝，因为采集端限制可能作用于解压后内容，而字符数不包含 UTF-8 和转义开销。计量完整未压缩请求提供保守上限。 + +## 影响 + +产品事件和 Session 记录不共享请求或队列，两个包也不相互导入。保守的逐记录 envelope 计量可能比精确合并计量产生更小批次。队列溢出、超限拒绝、退出和传输失败可能丢失数据；不新增持久 outbox 或确认机制。测试覆盖字节上限、线性计量、慢请求串行调度、元数据、脱敏复制隔离和反馈授权回放。 diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-failed-step-tool-results.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-19-failed-step-tool-results.i18n.yaml new file mode 100644 index 0000000000..727bb883f4 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-19-failed-step-tool-results.i18n.yaml @@ -0,0 +1,19 @@ +# Bilingual-pair consistency record for 2026-09-19-failed-step-tool-results.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-19-failed-step-tool-results.md +/agent-note-record-unanswered-tool-results-before-closing-a-failed-step: + en: 8fd2a50a041b1b18 + zh: 01aed07a6425a322 +/agent-note-record-unanswered-tool-results-before-closing-a-failed-step/problem: + en: 1fa7525f83af9035 + zh: 401ce968e3dd5434 +/agent-note-record-unanswered-tool-results-before-closing-a-failed-step/decision: + en: 3d58367a05183b4a + zh: f9ccc3a7011a6240 +/agent-note-record-unanswered-tool-results-before-closing-a-failed-step/alternatives-considered: + en: 37da4d9c8533b736 + zh: e52a59763ae2b62e +/agent-note-record-unanswered-tool-results-before-closing-a-failed-step/consequences: + en: 1ea72421a98551d8 + zh: c01e02ddac8a3454 diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-failed-step-tool-results.md b/.agents/notes/implemented/bug-fix/2026-09-19-failed-step-tool-results.md new file mode 100644 index 0000000000..80c813598e --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-19-failed-step-tool-results.md @@ -0,0 +1,33 @@ +# Agent Note: Record unanswered tool results before closing a failed step + +Status: implemented + +English | [中文](2026-09-19-failed-step-tool-results.zh.md) + +## Problem + +A committed assistant message can request tools whose scheduler fails before all results are recorded. Closing the step and turn with those calls unanswered makes later model requests invalid for providers that require paired tool calls and results. An error turn is already closed, so crash-tail repair cannot recover it on resume. + +## Decision + +The AgentLoop driver records recovery results for unanswered calls before it closes a failed step, then propagates the original failure. Live step recovery and `interruptedTurnClosers` share incremental pending-call tracking and result construction; the live driver still owns its step and turn events. A step-local observer retains pending identities from committed events without copying session history. The scheduler stops replenishment and drains started dispatches before rejecting, so result recovery cannot race a live dispatch. + +Recovery preserves committed results and follows the assistant's call order. A recorded `tool/call` without a result receives `TOOL_OUTCOME_UNKNOWN`; its text warns against blindly retrying an operation with possible side effects. An assistant request with no call record receives `TOOL_NOT_STARTED`. A call record precedes preparation and does not establish that the tool body ran, so unknown outcomes remain conservative. + +This decision supersedes only the missing-result policy in [parallel tool-call execution](../feature/2026-07-10-parallel-tool-call-execution.md). Its classification, concurrency limit, ordering, and quiescence rules remain applicable. + +## Alternatives considered + +**Leave calls unanswered to avoid inventing tool outcomes.** An unanswered call invalidates later provider requests. An explicit unknown-outcome error records the limit of the available evidence without claiming success, cancellation, or absence of side effects. + +**Repair only when resuming or forking.** The ordinary failure path already records `step/end` and `turn/end`; open-tail repair intentionally preserves closed history. Recovery belongs before those records, while the driver owns the failed step. + +**Repair inside the tool scheduler alone.** Failure can occur after the assistant message is recorded but before scheduling starts. The step driver covers that interval and reuses the existing session repair semantics rather than adding a second implementation of call/result matching. + +**Retry automatically.** A dispatch can have side effects even when its result is missing. The error result supplies retry guidance, while the turn retains the original failure and waits for later work. + +## Consequences + +Later requests, resume, and fork retain a usable call/result history after a live step failure. Recovery appends results; it does not remove assistant messages, replace completed results, execute tools, or convert the failed turn into success. The log uses existing event types and recovery codes, with no format change. + +Already-closed inconsistent historical turns remain unchanged. The live recovery path requires the session to accept the missing result records; it cannot promise recovery from a failed log append. diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-failed-step-tool-results.zh.md b/.agents/notes/implemented/bug-fix/2026-09-19-failed-step-tool-results.zh.md new file mode 100644 index 0000000000..7d69b46a9a --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-19-failed-step-tool-results.zh.md @@ -0,0 +1,33 @@ +# Agent Note: 在关闭失败步骤前补齐工具结果 + +Status: implemented + +[English](2026-09-19-failed-step-tool-results.md) | 中文 + +## 问题 + +已提交的 assistant 消息可能请求多个工具，而调度器在全部结果记录完成之前失败。如果关闭步骤和轮次时仍有调用尚无结果，后续模型请求就不满足要求工具调用与结果配对的提供方。错误轮次已经关闭，因此恢复会话时的崩溃尾部修复无法恢复它。 + +## 决策 + +AgentLoop 驱动器在关闭失败步骤之前，为尚无结果的调用记录恢复结果，随后传播原始失败。实时步骤恢复和 `interruptedTurnClosers` 共享增量的待处理调用跟踪与结果构造；实时驱动器仍拥有自己的步骤和轮次事件。步骤本地观察器从已提交事件中保留待处理调用标识，不复制会话历史。调度器在拒绝之前停止补充池并排空已启动的派发，因此结果恢复不会与运行中的派发竞争。 + +恢复保留已提交的结果，并遵循 assistant 的调用顺序。已有 `tool/call` 记录但尚无结果的调用获得 `TOOL_OUTCOME_UNKNOWN`；其文本警告不要盲目重试可能存在副作用的操作。没有调用记录的 assistant 请求获得 `TOOL_NOT_STARTED`。调用记录先于准备阶段，不能证明工具主体已经运行，因此未知结果保持保守。 + +本决策仅取代[并行工具调用执行](../feature/2026-07-10-parallel-tool-call-execution.zh.md)中的缺失结果策略。其中的分类、并发上限、顺序和完全停稳规则继续适用。 + +## 备选方案 + +**让调用保持无结果，避免虚构工具执行结果。** 尚无结果的调用会使后续提供方请求无效。显式的未知结果错误记录可用证据的局限，而不声称成功、取消或没有副作用。 + +**仅在恢复或 fork 时修复。** 普通失败路径已经记录 `step/end` 和 `turn/end`；开放尾部修复有意保留已关闭历史。恢复应在这些记录之前执行，此时驱动器仍拥有失败步骤。 + +**仅在工具调度器内部修复。** 失败可能发生在 assistant 消息记录之后、调度开始之前。步骤驱动器覆盖这段区间，并复用已有的会话修复语义，避免另行实现调用／结果匹配。 + +**自动重试。** 即使结果缺失，派发也可能产生副作用。错误结果提供重试指引，而轮次保留原始失败并等待后续工作。 + +## 影响 + +实时步骤失败后，后续请求、恢复和 fork 会保留可用的调用／结果历史。恢复追加结果；它不移除 assistant 消息、不替换已完成结果、不执行工具，也不将失败轮次改为成功。日志使用已有事件类型和恢复代码，无需格式变更。 + +此前已关闭的不一致历史轮次保持不变。实时恢复路径要求会话能够接纳缺失结果记录；它不能保证从日志追加失败中恢复。 diff --git a/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.i18n.yaml new file mode 100644 index 0000000000..af95d9cdf7 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.i18n.yaml @@ -0,0 +1,22 @@ +# Bilingual-pair consistency record for 2026-09-27-pwsh-prompt-tail-grace.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.md +/agent-note-a-seen-prompt-marker-keeps-its-own-tail-grace: + en: 5e8c5673a0669d9c + zh: c8442a6186288a2a +/agent-note-a-seen-prompt-marker-keeps-its-own-tail-grace/problem: + en: ac4fb08e3203cee9 + zh: 69fcfcb4f8fc0319 +/agent-note-a-seen-prompt-marker-keeps-its-own-tail-grace/decision: + en: 653c74442decb65a + zh: 46f01c45d48b846b +/agent-note-a-seen-prompt-marker-keeps-its-own-tail-grace/alternatives-considered: + en: 21a9a19b76f42758 + zh: 30a8f5425b59900d +/agent-note-a-seen-prompt-marker-keeps-its-own-tail-grace/consequences: + en: b58904921286a1db + zh: a696c2954d86c04f +/agent-note-a-seen-prompt-marker-keeps-its-own-tail-grace/testing: + en: 78253191eea198fa + zh: 32bdd6807ddc13a0 diff --git a/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.md b/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.md new file mode 100644 index 0000000000..0aa25795c1 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.md @@ -0,0 +1,31 @@ +# Agent Note: A seen prompt marker keeps its own tail grace + +Status: implemented + +English | [中文](2026-09-27-pwsh-prompt-tail-grace.zh.md) + +## Problem + +Windows sessions on the self-hosted lane settled one or two of seven sends on the controlled prompt and charged the silence tier for the rest (2026-09-25/26, issue #2487). The exact readiness evidence is the controlled prompt's printable tail after the OSC `133;D` marker, and the bound on waiting for it was `idleSilenceMs + handoffGraceMs`. A native Windows probe shows the render arrives as two pty chunks: the marker alone, then the five-byte `dsh> ` 2-28 ms later (56 renders), with nothing printable after any prompt and no terminal queries in the output. The marker is written by the shell's own prompt function and the tail by the same render, so a tail that arrives past the bound means the host stalled that delivery, not that the prompt is absent. The session settled `inferred_idle` anyway, and each such send cost the tool call roughly three seconds. + +## Decision + +`dsh-terminal-bash` gains a validated `promptTailGraceMs` configuration field, default `0`. While a send has seen the prompt marker and its printable tail has not arrived, the silence bound becomes `idleSilenceMs + handoffGraceMs + promptTailGraceMs`; every other bound, wait reason, and code path is unchanged. The [persistent PTY readiness design](../feature/2026-07-16-persistent-pty-sessions.md) owns the tier ladder this bound extends. Zero reproduces the previous bound exactly, so an upgrade changes no deployment's behaviour. The persistent pwsh Loader-composition case sets 5000 ms, because the hosts whose stalls the field is for are exactly the ones that run it, and its assertion (at least six `stdin_read` settlements, no `inferred_idle`) then measures the controlled-prompt path instead of the host's delivery timing. `validateConfig` accepts zero for this field — the one numeric bound whose zero is a documented value — and rejects negative or fractional values. + +## Alternatives considered + +**Raise the default instead of adding a field.** Rejected: it trades one fixed cost for another on every host. A marker whose tail never arrives (a stray marker from a child, a broken prompt function) would then fall back that much later everywhere, while the timing that matters differs per deployment. + +**Make the observation sticky: once the exact tail was seen, let later output stand.** Rejected: the tail rule exists to prove the marker was followed by the prompt text rather than by a command's output, and a sticky flag would settle a send while that command is still printing. + +**Wait for the tail up to the absolute `timeoutMs` once a marker was seen.** Rejected: a prompt that never completes its render would hang every send until the tool deadline instead of falling back after a bounded silence, and the send budget belongs to the caller. + +**Detect the stall in the test and retry the send.** Rejected: retries hide which tier settled a send, and the durable fix belongs where the evidence is interpreted, not where it is measured. + +## Consequences + +A deployment whose console renderer stalls keeps those sends on the exact path by setting `promptTailGraceMs`; the default path is bit-for-bit the previous bound, so the negative control — the same delayed tail with the field at zero — still settles `inferred_idle`. The tolerance applies only after a marker was seen: a missing prompt keeps the plain silence bound, so the regression the Loader-composition case pins (a lost prompt must fail) is still caught, and a marker whose tail never arrives falls back one configured interval later. + +## Testing + +`packages/terminal/terminal-bash/tests/session.spec.ts` pins every state with fake timers: with `promptTailGraceMs` set, a marker whose tail arrives after the plain bound stays pending and then settles `stdin_read`; a marker whose tail never arrives falls back to `inferred_idle` at the extended bound; a tail that arrived and was invalidated by later output keeps the plain bound; and with the field at zero the same delayed delivery settles `inferred_idle`. `packages/terminal/terminal-bash/tests/config.spec.ts` accepts zero and rejects negative or fractional values, and rejects a nonzero tolerance shorter than one `pollIntervalMs`. `packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts` carries the end-to-end evidence on native Windows: with every session's prompt tail withheld for four seconds the case passes with the configured tolerance — nine settles, eight `stdin_read` and the `exit` command's `session_exit`, in 33.4 s and 37.5 s — and fails with the tolerance patched to zero, where two sends settle `inferred_idle` with `promptSeen` true, `promptTextSeen` false, an empty tail and `idleFor` 3312-3316 ms. diff --git a/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.zh.md b/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.zh.md new file mode 100644 index 0000000000..feb551d35f --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.zh.md @@ -0,0 +1,31 @@ +# Agent Note: 已看到的提示符标记保留自己的尾部宽限 + +Status: implemented + +[English](2026-09-27-pwsh-prompt-tail-grace.md) | 中文 + +## Problem + +自托管 lane 上的 Windows 会话在七次 send 中只有一到两次按受控提示符结算，其余都要支付静默层（2026-09-25/26，issue #2487）。精确的就绪证据是 OSC `133;D` 标记之后受控提示符的可打印尾部，而等待它的上界是 `idleSilenceMs + handoffGraceMs`。原生 Windows 探测表明该渲染以两个 pty 分块到达：先是标记本身，2–28 毫秒后是 5 字节的 `dsh> `（56 次渲染），任何提示符之后都没有可打印文本，输出中也没有终端查询。标记由 shell 自己的 prompt 函数写出、尾部由同一次渲染写出，因此尾部晚于上界到达意味着宿主机拖慢了这次投递，而不是提示符缺失。会话此前仍会按 `inferred_idle` 结算，每次这样的 send 让工具调用多付约三秒。 + +## Decision + +`dsh-terminal-bash` 新增一个经过校验的 `promptTailGraceMs` 配置字段，默认 `0`。当某次 send 已看到提示符标记而其可打印尾部尚未到达时，静默上界变为 `idleSilenceMs + handoffGraceMs + promptTailGraceMs`；其他上界、等待原因与代码路径均不变。该上界所扩展的层级阶梯由[持久 PTY 就绪设计](../feature/2026-07-16-persistent-pty-sessions.zh.md)拥有。零精确复现此前的上界，因此升级不改变任何部署的行为。持久 pwsh 的 Loader 组合用例设置 5000 毫秒，因为需要该字段的宿主机正是运行该用例的那些，而其断言（至少六次 `stdin_read` 结算、不含 `inferred_idle`）由此度量受控提示符路径，而不是宿主机的投递时序。`validateConfig` 允许该字段取零——这是唯一一个零为文档化取值的数值上界——并拒绝负数与小数。 + +## Alternatives considered + +**不加字段，直接提高默认值。** 不采纳：那是把一种固定成本换成另一种，且对所有宿主机生效。尾部永不到达的标记（子进程打印的杂散标记、损坏的 prompt 函数）会在所有地方都多等那么久，而真正重要的时序因部署而异。 + +**让观测变为粘性：一旦看到精确尾部，后续输出不再使其失效。** 不采纳：尾部规则的存在就是为了证明标记之后跟着的是提示符文本而不是命令输出；粘性标志会在命令仍在打印时结算该 send。 + +**看到标记后一直等到绝对 `timeoutMs`。** 不采纳：渲染永不完成的提示符会让每次 send 都挂到工具截止时间，而不是在有界静默后回退，而 send 预算属于调用方。 + +**在测试里检测停摆并重试该 send。** 不采纳：重试会掩盖究竟是哪一层结算的，而持久的修复属于解释证据的地方，而不是测量证据的地方。 + +## Consequences + +控制台渲染器会停摆的部署通过设置 `promptTailGraceMs` 让这些 send 留在精确路径上；默认路径与此前的上界逐位一致，因此负控——同样的尾部延迟、字段为零——仍然按 `inferred_idle` 结算。该宽限只在看到标记之后生效：提示符缺失时保持普通静默上界，所以 Loader 组合用例所固定的回归（提示符丢失必须失败）仍会被抓住，而尾部永不到达的标记只会晚一个配置区间回退。 + +## Testing + +`packages/terminal/terminal-bash/tests/session.spec.ts` 用假定时器固定每一种状态：设置 `promptTailGraceMs` 时，尾部晚于普通上界到达的标记保持挂起，随后按 `stdin_read` 结算；尾部始终不到时在扩展上界处回落到 `inferred_idle`；尾部已到达但被后续输出失效时保持普通上界；字段为零时，同样的延迟投递按 `inferred_idle` 结算。`packages/terminal/terminal-bash/tests/config.spec.ts` 接受零、拒绝负数或小数，并拒绝非零但短于一个 `pollIntervalMs` 的宽限。`packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts` 承载原生 Windows 上的端到端证据：把每个 session 的提示符尾部扣留四秒时，配置了该宽限后用例通过——九次结算、八次 `stdin_read` 加 `exit` 命令的 `session_exit`，耗时 33.4 秒与 37.5 秒；把该宽限改为零后同一停摆失败，其中两次 send 以 `inferred_idle` 结算，`promptSeen` 为 true、`promptTextSeen` 为 false、尾部为空且 `idleFor` 为 3312–3316 毫秒。 diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml index 4b82a34a31..5867da4d43 100644 --- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml @@ -12,8 +12,8 @@ en: 532bb7268d9b93ce zh: ad47162233222ab0 /agent-note-parallel-tool-call-execution-by-per-call-safety/scheduling-and-ordering: - en: f0906d03fef98e7b - zh: f9e43c4c832c9a05 + en: a485c530ea4366de + zh: 6f9915d726de9ac7 /agent-note-parallel-tool-call-execution-by-per-call-safety/safety-contract: en: 16c4ee08b65ead23 zh: df80d6e49982615b @@ -24,8 +24,8 @@ en: eb5a6aa84980f0ab zh: eed2680a160e8ed2 /agent-note-parallel-tool-call-execution-by-per-call-safety/alternatives-considered: - en: 44f8fb5851ba4e39 - zh: 4d75c937ac5277f7 + en: 17becc038bb7df7c + zh: 673d9a9bdfa39edf /agent-note-parallel-tool-call-execution-by-per-call-safety/consequences: - en: 5e5b2a1c7d850f83 - zh: b63311f28eb69366 + en: a5508057bc03f4f6 + zh: 96b46c59402474c3 diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md index d5d26e03a2..004d725bfd 100644 --- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md +++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md @@ -46,7 +46,7 @@ Only dispatch and the tool body overlap. `tools/pre-execute` and `tools/post-exe Each started call appends `tool/call` immediately before its pre-execute gate. Completed dispatches occupy model-order slots, and a commit cursor appends `tool/result` and collects `additionalContexts` only when the next slot is ready. Live surfaces may show several pending calls, but results and post-tool context remain model-ordered. -An abort before a group starts records no calls from that group. An abort during a group stops replenishment, waits for already-started calls, commits their results in order, drains accepted batch context after those results, and then ends the step through the existing abort path. Calls that never start have no audit event. An unexpected scheduler failure stops new dispatches, waits for every already-started dispatch to settle, and rethrows the first failure. Because that failure is terminal internal state rather than a tool outcome, the loop does not invent tool results for rejected or uncommitted calls. +An abort stops replenishment, waits for already-started calls, commits their results in order, drains accepted batch context after those results, and records synthetic aborted call/result pairs for undispatched calls. An unexpected scheduler failure stops new dispatches, waits for every already-started dispatch to settle, and rethrows the first failure. The driver records missing results before closing the failed step under the [failed-step recovery decision](../bug-fix/2026-09-19-failed-step-tool-results.md). PTC mode remains outside this scheduler because the model emits one native `run_code` call. `run_code` and its internal dispatch queue remain serial; native sibling calls in `mode: 'both'` use the normal scheduler. @@ -84,7 +84,7 @@ Snapshot coverage pins the visible multi-call transcript: pending calls may over **Expose staged methods or a scheduling waterfall.** Public `prepare` / `dispatch` / `finalize` methods or a `tools/execution-mode` event add extension surface before another consumer needs it. The loop uses an internal scheduler view, while `executionMode(exec)` leaves an insertion point for a policy hook. -**Convert scheduler failures into tool results.** AgentLoop cannot determine whether a rejected dispatch invoked the tool body; ToolRuntime owns body-invocation state and typed tool outcomes. Internal scheduler failures therefore remain terminal instead of being reclassified as `ABORTED` results. +**Convert scheduler failures into ordinary tool results.** AgentLoop cannot determine whether a rejected dispatch invoked the tool body; ToolRuntime owns body-invocation state and typed tool outcomes. Internal scheduler failures remain terminal instead of being reclassified as `ABORTED` results. Explicit recovery results preserve this uncertainty without leaving unanswered calls. **Start calls while the model streams.** This may reduce latency further but changes assistant-message authority, replay, and call/result pairing. The scheduler starts only after the assistant message is complete. @@ -96,7 +96,7 @@ Snapshot coverage pins the visible multi-call transcript: pending calls may over The design is fail-closed and simple for tool authors, but it cannot exploit concurrency whose safety depends on comparing siblings. A tool that opts in too broadly can expose latent shared-state races. -Parallel calls may begin in cases where serial execution would have aborted before reaching them. The scheduler therefore records only started calls, drains them on abort, and never starts replacements after cancellation. +Parallel calls may begin in cases where serial execution would have aborted before reaching them. The scheduler drains them on abort and never starts replacements after cancellation; undispatched calls receive synthetic aborted call/result pairs. Ordered commits may hold a fast result behind a slow earlier sibling. This preserves replay and model-history order while live surfaces still show pending progress. @@ -104,4 +104,4 @@ Concurrent external calls can compete for quota or process capacity. Providers o Tool registration is a scheduling boundary. Registry mutations affect not-yet-started calls because the scheduler reclassifies after each barrier and before every pool replenishment. Already-started calls retain the scheduling decision under which they entered the pool. -A terminal scheduler failure may leave recorded calls without results before the failed step closes. Waiting for live dispatches preserves quiescence without misreporting those internal failures as tool outcomes. +A terminal scheduler failure reaches step recovery only after live dispatches settle. Recovery reports uncommitted outcomes as unknown, preserving quiescence and the original failure while keeping later model history usable. diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md index 707428985c..e78f56e07c 100644 --- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md +++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md @@ -46,7 +46,7 @@ Status: implemented 每个已启动的调用都会在进入 pre-execute 门禁之前立即追加 `tool/call`。已完成的派发占据模型顺序的槽位；提交游标只有在下一个槽位就绪时，才会追加 `tool/result` 并收集 `additionalContexts`。实时界面可以显示多个待处理调用，但结果和工具执行后的上下文仍按模型顺序排列。 -如果在一组启动前中止，系统不会记录该组的任何调用。如果在一组执行期间中止，系统会停止补充池，等待已启动的调用，按顺序提交其结果，在这些结果之后排空已接受的批次上下文，然后通过现有中止路径结束该步骤。从未启动的调用没有审计事件。调度器发生意外故障时，会停止新的派发，等待每项已启动的派发结算，并重新抛出第一个故障。由于该故障是内部终态，而非工具结果，循环不会为被拒绝或未提交的调用虚构工具结果。 +中止会停止补充池，等待已启动的调用，按顺序提交其结果，在这些结果之后排空已接受的批次上下文，并为未派发的调用记录合成的中止调用／结果对。调度器发生意外故障时，会停止新的派发，等待每项已启动的派发结算，并重新抛出第一个故障。驱动器按照[失败步骤恢复决策](../bug-fix/2026-09-19-failed-step-tool-results.zh.md)，在关闭失败步骤之前记录缺失结果。 PTC mode 仍不使用此调度器，因为模型只会发出一个原生 `run_code` 调用。`run_code` 及其内部派发队列仍按串行方式执行；`mode: 'both'` 中的原生并列调用使用常规调度器。 @@ -84,7 +84,7 @@ PTC mode 仍不使用此调度器，因为模型只会发出一个原生 `run_co **公开分阶段方法或调度 waterfall（瀑布式事件）。** 公开的 `prepare` / `dispatch` / `finalize` 方法或 `tools/execution-mode` 事件，会在另一个消费方需要它之前扩大扩展接口。循环使用内部调度器视图，而 `executionMode(exec)` 为策略钩子保留了插入点。 -**将调度器故障转换为工具结果。** AgentLoop 无法判断被拒绝的派发是否已调用工具主体；ToolRuntime 负责工具主体调用状态和类型化工具结果。因此，内部调度器故障保持为终态，而不会被重新分类为 `ABORTED` 结果。 +**将调度器故障转换为普通工具结果。** AgentLoop 无法判断被拒绝的派发是否已调用工具主体；ToolRuntime 负责工具主体调用状态和类型化工具结果。内部调度器故障保持为终态，而不会被重新分类为 `ABORTED` 结果。显式恢复结果保留这种不确定性，同时避免留下尚无结果的调用。 **在模型流式输出时启动调用。** 这可能进一步降低延迟，但会改变 assistant 消息的权威性、回放以及调用/结果配对。调度器只在 assistant 消息完成后才启动。 @@ -96,7 +96,7 @@ PTC mode 仍不使用此调度器，因为模型只会发出一个原生 `run_co 该设计遵循安全侧原则，对工具作者而言也很简单，但无法利用必须通过比较并列调用才能确认安全的并发性。工具过于宽泛地选择并行，可能暴露潜在的共享状态竞态。 -在某些情形下，并行调用会先行启动，而串行执行原本会在轮到这些调用之前中止。因此，调度器只记录已启动的调用，在中止时将其排空，且取消后绝不启动替换调用。 +在某些情形下，并行调用会先行启动，而串行执行原本会在轮到这些调用之前中止。调度器在中止时将其排空，且取消后绝不启动替换调用；未派发的调用获得合成的中止调用／结果对。 有序提交可能会让快速结果等待较慢的早期并列调用。这保留了回放和模型历史顺序，同时实时界面仍可显示待处理进度。 @@ -104,4 +104,4 @@ PTC mode 仍不使用此调度器，因为模型只会发出一个原生 `run_co 工具注册是调度边界。调度器会在每个屏障之后以及每次补充池之前重新分类，因此注册表变更会影响尚未启动的调用。已启动的调用保留它们进入池时所依据的调度决策。 -终态调度器故障可能会在故障步骤关闭前留下已记录但没有结果的调用。等待仍在运行的派发可确保完全停稳，而不会将这些内部故障误报为工具结果。 +终态调度器故障只有在运行中的派发结算后才会进入步骤恢复。恢复将未提交的执行结果报告为未知，保留完全停稳与原始失败，同时让后续模型历史保持可用。 diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml index ac9be41f4d..6f55ce4f48 100644 --- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml @@ -24,8 +24,8 @@ en: b92715f36550c728 zh: e18d7e0e2363347a /agent-note-persistent-pty-sessions/decision/local-readiness-detection: - en: cd8b4032a624c277 - zh: 47f0d8c15f1c9cad + en: 8f36f06869bd5367 + zh: f3560477a8965cbe /agent-note-persistent-pty-sessions/decision/model-visible-output-and-durability: en: 1b504ab41b47216d zh: 8fb3d360b3a4e6a1 diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md index d62587ced7..b309e1b1f9 100644 --- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md +++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md @@ -72,13 +72,13 @@ With `run_in_background: true`, `dsh-tool-terminal` registers the in-flight send ### Local readiness detection -The local backend first recognizes a private OSC prompt marker emitted by its controlled bash startup, then requires the printable tail after the latest marker to exactly equal the controlled `PS1` before declaring prompt readiness and runs three bounded fallback tiers. Carrying that tail across data callbacks covers delivery where the marker and prompt arrive separately; requiring the exact tail rejects a delayed earlier prompt once echoed input or output follows it, so it cannot settle the current send. The marker is removed before output reaches the model and avoids a fixed silence delay for ordinary shell commands on both platforms. Unpublished startup does not accept zero-output silence as readiness; timeout rejects the spawn. If caller cancellation wins during startup, the backend closes the private session and propagates the exact `AbortSignal.reason`; a foreground PGID that is not observable yet cannot replace cancellation with a lookup error. All timings are validated config fields: `pollIntervalMs`, `exactProbeAfterMs`, `idleSilenceMs`, `handoffGraceMs`, and `timeoutMs`. +The local backend first recognizes a private OSC prompt marker emitted by its controlled bash startup, then requires the printable tail after the latest marker to exactly equal the controlled `PS1` before declaring prompt readiness and runs three bounded fallback tiers. Carrying that tail across data callbacks covers delivery where the marker and prompt arrive separately; requiring the exact tail rejects a delayed earlier prompt once echoed input or output follows it, so it cannot settle the current send. The marker is removed before output reaches the model and avoids a fixed silence delay for ordinary shell commands on both platforms. Unpublished startup does not accept zero-output silence as readiness; timeout rejects the spawn. If caller cancellation wins during startup, the backend closes the private session and propagates the exact `AbortSignal.reason`; a foreground PGID that is not observable yet cannot replace cancellation with a lookup error. All timings are validated config fields: `pollIntervalMs`, `exactProbeAfterMs`, `idleSilenceMs`, `handoffGraceMs`, `promptTailGraceMs`, and `timeoutMs`. On Linux, the inspector reads the shell's terminal foreground PGID from `/proc//stat`, enumerates every process and thread in that process group, and probes their current syscalls. A positive Tier 1 result requires an observed stdin wait: direct `read(0)`, a permitted read of a `select`/`pselect6` or `poll`/`ppoll` argument containing fd 0, or an epoll interest list containing fd 0. The waiting thread's `/proc//task//fd/0` must identify the shell's controlling terminal device, so a thread-local fd table cannot substitute its leader's terminal descriptor and a pipeline reader blocked on its pipe remains a running command. Direct PTY descriptors use their device number; `/dev/tty` uses the owning process's `tty_nr` because `stat` reports the alias device rather than the selected PTY. A wait already present before terminal input is not post-write readiness: the same PGID must be observed outside that wait before re-entering it, while a changed foreground PGID is new evidence. Unreadable process memory and unrecognized syscalls are misses, never positive guesses. A host policy that denies `/proc//task//syscall`, including hardened ptrace policy, likewise skips Tier 1 and preserves the bounded Tier 2 idle inference; process sleep state never substitutes for inaccessible syscall evidence. Architecture tables contain only syscall numbers defined by the corresponding Linux UAPI; the inspector admits the runtime architecture, then checks every supported kernel ABI because `/proc` can report a different ABI under user-mode emulation. Unsupported runtime architectures skip Tier 1. On macOS there is no exact syscall tier. Output silence returns `inferred_idle` for any foreground process group, including Python and `gdb`; `ps`-derived terminal PGID is used for signaling, not as proof that only the shell can be idle. Pure process-inspector logic is injectable and unit-tested on Linux, while a macOS CI job exercises the real PTY and process-table path. -Tier 2 returns `inferred_idle` after `idleSilenceMs` without output. A sleeping or network-blocked command can therefore look ready. When a prompt marker was already seen, Tier 2 waits a further `handoffGraceMs` so a bash foreground handoff that lands on the silence boundary still settles as the exact `stdin_read` attribution instead of the weaker inference; the grace is a deployment-owned config field validated to cover at least one `pollIntervalMs`, because a grace shorter than the poll period cannot contain a single readiness poll and so cannot change any outcome. It bounds only sends that saw a marker, so its cost is the interactive return latency of that one case rather than every send. Tier 3 returns `timeout` after `timeoutMs` so a foreground tool call cannot hold the agent indefinitely. The result preserves the distinction; callers may wait through `ctx.jobs`, signal the foreground group, or inspect from another session. +Tier 2 returns `inferred_idle` after `idleSilenceMs` without output. A sleeping or network-blocked command can therefore look ready. When a prompt marker was already seen, Tier 2 waits a further `handoffGraceMs` so a bash foreground handoff that lands on the silence boundary still settles as the exact `stdin_read` attribution instead of the weaker inference; the grace is a deployment-owned config field validated to cover at least one `pollIntervalMs`, because a grace shorter than the poll period cannot contain a single readiness poll and so cannot change any outcome. A marker whose printable tail has not arrived yet adds `promptTailGraceMs` to that bound, because the marker and its tail are written by the same prompt render and a contended host delays only the tail; the [prompt tail grace decision](../bug-fix/2026-09-27-pwsh-prompt-tail-grace.md) owns the field, and it applies only while the tail can still complete. It bounds only sends that saw a marker, so its cost is the interactive return latency of that one case rather than every send. Tier 3 returns `timeout` after `timeoutMs` so a foreground tool call cannot hold the agent indefinitely. The result preserves the distinction; callers may wait through `ctx.jobs`, signal the foreground group, or inspect from another session. Once a send settles under any tier, `TerminalSendOperation.append` stops accepting output, so later child output no longer reaches that settled operation; it still reaches the scrollback, and any send that is active when it arrives. A test that waits for a marker on the operation it started must therefore set `idleSilenceMs` and `timeoutMs` above the child's own startup latency; interpreter startup on a loaded macOS runner otherwise ends the send before the marker is printed. diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md index a26c3ed852..46257a6835 100644 --- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md +++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md @@ -72,13 +72,13 @@ UI 渲染约定精确且不携带位置信息。`terminal_send` 只为前台发 ### 本地就绪检测 -本地后端先识别受控 bash 启动时发出的私有 OSC prompt marker，并且只有在最近一个 marker 后的可打印尾部与受控 `PS1` 完全相等时才声明 prompt 就绪；除此之外，它还运行 3 个有界 fallback 层级。在 data callback 之间保留该尾部，可以适配 marker 与 prompt 被分开交付的情况；如果回显的输入或输出跟在延迟到达的先前 prompt 之后，要求尾部完全相等会拒绝该 prompt，使其无法完成当前 send。marker 在输出到达模型前被移除，使两个平台上的普通 shell 命令都无需固定等待静默阈值。尚未发布的 startup 不会把零输出静默视为就绪；timeout 会拒绝 spawn。若调用方取消在 startup 期间胜出，后端会关闭私有会话并原样抛出 `AbortSignal.reason`；尚不可观察的前台 PGID 不会再用查找错误覆盖取消原因。所有时间参数都是经校验的配置字段：`pollIntervalMs`、`exactProbeAfterMs`、`idleSilenceMs`、`handoffGraceMs` 和 `timeoutMs`。 +本地后端先识别受控 bash 启动时发出的私有 OSC prompt marker，并且只有在最近一个 marker 后的可打印尾部与受控 `PS1` 完全相等时才声明 prompt 就绪；除此之外，它还运行 3 个有界 fallback 层级。在 data callback 之间保留该尾部，可以适配 marker 与 prompt 被分开交付的情况；如果回显的输入或输出跟在延迟到达的先前 prompt 之后，要求尾部完全相等会拒绝该 prompt，使其无法完成当前 send。marker 在输出到达模型前被移除，使两个平台上的普通 shell 命令都无需固定等待静默阈值。尚未发布的 startup 不会把零输出静默视为就绪；timeout 会拒绝 spawn。若调用方取消在 startup 期间胜出，后端会关闭私有会话并原样抛出 `AbortSignal.reason`；尚不可观察的前台 PGID 不会再用查找错误覆盖取消原因。所有时间参数都是经校验的配置字段：`pollIntervalMs`、`exactProbeAfterMs`、`idleSilenceMs`、`handoffGraceMs`、`promptTailGraceMs` 和 `timeoutMs`。 在 Linux 上，检查器从 `/proc//stat` 读取 shell 的终端前台 PGID，枚举该进程组中的每个进程与线程，并检查它们当前的 syscall。Tier 1 只有观察到 stdin 等待才返回正结果：直接 `read(0)`、获准读取且含 fd 0 的 `select`/`pselect6` 或 `poll`/`ppoll` 参数，或者含 fd 0 的 epoll interest list。等待线程的 `/proc//task//fd/0` 还必须标识 shell 的控制终端设备，因此线程本地 fd 表无法用 leader 的终端描述符冒充自身 fd，阻塞于管道的流水线读取端仍属于正在运行的命令。直接 PTY 描述符使用其设备号；`/dev/tty` 则使用所属进程的 `tty_nr`，因为 `stat` 报告的是别名设备而非选定的 PTY。终端输入前就已存在的等待并不代表写入后就绪：必须先观察到同一 PGID 脱离该等待，之后再次进入等待才能使该次 send 完成；前台 PGID 发生变化则构成新的证据。无法读取的进程内存和未识别的 syscall 都是 miss，绝不作为正向猜测。宿主策略（包括加固的 ptrace 策略）若拒绝读取 `/proc//task//syscall`，同样会跳过 Tier 1 并保留有界的 Tier 2 idle 推断；进程休眠状态绝不会代替不可访问的 syscall 证据。架构表只包含对应 Linux UAPI 定义的 syscall number；检查器先准入运行时架构，再检查每个受支持的内核 ABI，因为在用户态模拟下，`/proc` 可能报告不同的 ABI。不受支持的运行时架构会跳过 Tier 1。 macOS 没有精确 syscall 层。任何前台进程组输出静默都会返回 `inferred_idle`，包括 Python 和 `gdb`；从 `ps` 推导的终端 PGID 只用于发送信号，不作为「只有 shell 才能 idle」的证明。纯进程检查逻辑可注入，并在 Linux 上经过单元测试，同时由 macOS CI job 驱动真实 PTY 和进程表路径。 -Tier 2 在持续 `idleSilenceMs` 没有输出后返回 `inferred_idle`，因此 sleep 或网络阻塞的命令可能看似 ready。如果此前已经见过 prompt marker，Tier 2 会再等待 `handoffGraceMs`，使恰好落在静默边界上的 bash 前台交接仍然以精确的 `stdin_read` 归因结束，而不是退到较弱的推断；该宽限是由部署方拥有的配置字段，并被校验为至少覆盖一个 `pollIntervalMs`——短于轮询周期的宽限装不下一次就绪轮询，因此不可能改变任何结果。它只约束见过 marker 的 send，代价是这一种情况的交互返回延迟，而不是每一次 send。Tier 3 在 `timeoutMs` 后返回 `timeout`，避免前台工具调用无限占住 agent。结果保留这些区别；调用方可以通过 `ctx.jobs` 等待、向前台组发信号，或从另一个会话排查。 +Tier 2 在持续 `idleSilenceMs` 没有输出后返回 `inferred_idle`，因此 sleep 或网络阻塞的命令可能看似 ready。如果此前已经见过 prompt marker，Tier 2 会再等待 `handoffGraceMs`，使恰好落在静默边界上的 bash 前台交接仍然以精确的 `stdin_read` 归因结束，而不是退到较弱的推断；该宽限是由部署方拥有的配置字段，并被校验为至少覆盖一个 `pollIntervalMs`——短于轮询周期的宽限装不下一次就绪轮询，因此不可能改变任何结果。若已见 marker 而其可打印尾部尚未到达，该上界还会加上 `promptTailGraceMs`：marker 与尾部由同一次提示符渲染写出，负载高的宿主机只会拖慢尾部；该字段由[提示符尾部宽限决策](../bug-fix/2026-09-27-pwsh-prompt-tail-grace.zh.md)拥有，且只在尾部仍可能补齐时生效。它只约束见过 marker 的 send，代价是这一种情况的交互返回延迟，而不是每一次 send。Tier 3 在 `timeoutMs` 后返回 `timeout`，避免前台工具调用无限占住 agent。结果保留这些区别；调用方可以通过 `ctx.jobs` 等待、向前台组发信号，或从另一个会话排查。 一次 send 在任一层级 settle 之后，`TerminalSendOperation.append` 就不再接受输出，此后子进程的输出不会再进入那个已 settle 的 operation；它仍然会进入 scrollback，以及此时恰好处于活跃状态的任何 send。因此，等待自己所启动的 operation 上出现标记的测试，必须把 `idleSilenceMs` 与 `timeoutMs` 设得高于子进程自身的启动耗时；否则在负载较高的 macOS runner 上，解释器启动会在标记打印之前就结束这次 send。 diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml index 8f2fe2b211..a06d830891 100644 --- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml @@ -9,8 +9,8 @@ en: d3383b495424d118 zh: 4e6ffc8ebfa7f741 /agent-note-session-telemetry-seam-with-mandatory-redaction-and-the-otel-backend/decision: - en: 85b950a67315023c - zh: cb4c08338c30b226 + en: 739b871ae583dcbf + zh: d17053e3b0a35942 /agent-note-session-telemetry-seam-with-mandatory-redaction-and-the-otel-backend/alternatives-considered: en: 01838eefca2bc117 zh: fc71f5449d095b27 diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md index dc52ee87ef..b3b50d4be5 100644 --- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md +++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md @@ -16,6 +16,8 @@ Every deployment that wants harness sessions in an observability stack must hand - **The `session-telemetry/record` waterfall** — the delta over the branch version and the seam's redaction extension point. Every record passes it before reaching any backend; the seam ships NO rules of its own — the innermost `next()` is a pass-through, deployments mount their rules as listeners (stacking by transforming `next()`'s return value), and a throwing rule withholds the record fail-closed. Redaction applies to the exported copy only; the canonical log is never rewritten. - **`@deepseek-ai/dsh-session-telemetry-otel`** — the reference backend: OTel JS SDK log pipeline (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter), configured verbatim through `exporter`/`processor` passthroughs. `DISABLED` is the plugin default and constructs no transport. `FEEDBACK_ONLY` requires `exporter.url`; the [explicit-feedback policy](../architecture/2026-09-05-nonofficial-feedback-otel.md) requires a new submission for every bounded capture, for all providers. [Buffer-free feedback replay](../../archived/simplification/2026-08-06-buffer-free-feedback-telemetry.md) avoids a second in-memory copy of the session prefix. +The [Session-log request limits](../architecture/2026-09-25-session-log-otel-byte-limits.md) supersede the SDK-only batching rule below for the OTel Session sender; capture, redaction, and handoff rationale remain applicable. + The boundary axiom holds: the harness's aspect ends at `emit()`. Batching, retry, queueing, and loss policy are the reporting SDK's, configured through passthroughs. Delivery is best-effort: a crash can lose queued records. Backend retry or losing the same live object's module-scope cursor can duplicate lifecycle-local rows, so receivers deduplicate on `(session.id, session.format_version, event.seq)`. ## Alternatives considered diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md index f647ea2896..349cd47e59 100644 --- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md +++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md @@ -16,6 +16,8 @@ Status: implemented - **`session-telemetry/record` waterfall（瀑布式事件）** —— 相对分支版本的增量，也是该 seam 的脱敏扩展点。每条记录抵达任何后端前必经此处；seam 自身不带任何规则——最内层 `next()` 原样透传，部署方以监听器挂载自己的规则（通过变换 `next()` 的返回值堆叠），抛异常的规则将该记录 fail-closed 扣下。脱敏只作用于导出副本；canonical log 永不改写。 - **`@deepseek-ai/dsh-session-telemetry-otel`** —— 参考后端：OTel JS SDK 日志流水线（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter），经 `exporter`/`processor` passthrough 原样配置。`DISABLED` 是插件默认值，且不构造任何传输。`FEEDBACK_ONLY` 要求 `exporter.url`；[显式反馈策略](../architecture/2026-09-05-nonofficial-feedback-otel.zh.md)要求每次有界捕获都由新提交触发，适用于所有提供方。[无缓冲反馈回放](../../archived/simplification/2026-08-06-buffer-free-feedback-telemetry.md)避免在内存中创建会话前缀的第二份副本。 +[Session 日志请求上限](../architecture/2026-09-25-session-log-otel-byte-limits.zh.md) 在 OTel Session 发送器中替代下述仅由 SDK 分批的规则；采集、脱敏和交接的理由仍然适用。 + 边界公理保持不变：harness 的职责止于 `emit()`。批处理、重试、排队与丢失策略属于 reporting SDK，并经 passthrough 配置。投递是尽力而为：崩溃可能丢失已排队记录。后端重试或丢失同一 live 对象的模块作用域游标可能重复生命周期本地 row，因此接收端基于 `(session.id, session.format_version, event.seq)` 去重。 ## 考虑过的替代方案 diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml index 770368862d..e811b85577 100644 --- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml @@ -12,8 +12,8 @@ en: 8892eea7f62d45ed zh: 18f64966ff53e38b /agent-note-web-subagent-catalog-and-human-continuation/design-context: - en: 3c44fc5af90bc807 - zh: 478538d028a52858 + en: da3858c86cf685ff + zh: b13ee4f45e3dff7d /agent-note-web-subagent-catalog-and-human-continuation/product-contract: en: 2060d607d1cd1ef3 zh: e7100887358625c4 diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md index 3798a5a2e5..ba72e31d88 100644 --- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md +++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md @@ -28,7 +28,7 @@ This decision covers Web discovery, transcript viewing, and parent-authorized hu ## Design context -The Figma [subagent list](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=383-14602&p=f), [hierarchical expansion](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=383-15917&p=f), and [child conversation](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=388-18584&p=f) frames are non-normative interaction and visual references. This note owns lifecycle, wire, and failure semantics. +The Figma subagent list, hierarchical expansion, and child conversation frames are non-normative interaction and visual references. This note owns lifecycle, wire, and failure semantics. | Design intent | Shipped contract | | --- | --- | diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md index 4531528dd2..a3841b05fb 100644 --- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md +++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md @@ -28,7 +28,7 @@ Web 产品通过页头的当前 title 谱系区域公开选中会话中由会话 ## 设计上下文 -Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=383-14602&p=f)、[层级展开](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=383-15917&p=f)与 [child 对话](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=388-18584&p=f)画框是非规范性的交互与视觉参考。本记录负责生命周期、协议与失败语义。 +Figma 中的 subagent 列表、层级展开与 child 对话画框是非规范性的交互与视觉参考。本记录负责生命周期、协议与失败语义。 | 设计意图 | 已交付约定 | | --- | --- | diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml index 42a4a26dc0..c161ba26e8 100644 --- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml +++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml @@ -9,11 +9,11 @@ en: 4fb1c27a631b32d3 zh: 9dbe9a4b9aadfca9 /agent-note-serial-cross-platform-ci-reference/decision: - en: f547014d316c1385 - zh: f13b09a4a778adaa + en: 7c58d88d4c002f19 + zh: a3b961be49f2a96b /agent-note-serial-cross-platform-ci-reference/alternatives-considered: - en: bc72a1e194e3b0e2 - zh: 9a92cbac88adc7a7 + en: 3610152c5c4e93af + zh: f4c09d327716f750 /agent-note-serial-cross-platform-ci-reference/consequences: en: 7042125ce6a209d4 zh: ef2be4fa8a4d6320 diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md index 24022fea27..ca2b47c1d0 100644 --- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md +++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md @@ -24,7 +24,7 @@ Platform ownership remains explicit inside that complete aggregate. `terminal-ba The macOS reference runs the ordinary Vitest project in forked processes. Node 24 on macOS arm64 has aborted in its CJS lexer from a worker thread; the process boundary contains that external runtime failure without removing any test from the aggregate, while Linux and Windows retain the lower-overhead thread pool. Repository-owned races are fixed at their observation boundaries: dev bundle polling stages each candidate table, graph, and watch-baseline map before publishing a rescan, and a missing bundle remains dirty until a successful content hash. PTY readiness retains a prompt candidate while polling checks foreground ownership; the ordinary silence bound covers inherited markers from interactive children. Real PTY fixtures assemble synchronization tokens at runtime so the interactive shell's input echo cannot satisfy a child-readiness wait. The live-link package-manager e2e preserves the workflow-prepared Corepack home and pnpm metadata/store caches while isolating the other managers' mutable caches, so it does not discard reusable package-manager state before the install. -The standalone [Sandbox](../../../../.github/workflows/sandbox.yml) workflow belongs to the reference side of the same split. Its bwrap, Landlock x64/arm64, and Seatbelt real-kernel matrix runs only after a push to `master`. Those four jobs are diagnostic: they are not branch-protection requirements and do not feed `all checks passed` across workflow files. Pull-request CI still checks sandbox source through its ordinary unit and coverage inventory; the host-kernel and packed-install proofs report after merge. +The standalone [Sandbox](../../../../.github/workflows/sandbox.yml) workflow belongs to the reference side of the same split. Its bwrap, Landlock x64/arm64, and Seatbelt real-kernel matrix runs only after a push to `master`. Those four jobs are diagnostic: they are not branch-protection requirements and do not feed `all checks passed` across workflow files. A fifth job, `unit-darwin`, runs the complete unit suite on `macos-latest` under its own budget, so the darwin-only unit expectations keep a platform oracle without holding the Seatbelt leg to the unit suite's duration. Pull-request CI still checks sandbox source through its ordinary unit and coverage inventory; the host-kernel and packed-install proofs report after merge. Master reference jobs are diagnostic and do not participate in the pull request's required `all checks passed` result. The ci-master and Sandbox workflows keep their cross-platform references on master pushes. Performance is evaluated from completed hosted-job timestamps and reported as a measurement; it is not encoded as a `timeout-minutes` value. @@ -35,7 +35,7 @@ The active serial references run on the self-hosted `vm-backup` (`serial / linux - **Set each timeout equal to its latency target** - rejected because scheduling variance would cancel correct work and suppress the evidence needed to diagnose a regression. - **Trust only the concurrent primary inventory** - rejected because scheduling and validation share implementation assumptions; a serial aggregate is an independent completeness check. - **Run the serial references on every pull request** - rejected because they duplicate complete cross-platform aggregates and add macOS work to every change; the required jobs already execute the blocking Linux and native Windows checks, and the other native jobs supply the complete Windows result. -- **Run the real-kernel Sandbox matrix on every pull request** - rejected because its four statuses do not participate in branch protection, while repeated installs, Landlock builds, and macOS unit parity consume runner capacity without changing the merge verdict. The master run retains the platform and installed-launcher signal. +- **Run the real-kernel Sandbox matrix on every pull request** - rejected because its statuses do not participate in branch protection, while repeated installs, Landlock builds, and macOS unit parity consume runner capacity without changing the merge verdict. The master run retains the platform and installed-launcher signal. - **Use one operating-system matrix** - rejected because three named jobs make the reference surface visible without another selection mechanism. - **Run the serial reference on larger runners** - rejected because both required CI and its independent reference must remain runnable when organization-owned pools cannot allocate jobs. diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md index c9fbc84d8f..4feb6c3ae8 100644 --- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md +++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md @@ -24,7 +24,7 @@ Status: implemented macOS 参考流程使用 fork 进程运行常规 Vitest 项目。macOS arm64 上的 Node 24 曾在工作线程中执行 CJS 词法分析器时异常终止；进程边界能够隔离这一外部运行时故障，且无需从聚合流程中删除任何测试，而 Linux 与 Windows 仍使用开销更低的线程池。仓库自身引入的竞态均在相应的观测边界修复：开发构建产物的轮询逻辑每次发布重新扫描结果前，都会先暂存候选表、候选图和候选监视基线映射；构建产物缺失后会一直保持脏状态，直到成功计算内容哈希。PTY 就绪检测会在轮询检查前台进程组归属期间保留提示符候选项；常规静默时限也涵盖从交互式子进程继承而来的标记。真实 PTY fixture 会在运行时拼接同步标记，使就绪等待逻辑不会把交互式 shell 的输入回显误判为子进程已就绪。实时链接场景下的包管理器 e2e 会保留由工作流预先准备的 Corepack 主目录、pnpm 元数据缓存和 store 缓存，同时隔离其他包管理器的可变缓存，因此不会在安装前丢弃可复用的包管理器状态。 -独立的 [Sandbox](../../../../.github/workflows/sandbox.yml) 工作流属于同一职责划分中的参考侧。其 bwrap、Landlock x64/arm64 与 Seatbelt 真实内核矩阵只在向 `master` 推送后运行。这四个作业仅用于诊断：它们既不是分支保护的必需项，也不会跨工作流计入 `all checks passed`。拉取请求 CI 仍通过常规的单元测试与覆盖率清单检查沙箱源码；宿主内核与 packed-install 验证在合并后报告结果。 +独立的 [Sandbox](../../../../.github/workflows/sandbox.yml) 工作流属于同一职责划分中的参考侧。其 bwrap、Landlock x64/arm64 与 Seatbelt 真实内核矩阵只在向 `master` 推送后运行。这四个作业仅用于诊断：它们既不是分支保护的必需项，也不会跨工作流计入 `all checks passed`。第五个作业 `unit-darwin` 在 `macos-latest` 上以自己的预算运行完整单元测试套件，让只在 darwin 上生效的单元测试预期保有平台判据，同时不让 Seatbelt 作业受制于单元测试套件的时长。拉取请求 CI 仍通过常规的单元测试与覆盖率清单检查沙箱源码；宿主内核与 packed-install 验证在合并后报告结果。 master 分支的参考作业仅用于诊断，不参与拉取请求所要求的 `all checks passed` 结果。ci-master 与 Sandbox 工作流把跨平台参考流程保留在 master 推送上。系统根据已完成托管作业的时间戳评估性能，并将其报告为测量结果，而不是写成 `timeout-minutes` 值。 @@ -35,7 +35,7 @@ master 分支的参考作业仅用于诊断，不参与拉取请求所要求的 - **将每个超时值设为相应延迟目标**：不予采纳，因为调度波动会中止原本正确的执行，并使诊断回归所需的证据无法产生。 - **仅信任并发执行的主门禁清单**：不予采纳，因为调度逻辑与校验逻辑共享实现假设；串行聚合流程是一项独立的完整性检查。 - **在每个拉取请求上运行串行参考作业**：不予采纳，因为这些作业会重复完整的跨平台聚合流程，并为每项改动增加 macOS 工作；必需作业已经执行阻塞性的 Linux 和原生 Windows 检查，而其它原生作业提供完整的 Windows 结果。 -- **在每个拉取请求上运行真实内核 Sandbox 矩阵**：不予采纳，因为它的四个状态不参与分支保护，而重复安装、Landlock 构建以及为保持平台一致而运行的 macOS 单元测试会消耗运行器容量，却不会改变合并裁决。master 上的运行保留平台与已安装 launcher 的信号。 +- **在每个拉取请求上运行真实内核 Sandbox 矩阵**：不予采纳，因为它的状态不参与分支保护，而重复安装、Landlock 构建以及为保持平台一致而运行的 macOS 单元测试会消耗运行器容量，却不会改变合并裁决。master 上的运行保留平台与已安装 launcher 的信号。 - **使用一个操作系统矩阵**：不予采纳，因为三个具名作业无需另一套选择机制，就能让参考流程的构成清晰可见。 - **在大型运行器上运行串行参考流程**：不予采纳，因为当组织自有运行器池无法分配作业时，必需 CI 及其独立参考流程都必须仍可运行。 diff --git a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml index 1b44f40971..982839c935 100644 --- a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml +++ b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml @@ -9,8 +9,8 @@ en: cef0f05fd8dfd6a1 zh: 228107eb6c00a91a /agent-note-freeze-low-future-value-agent-notes-outside-the-active-corpus/decision: - en: 453cf66046816477 - zh: af5bb77e849416a1 + en: f0d9c292c3b8dd3b + zh: fd928084dfd333e2 /agent-note-freeze-low-future-value-agent-notes-outside-the-active-corpus/alternatives-considered: en: 7637deef67f3ec14 zh: 7f43606e487fab67 diff --git a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.md b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.md index e9ecfa78f5..8e4ae6beab 100644 --- a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.md +++ b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.md @@ -18,7 +18,7 @@ The root `.rgignore` excludes the archive from searches that traverse a parent d After archival, the triplet is permanently frozen and is historical context rather than current authority. It is not updated for renamed packages, changed behavior, translation standards, formatting rules, broken outbound links, or later documentation contracts. Active prose may intentionally link into an archived note, redirect that link to current authority, or delete it. Repository gates therefore validate links into archived files but never treat archived files as link sources. -[`verify-archived-agent-notes`](../../../../scripts/verify-archived-agent-notes.ts) owns the frozen boundary. It accepts only the closed set of Agent Note kinds, requires a complete triplet with implemented status and matching valid archive dates, verifies the sidecar against both current Git blob hashes, and seals every artifact by path and SHA-256 content hash in an append-only manifest. Its `--write` mode first proves every existing seal unchanged and then appends only newly archived artifacts. Pull-request CI supplies the trusted base SHA and checks out complete history before running the verifier, so a reused runner's shallow checkout cannot omit the baseline manifest. The ordinary Agent Note format, translation-pairing, wrapping, Markdown-link, package-path, Mermaid, documentation-TypeScript, and type-equivalence gates exclude archive sources; their evolving standards cannot create pressure to edit history. +[`verify-archived-agent-notes`](../../../../scripts/verify-archived-agent-notes.ts) owns the frozen boundary. It accepts only the closed set of Agent Note kinds, requires a complete triplet with implemented status and matching valid archive dates, verifies the sidecar against both current Git blob hashes, and seals every artifact by path and SHA-256 content hash in an append-only manifest, with only the exact seal-transition exceptions recorded in [archive instructions](../../archived/AGENTS.md). Its `--write` mode first proves every existing seal unchanged and then appends only newly archived artifacts. Pull-request CI supplies the trusted base SHA and checks out complete history before running the verifier, so a reused runner's shallow checkout cannot omit the baseline manifest. The ordinary Agent Note format, translation-pairing, wrapping, Markdown-link, package-path, Mermaid, documentation-TypeScript, and type-equivalence gates exclude archive sources; their evolving standards cannot create pressure to edit history. The [`dsh-archive-agent-notes`](../../../skills/dsh-archive-agent-notes/SKILL.md) workflow owns classification. It requires a semantic note-by-note audit, uses code and current documentation to identify present authority, treats word count only as triage, carries calibrated keep/archive/delete examples, and reports genuinely borderline outcomes for review. diff --git a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md index 9a3ce2e6e2..a41cf83cf5 100644 --- a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md +++ b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md @@ -18,7 +18,7 @@ implemented Agent Note 作为当前决策记录持续维护，因此活跃记录 归档后，这三个文件永久冻结，只作为历史背景，不再是当前权威依据。不得因为包重命名、行为变化、翻译标准、格式规则、出站链接失效或后续文档约定而更新归档文件。活跃文档可以有意链接到归档 Agent Note，也可以把该链接重定向到当前权威依据，或直接删除。仓库门禁因此会校验指向归档文件的链接，但绝不把归档文件作为链接源来校验。 -[`verify-archived-agent-notes`](../../../../scripts/verify-archived-agent-notes.ts) 负责维护冻结边界。它只接受封闭集合中的 Agent Note 类别，要求三个配对文件完整、状态为 implemented，且归档日期有效并互相匹配；它还会用双方当前的 Git blob hash 校验伴随记录，并在仅追加的 manifest（元数据清单）中按路径和 SHA-256 内容 hash 封存每项产物。其 `--write` 模式会先证明每条现有封存记录对应的内容都未改变，再仅追加新归档的产物。拉取请求 CI 会提供可信的基准 SHA，并在运行校验器前检出完整历史，因此复用运行器上的浅克隆检出无法漏掉基线 manifest。普通的 Agent Note 格式、翻译配对、换行、Markdown 链接、包路径、Mermaid、文档 TypeScript 和类型等价门禁都排除归档源文件，因此这些门禁持续演进的标准不会产生修改历史记录的压力。 +[`verify-archived-agent-notes`](../../../../scripts/verify-archived-agent-notes.ts) 负责维护冻结边界。它只接受封闭集合中的 Agent Note 类别，要求三个配对文件完整、状态为 implemented，且归档日期有效并互相匹配；它还会用双方当前的 Git blob hash 校验伴随记录，并在仅追加的 manifest（元数据清单）中按路径和 SHA-256 内容 hash 封存每项产物，仅允许[归档说明](../../archived/AGENTS.md)中记录的精确封存哈希转换例外。其 `--write` 模式会先证明每条现有封存记录对应的内容都未改变，再仅追加新归档的产物。拉取请求 CI 会提供可信的基准 SHA，并在运行校验器前检出完整历史，因此复用运行器上的浅克隆检出无法漏掉基线 manifest。普通的 Agent Note 格式、翻译配对、换行、Markdown 链接、包路径、Mermaid、文档 TypeScript 和类型等价门禁都排除归档源文件，因此这些门禁持续演进的标准不会产生修改历史记录的压力。 [`dsh-archive-agent-notes`](../../../skills/dsh-archive-agent-notes/SKILL.md) 工作流负责分类判断。它要求逐份 Agent Note 做语义审计，使用代码和当前文档识别现行权威依据，仅把字数作为初步筛选手段，收录经过校准的保留、归档和删除示例，并报告真正处于边界的结果，以供评审。 diff --git a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.i18n.yaml b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.i18n.yaml index 5d29f39a16..a87c0b5e8b 100644 --- a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.i18n.yaml +++ b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.i18n.yaml @@ -9,8 +9,8 @@ en: b3ec2245644b46e6 zh: 83de1cb620f9ddcf /agent-note-make-lefthook-installation-worktree-local/decision: - en: 577d90ff7e03ebaf - zh: dc680155c0c3a2a1 + en: b53a2425f88a6031 + zh: 41f459b00803b3f9 /agent-note-make-lefthook-installation-worktree-local/alternatives-considered: en: d7100b0d2c95a3f9 zh: 070c38c4d0d1331a diff --git a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md index 42adc1ed1d..66ae7a136e 100644 --- a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md +++ b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md @@ -14,7 +14,7 @@ Lefthook-generated hooks prefer an absolute binary path captured from the instal Hook installation is worktree-scoped. With `CI=true` or `GITHUB_ACTIONS=true`, the installer returns before Git discovery or mutation because automated jobs do not consume contributor hooks. Otherwise, it requires Git 2.26 or newer so `git config --show-scope` can report which scope supplied a value, upgrades a format-0 repository to format 1, enables `extensions.worktreeConfig`, and assigns the current worktree an absolute `core.hooksPath` at `$GIT_DIR/dsh-hooks`. -Before upgrading format 0, the installer refuses direct common-config `extensions.*`; it also refuses direct `core.worktree` or `core.bare=true` and non-empty dormant worktree configs that enabling the extension would activate. The migration removes direct `core.bare=false` because false is Git's default. The common repository config and every existing `config.worktree` must be regular files. These checks disable include expansion because Git's repository-format parser also ignores included targets. A repository-scoped lock serializes migration and hook writes; its process ID, random token, file identity, and exact contents must still match at release. Dead or invalid locks require manual recovery rather than automatic breaking. +Before upgrading format 0, the installer refuses direct common-config `extensions.*`; it also refuses direct `core.worktree` or `core.bare=true` and non-empty dormant worktree configs that enabling the extension would activate. The migration removes direct `core.bare=false` because false is Git's default. The common repository config and every existing `config.worktree` must be regular files. These checks disable include expansion because Git's repository-format parser also ignores included targets. A repository-scoped lock serializes migration and hook writes; its process ID, random token, file identity, and exact contents must still match at release. Dead or invalid locks require manual recovery rather than automatic breaking. On Windows, acquiring or inspecting a lock retries EPERM within the existing 30-second acquisition deadline because deleting a lock can temporarily deny access while readers close their handles; other errors and expired deadlines still fail. Each hook directory carries a JSON ownership marker containing the absolute path last published to worktree config. After a checkout moves, that marker permits replacement of only the exact stale owned value. Git seeds a new linked worktree's `config.worktree` from the main worktree; when that seed contains the marker-backed reserved hook path of a registered worktree, the installer replaces only the new worktree's config with its own path. Before Lefthook runs, the marker and every existing generated hook must be unaliased regular files. The installer resolves the effective scope, origin, and value of `core.hooksPath`, including active `config.worktree` includes; it refuses command-scoped paths, unowned worktree-scoped paths, and unowned reserved directories. An inherited system, global, or common-repository path requires `DSH_LEFTHOOK_ALLOW_HOOKS_PATH_OVERRIDE=1`, which opts only the current worktree into Lefthook. Inactive `includeIf` targets are not recursively inspected because they do not affect the current configuration. Command-scoped Git configuration is removed from the Lefthook subprocess environment after validation. diff --git a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.zh.md b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.zh.md index b4b9059678..641bc6d2c8 100644 --- a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.zh.md +++ b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.zh.md @@ -14,7 +14,7 @@ Lefthook 生成的钩子会优先使用安装时从对应 worktree 记录的绝 钩子安装以 worktree 为作用域。当 `CI=true` 或 `GITHUB_ACTIONS=true` 时，安装程序会在探测 Git 或做出任何变更之前返回，因为自动化任务不会使用贡献者钩子。否则，安装程序要求 Git 2.26 或更高版本，使 `git config --show-scope` 可以报告由哪个作用域提供配置值；它会将格式版本为 0 的仓库升级到格式版本 1，启用 `extensions.worktreeConfig`，并将当前 worktree 的 `core.hooksPath` 设为指向 `$GIT_DIR/dsh-hooks` 的绝对路径。 -升级格式 0 之前，安装程序会拒绝共用配置中直接设置的 `extensions.*`；它还会拒绝直接设置的 `core.worktree` 或 `core.bare=true`，以及启用扩展后将被激活的非空休眠 worktree 配置。迁移会移除直接设置的 `core.bare=false`，因为 false 是 Git 的默认值。共用仓库配置和每个已有的 `config.worktree` 都必须是常规文件。这些检查会禁用 include 展开，因为 Git 的仓库格式解析器也会忽略 include 目标。仓库级锁会串行化迁移和钩子写入；释放时，锁的进程 ID、随机令牌、文件身份和完整内容必须仍然匹配。所属进程已结束或内容无效的锁必须人工介入恢复，而不能自动强制解除。 +升级格式 0 之前，安装程序会拒绝共用配置中直接设置的 `extensions.*`；它还会拒绝直接设置的 `core.worktree` 或 `core.bare=true`，以及启用扩展后将被激活的非空休眠 worktree 配置。迁移会移除直接设置的 `core.bare=false`，因为 false 是 Git 的默认值。共用仓库配置和每个已有的 `config.worktree` 都必须是常规文件。这些检查会禁用 include 展开，因为 Git 的仓库格式解析器也会忽略 include 目标。仓库级锁会串行化迁移和钩子写入；释放时，锁的进程 ID、随机令牌、文件身份和完整内容必须仍然匹配。所属进程已结束或内容无效的锁必须人工介入恢复，而不能自动强制解除。在 Windows 上，获取或检查锁时遇到 EPERM 会在原有的 30 秒获取期限内重试，因为删除锁时，读取者关闭句柄前可能暂时无法访问该文件；其他错误及超时仍会导致失败。 每个钩子目录都有一个 JSON 所有权标记，其中包含上次写入 worktree 配置的绝对路径。检出目录移动后，该标记只允许替换确切的陈旧自有值。Git 会以主 worktree 的配置为新链接 worktree 初始化 `config.worktree`；当该初始配置包含某个已注册 worktree 中由所有权标记佐证的保留钩子路径时，安装程序只会在新 worktree 的配置中将其替换为新 worktree 自有的路径。Lefthook 运行前，所有权标记和每个已有的生成钩子都必须是不带别名的常规文件。安装程序会解析 `core.hooksPath` 的生效作用域、来源和值，包括通过当前生效的 `config.worktree` include 加载的值；它会拒绝命令作用域路径、非自有的 worktree 作用域路径以及非自有的保留目录。继承自系统、全局或共用仓库配置的路径必须设置 `DSH_LEFTHOOK_ALLOW_HOOKS_PATH_OVERRIDE=1`，从而只让当前 worktree 显式启用 Lefthook。未生效的 `includeIf` 目标不会被递归检查，因为它们不影响当前配置。完成验证后，Lefthook 子进程的环境会移除命令作用域的 Git 配置。 diff --git a/.agents/notes/implemented/testing/2026-09-26-web-conversation-clock-fixture-day.i18n.yaml b/.agents/notes/implemented/testing/2026-09-26-web-conversation-clock-fixture-day.i18n.yaml new file mode 100644 index 0000000000..8f91e16be8 --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-26-web-conversation-clock-fixture-day.i18n.yaml @@ -0,0 +1,22 @@ +# Bilingual-pair consistency record for 2026-09-26-web-conversation-clock-fixture-day.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-09-26-web-conversation-clock-fixture-day.md +/agent-note-web-conversation-clocks-on-the-fixture-day: + en: 13b5d9d0bb3626af + zh: 0bd01e1848284a35 +/agent-note-web-conversation-clocks-on-the-fixture-day/problem: + en: 6f334488a6d3a28d + zh: b33aed9b10d0cd84 +/agent-note-web-conversation-clocks-on-the-fixture-day/decision: + en: ba875c82795d58e1 + zh: 13a7df6f8c4e0aa6 +/agent-note-web-conversation-clocks-on-the-fixture-day/alternatives-considered: + en: 9c0a2afb1473c1d1 + zh: 36c9e72a70072f5e +/agent-note-web-conversation-clocks-on-the-fixture-day/verification: + en: 5031ca866fed24dd + zh: c11f71af70c1f5ec +/agent-note-web-conversation-clocks-on-the-fixture-day/consequences: + en: c5cdbbd3b2889df7 + zh: 8458ef92443cf1a6 diff --git a/.agents/notes/implemented/testing/2026-09-26-web-conversation-clock-fixture-day.md b/.agents/notes/implemented/testing/2026-09-26-web-conversation-clock-fixture-day.md new file mode 100644 index 0000000000..8b572d43f3 --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-26-web-conversation-clock-fixture-day.md @@ -0,0 +1,47 @@ +# Agent Note: Web conversation clocks on the fixture day + +Status: implemented + +English | [中文](2026-09-26-web-conversation-clock-fixture-day.zh.md) + +## Problem + +Run 36157253018 (job 108144715986, `node 24 / snapshots and artifacts`) failed four browser scenarios in one pass — [steering](../../../../apps/web/tests/steering.e2e.ts), [markdown-images](../../../../apps/web/tests/markdown-images.e2e.ts), [message-actions](../../../../apps/web/tests/message-actions.e2e.ts), and [reference-composer](../../../../apps/web/tests/reference-composer.e2e.ts) — with one aria difference: a message rendered `… and stop. 9/25 23:58` where its golden records `… and stop. {{clock}}`. + +[`newEnglishPage`](../../../../apps/web/tests/support.ts) pins the browser to `Asia/Shanghai`, and [`formatMessageClock`](../../../../packages/client/ui-chat/src/client/chat/message-chrome.ts) prefixes `clock.md` / `clock.ymd` to the clock as soon as the message's local calendar day or year differs from the renderer's. These scenarios left both clocks on the wall clock, and their message times are stamped during the run: a live composer send by the Host, a seed whose fixture header carries `createdAt: 0` anchored at `Date.now() - 60_000` by `seedSession`. The failing job started at 15:54Z, six minutes before local midnight, so rows stamped before it were captured after it and rendered a date prefix; the next run of the same scenario passed minutes after midnight. + +The lane already carried the remedy — [`WEB_FIXTURE_TIME`](../../../../apps/web/tests/support.ts), documented as the same-day anchor for seeded event times and the `Asia/Shanghai` browser clock, and used by seven other scenarios — but these four scenarios never adopted it. + +## Decision + +The four scenarios read the fixture day on both clocks. + +Live-stamped scenarios pin the Host clock with `pinHostClock()`, a `Date.now` spy advancing from the anchor with real elapsed time, and the browser clock with [`pinBrowserClock(page)`](../../../../apps/web/tests/support.ts). Seeded scenarios anchor the seed through `seedSession`'s `createdAt` argument and pin the browser clock the same way. + +The seed anchor is not only the rendered clock: the sidebar's relative ages are computed against the browser clock, so a pinned browser with a live-anchored seed reads `8mo` where the [message-actions](../../../../apps/web/tests/message-actions.e2e.ts) fork golden asserts `now` and `1min`. + +`pinBrowserClock` re-applies one frozen instant from the anchor on an interval instead of leaving it at a single value, because product code reads two `Date.now()` values to decide how long a rendered value is held: the step process keeps its previous title for `PROCESS_TITLE_MINIMUM_MS` = 150 ms ([ChatGroupSeat](../../../../packages/client/ui-chat/src/client/chat/ChatGroupSeat.tsx)) and the composer keymap keeps a composition guard 10 ms past `compositionend` ([keymap](../../../../packages/client/ui-conversation/src/client/input/editor/keymap.ts)). Both compute the remaining hold as `Date.now() - previousReading`, which a permanently frozen clock never advances, so the hold never elapses and the golden's settled text stays unrendered. CI run 36179748541 (job 108218939163) caught exactly that on the first revision that froze the clock: `Preparing questions` where the steering mid golden records `Waiting for your action · Ready to continue?`. + +The steering mid capture waits for that settled question title before it captures, and the [whole-queue scenario](../../../../apps/web/tests/steering.e2e.ts) calls the queue gesture only after the running turn's Stop control appears, so Enter's queue decision always resolves against an agent that already reports busy. + +## Alternatives considered + +**Collapse the rendered date prefix in the aria normalizer.** Collapsing `9/25 23:58` to `{{clock}}` in `normalizeAria` fixes the four scenarios with a two-line change, and it was measured: it passed the four files and then failed `cordis-tool-round`, `stats-paged-history`, and `navigation-panes` in one `DSH_WEB_SNAPSHOT_WORKERS=16` lane run, because their goldens deliberately record the dated form (`9/1 {{clock}}` and the year form in the Timing pane), and `skill-tool-row` already tokenizes that form as `{{date}} {{clock}}`. The two renderings state different facts — this row is from another day, this row is from today — so collapsing them deletes assertions instead of stabilizing them. + +**Leave the browser clock frozen.** Pinning one instant for the whole scenario is simpler and passed the four files, but it removes elapsed time from every two-reading hold in the page, which is how the `Preparing questions` capture above happened. Re-applying the anchor keeps the calendar pinned without changing how long a held value is held. + +**Pin the clocks for the whole lane.** Pinning inside `launchWebScaffold` and `newEnglishPage` would cover every scenario at once, including the ones that fail this way in future. It loses on blast radius: 83 goldens carry a clock and session-tree goldens assert literal relative ages, so a lane-wide now moves every scenario away from its own session and fixture times simultaneously, and each would still need its own anchor to read the buckets it was recorded with. + +**Keep scenarios clear of local midnight.** Scheduling or refusing runs near the boundary leaves the dependency in place and fails the run instead of the code under test. The [CI readiness and completion decision](2026-09-08-ci-readiness-and-completion.md) already rejects budgets and retries as substitutes for a controlled observation. + +## Verification + +Two negative controls pin one clock and leave the other on the wall clock, reproducing the recorded signature exactly: `steering` with the browser clock pinned and the Host clock live fails its two golden tests with `… and stop. 9/26 {{clock}}`, and `message-actions` with the browser clock pinned and a live-anchored seed fails with `9/26 {{clock}}` on every clock line plus `now` where the fork golden asserts `1min`. Pinning both clocks passes both files, and their goldens are unchanged. + +The queue scenario's start race is measured, not inferred: with the clocks pinned and no busy observation it failed 10 times in 61 runs of `vitest run … -t "queues two messages"`, all at the same `2 queued messages` wait; `origin/master` without the pins failed 0 of 41; with the observation added, 20 of 20 passed. + +CI run 36179748541 (job 108218939163) shows the calendar fix holding under the lane's own topology: the prompt line matches `{{clock}}` where run 36157253018 rendered `9/25 {{clock}}`. + +## Consequences + +The four scenarios render the same aria line whenever they run, and their goldens keep asserting a clock without a date prefix. The calendar fact is owned per scenario: a scenario that types messages, or seeds a fixture whose header carries `createdAt: 0`, must read the fixture day on both clocks, or it inherits the midnight exposure. Product clock rendering, the `Asia/Shanghai` browser timezone, every committed golden, and the assertions of the scenarios not listed here are unchanged. diff --git a/.agents/notes/implemented/testing/2026-09-26-web-conversation-clock-fixture-day.zh.md b/.agents/notes/implemented/testing/2026-09-26-web-conversation-clock-fixture-day.zh.md new file mode 100644 index 0000000000..4631d36b8a --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-26-web-conversation-clock-fixture-day.zh.md @@ -0,0 +1,47 @@ +# Agent Note: Web conversation clocks on the fixture day + +Status: implemented + +[English](2026-09-26-web-conversation-clock-fixture-day.md) | 中文 + +## Problem + +运行 36157253018（作业 108144715986，`node 24 / snapshots and artifacts`）在一次执行中让四个浏览器场景失败——[steering](../../../../apps/web/tests/steering.e2e.ts)、[markdown-images](../../../../apps/web/tests/markdown-images.e2e.ts)、[message-actions](../../../../apps/web/tests/message-actions.e2e.ts) 与 [reference-composer](../../../../apps/web/tests/reference-composer.e2e.ts)——且是同一处 aria 差异：消息渲染为 `… and stop. 9/25 23:58`，而 golden 记录为 `… and stop. {{clock}}`。 + +[`newEnglishPage`](../../../../apps/web/tests/support.ts) 将浏览器时区固定为 `Asia/Shanghai`，而 [`formatMessageClock`](../../../../packages/client/ui-chat/src/client/chat/message-chrome.ts) 一旦消息的本地日历日或年份与渲染时不同，就会在时钟前拼接 `clock.md` / `clock.ymd`。这些场景把两个时钟都留在墙上时钟上，而它们的消息时间是在运行期盖章的：实时输入由 Host 盖章，fixture 头部为 `createdAt: 0` 的种子由 `seedSession` 以 `Date.now() - 60_000` 为锚点。失败的作业于 15:54Z 启动，距本地午夜还有六分钟，于是午夜前盖章的行在午夜后捕获并渲染出日期前缀；同一场景的下一次运行在午夜后数分钟通过。 + +通道本已具备对策——[`WEB_FIXTURE_TIME`](../../../../apps/web/tests/support.ts)，其文档写明它是种子事件时间与 `Asia/Shanghai` 浏览器时钟的同日锚点，另有七个场景在使用它——但这四个场景从未采用。 + +## Decision + +这四个场景让两个时钟都读取 fixture 日。 + +实时盖章的场景用 `pinHostClock()` 固定 Host 时钟（一个从锚点起按真实流逝时间推进的 `Date.now` spy），并用 [`pinBrowserClock(page)`](../../../../apps/web/tests/support.ts) 固定浏览器时钟。种子场景通过 `seedSession` 的 `createdAt` 参数锚定种子，并用同样方式固定浏览器时钟。 + +种子锚点不只影响渲染出的时钟：侧边栏的相对时间也以浏览器时钟为基准计算，因此固定浏览器却用实时锚点的种子会读出 `8mo`，而 [message-actions](../../../../apps/web/tests/message-actions.e2e.ts) 的 fork golden 断言的是 `now` 与 `1min`。 + +`pinBrowserClock` 按固定间隔从锚点重新施加同一个冻结时刻，而不是让时钟停在单一数值上，因为产品代码要靠读取两个 `Date.now()` 值来决定一个已渲染值要保持多久：步骤进程会把上一个标题保持 `PROCESS_TITLE_MINIMUM_MS` = 150 ms（[ChatGroupSeat](../../../../packages/client/ui-chat/src/client/chat/ChatGroupSeat.tsx)），输入框 keymap 会在 `compositionend` 后再保持 10 ms 的合成守卫（[keymap](../../../../packages/client/ui-conversation/src/client/input/editor/keymap.ts)）。两者都把剩余保持时间算作 `Date.now() - previousReading`，而永久冻结的时钟永远不会让它推进，于是保持期不会结束，golden 里那行稳定文案始终不出现。CI 运行 36179748541（作业 108218939163）在第一个冻结时钟的修订上正是抓到了这一点：steering 的 mid golden 记录的是 `Waiting for your action · Ready to continue?`，实际捕获到 `Preparing questions`。 + +steering 的 mid 捕获在截图前等待该稳定标题出现；[整队场景](../../../../apps/web/tests/steering.e2e.ts) 则只在运行中回合的停止控件出现后才做排队手势，因此 Enter 的排队判定总是相对一个已上报忙碌的 agent 解析。 + +## Alternatives considered + +**在 aria normalizer 中折叠渲染出的日期前缀。** 在 `normalizeAria` 中把 `9/25 23:58` 折叠为 `{{clock}}` 只需两行即可修好这四个场景，且已实测：它让四个文件通过，随后在一次 `DSH_WEB_SNAPSHOT_WORKERS=16` 的通道运行中让 `cordis-tool-round`、`stats-paged-history` 与 `navigation-panes` 失败，因为这些 golden 有意记录带日期的形式（`9/1 {{clock}}`，以及 Timing 面板中的年份形式），而 `skill-tool-row` 早已把该形式 token 化为 `{{date}} {{clock}}`。两种渲染陈述的是不同事实——此行来自另一天，此行来自今天——因此折叠它们是在删除断言，而不是在稳定断言。 + +**让浏览器时钟保持冻结。** 整个场景固定单一时刻更简单，也能让四个文件通过，但它抽掉了页面中所有“读两次”保持逻辑的时间流逝，上面的 `Preparing questions` 捕获就是这样发生的。重新施加锚点既保持日历固定，又不改变已渲染值的保持时长。 + +**为整条通道固定时钟。** 在 `launchWebScaffold` 与 `newEnglishPage` 内固定时钟可以一次覆盖所有场景，包括将来以同样方式失败的场景。它因影响面而落选：83 个 golden 带有时钟，且会话树 golden 断言字面相对时间，因此通道级的 now 会同时把所有场景移离各自的会话与 fixture 时间，而每个场景仍需自己的锚点才能读出录制时的分桶。 + +**让场景避开本地午夜。** 在边界附近调度或拒绝运行会把依赖留在原处，并让运行而非被测代码失败。[CI 就绪与完成决策](2026-09-08-ci-readiness-and-completion.zh.md) 已经拒绝用预算或重试替代受控观察。 + +## Verification + +两个负向对照各固定一个时钟、把另一个留在墙上时钟，精确复现了记录到的特征：`steering` 固定浏览器时钟而 Host 时钟实时时，两个 golden 用例以 `… and stop. 9/26 {{clock}}` 失败；`message-actions` 固定浏览器时钟但仍用实时锚点的种子时，每行时钟都以 `9/26 {{clock}}` 失败，且本应断言 `1min` 的 fork golden 读出 `now`。两个时钟都固定后两个文件均通过，且它们的 golden 未改动。 + +排队场景的启动竞态是实测而非推断：固定时钟且不等待忙碌状态时，`vitest run … -t "queues two messages"` 在 61 次中失败 10 次，全部停在同一个 `2 queued messages` 等待上；未加固定时钟的 `origin/master` 在 41 次中失败 0 次；加上该观察后 20 次全部通过。 + +CI 运行 36179748541（作业 108218939163）显示日历修复在通道自身的拓扑下成立：提示行匹配 `{{clock}}`，而运行 36157253018 渲染的是 `9/25 {{clock}}`。 + +## Consequences + +这四个场景无论何时运行都渲染同一行 aria，其 golden 继续断言不带日期前缀的时钟。日历事实现在按场景归属：自行输入消息、或种子 fixture 头部为 `createdAt: 0` 的场景必须让两个时钟都读取 fixture 日，否则会继承午夜暴露。产品时钟渲染、`Asia/Shanghai` 浏览器时区、所有已提交的 golden，以及本说明未列出的场景的断言均不变。 diff --git a/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.i18n.yaml b/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.i18n.yaml new file mode 100644 index 0000000000..3e4c2f6895 --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.i18n.yaml @@ -0,0 +1,22 @@ +# Bilingual-pair consistency record for 2026-09-27-observation-waits-on-observed-state.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.md +/agent-note-windows-lane-observations-wait-on-the-state-they-read: + en: 8949f81c9d585fc0 + zh: 34e1bdbca1cf2126 +/agent-note-windows-lane-observations-wait-on-the-state-they-read/problem: + en: 270b015afc8de8ac + zh: 65aeb1e270d19a27 +/agent-note-windows-lane-observations-wait-on-the-state-they-read/decision: + en: 479cb25421102304 + zh: 9e23396728001e2c +/agent-note-windows-lane-observations-wait-on-the-state-they-read/alternatives-considered: + en: 00e59c561085e081 + zh: 4f6ac4dfc3259f58 +/agent-note-windows-lane-observations-wait-on-the-state-they-read/consequences: + en: 13db32f9da19d87b + zh: 48081fc7035dea45 +/agent-note-windows-lane-observations-wait-on-the-state-they-read/deferred: + en: 18dc81f98375fb04 + zh: e30413cd3d201b80 diff --git a/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.md b/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.md new file mode 100644 index 0000000000..e0218a4d5f --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.md @@ -0,0 +1,35 @@ +# Agent Note: Windows-lane observations wait on the state they read + +Status: implemented + +English | [中文](2026-09-27-observation-waits-on-observed-state.zh.md) + +## Problem + +Two self-hosted Windows lane cases observed state through a wall-clock window instead of the state they assert on. + +`packages/boot/plugin-manager/tests/operations.spec.ts` armed a 100 ms timer when the case started and read the profile's `run.json` when it fired, to observe the run record while the run was still in flight. The repaired installation it observes runs only after a refused installation, a `pnpm view` lookup, the restoration of the profile files, and a second `launch`, so the timer measured that whole prefix rather than the record write. Under the loaded runner the repair began after the deadline and the case failed with `expected null to deeply equal { pid: 4343, grouped: false }` (PR #4595 `windows node 24 / coverage`, job 108402945554, 2026-09-26; the case took 345 ms, and its sibling single-run cases, which need no such prefix, passed in 113 ms and 116 ms). + +`packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts` counts each send's settlement tier and requires the controlled-prompt fast path, but reported only the count, so a failure could not say which tier settled which send — the one fact that separates a degraded readiness path from a mis-sized window. + +## Decision + +`observingChild` stays in flight until the test has read the run record, so the read cannot race the run's end, and its bounded wait starts at the mocked launcher's hand-over instead of at test start: the recorded run is one atomic write that follows the launch, so the bound only has to cover that write. `RECORD_WAIT_MS` (2 s) is deliberately below the case budget, so a record that never appears reports as the assertion that names it rather than as a runner timeout. Both the repair-install case and the single-run case hand the child over through the same `spawned` hook. + +The loader-composition settle-reason assertion carries `JSON.stringify(settleReasons)` as its failure message. The threshold and the assertions are unchanged. + +## Alternatives considered + +**Raise the fixed timer, or poll for the record from test start.** Rejected: both keep the window anchored before the operation reached the run it observes, so the bound has to cover the whole prefix and grows with whatever the runner does before the repair run — the same mistake at a larger size. Anchoring on the hand-over measures only the state transition being waited for. + +**Wait for the record without a bound.** Rejected: a record the operation never writes would hang the case until the runner's own timeout and report nothing about the record. + +**Record only the settlements that matter, or assert a subset of sends.** Rejected: it weakens what the suite pins — that no send falls back to the silence tier — to make the failure go away. + +## Consequences + +Both plugin-manager record cases now observe the record while the run is in flight on a loaded runner, and a genuinely missing record still fails the same assertion. The bounded wait costs 2 s only when the operation never writes the record. + +## Deferred + +The loader-composition failure of 2026-09-25/26 is an environment-sensitive readiness window, not a product logic error, and the product now owns a documented tolerance for it: the [prompt tail grace decision](../bug-fix/2026-09-27-pwsh-prompt-tail-grace.md). On Windows `isStdinWaiting` returns false and `foregroundPgid` returns the shell pid, so `stdin_read` can only come from the controlled-prompt tail. A native Windows probe (Windows 11 ARM64 guest, 8 vCPU, with the readiness probe enabled) shows the fast path is deterministic when delivery is normal: every prompt render is the OSC marker alone in one pty chunk followed by a five-byte `dsh> ` chunk 2-28 ms later (56 renders), nothing printable follows any prompt, the output carries no terminal queries, and 21 runs (baseline, six CPU burners, emulated x64, four concurrent pty-heavy instances, and Windows PowerShell 5.1 as the shell) settled all seven sends on the prompt, six `stdin_read` plus the `exit` command's `session_exit`. Withholding each session's prompt tail for four seconds reproduces the reported failure exactly: `expected 4 to be greater than or equal to 6` with `["inferred_idle","stdin_read","stdin_read","stdin_read","stdin_read","session_exit","inferred_idle"]`, the degraded settles carrying `promptSeen` true, `promptTextSeen` false, an empty tail and `idleFor` 3301/3313 ms (exactly the configured bound), 22.1/21.9 s against 17.5/20.9 s in CI, and every output assertion still passing. The CI trigger itself was not reproduced locally, so this case keeps its assertion and supplies `promptTailGraceMs` in its composition: it measures the controlled-prompt path rather than the host's delivery timing, and it still fails when no prompt marker appears at all. diff --git a/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.zh.md b/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.zh.md new file mode 100644 index 0000000000..079ae65451 --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.zh.md @@ -0,0 +1,35 @@ +# Agent Note: Windows lane 的观测等待它所读取的状态 + +Status: implemented + +[English](2026-09-27-observation-waits-on-observed-state.md) | 中文 + +## Problem + +自托管 Windows lane 的两个用例用墙钟窗口观测状态，而不是等待它们真正断言的那个状态。 + +`packages/boot/plugin-manager/tests/operations.spec.ts` 在用例开始时启动一个 100 毫秒定时器，并在它触发时读取 profile 的 `run.json`，以此在该 run 仍在进行时观测 run 记录。它要观测的「修复安装」只有在一次被拒绝的安装、一次 `pnpm view` 查询、profile 文件恢复以及第二次 `launch` 之后才会发生，因此该定时器度量的是这整段前缀，而不是记录写入本身。在负载较高的 runner 上修复安装晚于该截止时刻才开始，用例因而以 `expected null to deeply equal { pid: 4343, grouped: false }` 失败（PR #4595 的 `windows node 24 / coverage`，job 108402945554，2026-09-26；该用例耗时 345 毫秒，而相邻的单 run 用例不需要这段前缀，分别以 113 毫秒和 116 毫秒通过）。 + +`packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts` 统计每次 send 的结算层级并要求受控提示符快路径，但只报告数量，失败时无法说明哪一层级结算了哪一次 send——而这正是区分「就绪路径退化」与「窗口取值不当」的唯一事实。 + +## Decision + +`observingChild` 会保持该 run 在进行中，直到测试读到 run 记录，因此读取不可能与 run 结束竞争；其有界等待从被 mock 的启动器交接处开始，而不是从用例开始处开始：被记录的 run 只是紧随启动之后的一次原子写入，因此等待上界只需覆盖这次写入。`RECORD_WAIT_MS`（2 秒）刻意低于用例预算，于是一条始终没有出现的记录会以指名它的断言报告，而不是以 runner 超时报告。修复安装用例与单 run 用例都通过同一个 `spawned` 钩子交接子进程。 + +loader-composition 的结算层级断言把 `JSON.stringify(settleReasons)` 作为失败信息。阈值与断言本身不变。 + +## Alternatives considered + +**提高固定定时器的时长，或从用例开始处轮询记录。** 不采纳：两者都把窗口锚定在操作尚未到达它所观测的 run 之前，于是上界必须覆盖整段前缀，并随 runner 在修复 run 之前的行为一起增长——同样的错误，只是更大。锚定在交接处则只度量真正要等待的那个状态转换。 + +**无上界地等待记录。** 不采纳：若操作永不写入记录，用例会挂到 runner 自身的超时，且对记录本身不给出任何信息。 + +**只记录关键的那几次结算，或断言 send 的子集。** 不采纳：这会把该套件所固定的内容——任何 send 都不得回退到静默层——削弱成让失败消失。 + +## Consequences + +在负载较高的 runner 上，两个插件管理器记录用例现在都能在该 run 仍在进行时观测到记录，而真正缺失的记录仍会以同一条断言失败。只有在操作始终不写记录时，这段有界等待才会付出 2 秒。 + +## Deferred + +loader-composition 于 2026-09-25/26 的失败是一个对投递时序敏感的就绪窗口，而不是 product 逻辑错误；product 现在为它拥有一个文档化的容忍度：[提示符尾部宽限决策](../bug-fix/2026-09-27-pwsh-prompt-tail-grace.zh.md)。在 Windows 上 `isStdinWaiting` 返回 false、`foregroundPgid` 返回 shell 自身的 pid，因此 `stdin_read` 只能来自受控提示符尾部。原生 Windows 探测（Windows 11 ARM64 guest，8 vCPU，启用就绪探测）表明只要投递正常，快路径就是确定的：每次提示符渲染都是 OSC 标记独占一个 pty 分块，紧随其后的下一个分块是 5 字节的 `dsh> `，间隔 2–28 毫秒（56 次渲染），任何提示符之后都没有可打印文本，输出中也没有终端查询；21 次运行（基线、6 个 CPU burner、模拟 x64、4 个并发 pty 实例、以及以 Windows PowerShell 5.1 作为 shell）全部七次 send 都按提示符结算——六次 `stdin_read` 加 `exit` 命令的 `session_exit`。把每个 session 的提示符尾部扣留 4 秒可以精确复现上报的失败：`expected 4 to be greater than or equal to 6`，`settleReasons` 为 `["inferred_idle","stdin_read","stdin_read","stdin_read","stdin_read","session_exit","inferred_idle"]`，退化的结算带着 `promptSeen` 为 true、`promptTextSeen` 为 false、空尾部与 `idleFor` 3301/3313 毫秒（正是配置的上界），耗时 22.1/21.9 秒对照 CI 的 17.5/20.9 秒，且所有输出断言仍然通过。CI 的触发条件本身未能在本地复现，因此该用例保留其断言并在组合中提供 `promptTailGraceMs`：它度量受控提示符路径而不是宿主机的投递时序，且在完全没有提示符标记时仍然失败。 diff --git a/.agents/notes/implemented/testing/2026-09-27-plugin-manager-git-child-environment.i18n.yaml b/.agents/notes/implemented/testing/2026-09-27-plugin-manager-git-child-environment.i18n.yaml new file mode 100644 index 0000000000..7de0fe8b38 --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-27-plugin-manager-git-child-environment.i18n.yaml @@ -0,0 +1,22 @@ +# Bilingual-pair consistency record for 2026-09-27-plugin-manager-git-child-environment.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-09-27-plugin-manager-git-child-environment.md +/agent-note-plugin-manager-git-children-isolate-the-host-s-command-line-configuration: + en: ebb8f6a97dcc126a + zh: 4f7fbb487136f218 +/agent-note-plugin-manager-git-children-isolate-the-host-s-command-line-configuration/problem: + en: 67f7316995be5f48 + zh: fbb8dda3946ff1f3 +/agent-note-plugin-manager-git-children-isolate-the-host-s-command-line-configuration/decision: + en: 7723360996b8b09e + zh: 78d8dfa61b1711ec +/agent-note-plugin-manager-git-children-isolate-the-host-s-command-line-configuration/alternatives-considered: + en: 3f4e5b0bc9a8a961 + zh: 5f39ffd20e076914 +/agent-note-plugin-manager-git-children-isolate-the-host-s-command-line-configuration/verification: + en: 7c8b5b8f4002c71a + zh: 59493bd968ba34bf +/agent-note-plugin-manager-git-children-isolate-the-host-s-command-line-configuration/consequences: + en: b81437323c8ae6e2 + zh: 79f8d0926218ae2e diff --git a/.agents/notes/implemented/testing/2026-09-27-plugin-manager-git-child-environment.md b/.agents/notes/implemented/testing/2026-09-27-plugin-manager-git-child-environment.md new file mode 100644 index 0000000000..ded480eacb --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-27-plugin-manager-git-child-environment.md @@ -0,0 +1,29 @@ +# Agent Note: Plugin-manager Git children isolate the host's command-line configuration + +Status: implemented + +English | [中文](2026-09-27-plugin-manager-git-child-environment.zh.md) + +## Problem + +The self-hosted Windows serial lane failed 13 cases in run 36227311113 (job 108363684565); 12 share one cause: [github-connection.spec.ts](../../../../packages/boot/plugin-manager/tests/github-connection.spec.ts) 9 (the six install-address forms and three proxy cases) and [manager.spec.ts](../../../../packages/boot/plugin-manager/tests/manager.spec.ts) 3 real-Git install cases. The host carried Git's indexed command-line configuration — `GIT_CONFIG_COUNT` with `GIT_CONFIG_KEY_0` / `GIT_CONFIG_VALUE_0`, the group Git hands to `git -c` calls and their hook children. The shared subprocess scrub (`scrubbedParentEnv`) removes credential-shaped names, so it stripped the key and kept the counter; Git reads the counter first, and every child died with `error: missing config key GIT_CONFIG_KEY_0` / `fatal: unable to parse command-line config` (exit 128) before opening any configuration file. + +## Decision + +Both spec files delete Git's command-line configuration group from their own process environment before they spawn Git, through [isolateGitCommandLineConfig](../../../../packages/boot/plugin-manager/tests/git-environment.ts). These specs judge profile behavior — profile Git configuration, real installs — rather than host state, so a host that exports the group no longer changes their outcome. The helper restores the removed entries after the file with `vi.stubEnv(name, undefined)` and `vi.unstubAllEnvs()`. + +## Alternatives considered + +**Remove the group whole in `scrubbedParentEnv`.** The product-side fix treats the counter and its keys as one unit, but it changes shared subprocess behavior for every consumer, which the review directive for this change excludes. It is preserved on the branch `deferred/git-command-line-config-scrub-20260927` for a future product PR with its own justification. + +**Pin `GIT_CONFIG_COUNT: '0'` at the plugin-manager call sites.** `packages/deliverables/workspace-changes/src/git.ts` does exactly that for its children, so the same two lines in `github-connection.ts` and `operations.ts` would cover this class. That is still a product behavior change, so it stays out of scope here. + +**Clear the group in the lane's workflow.** The group reaches the job from the host image rather than from a step this repository owns, and other Git-spawning specs would stay exposed. + +## Verification + +`GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=core.bare GIT_CONFIG_VALUE_0=true pnpm exec vitest run packages/boot/plugin-manager/tests/github-connection.spec.ts packages/boot/plugin-manager/tests/manager.spec.ts` fails 12 cases at the parent revision with the lane's assertion set and passes 95/95 with the isolation in place. + +## Consequences + +The two specs pass on a host that exports Git command-line configuration. The product's treatment of such hosts is unchanged, so the same environment still breaks any other consumer of the shared scrub; a future product change to `scrubbedParentEnv` must revisit this note. diff --git a/.agents/notes/implemented/testing/2026-09-27-plugin-manager-git-child-environment.zh.md b/.agents/notes/implemented/testing/2026-09-27-plugin-manager-git-child-environment.zh.md new file mode 100644 index 0000000000..66d667af50 --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-27-plugin-manager-git-child-environment.zh.md @@ -0,0 +1,29 @@ +# Agent Note: plugin-manager 的 Git 子进程隔离宿主机的命令行配置 + +Status: implemented + +[English](2026-09-27-plugin-manager-git-child-environment.md) | 中文 + +## Problem + +自托管 Windows 串行 lane 在运行 36227311113（作业 108363684565）中失败 13 个用例，其中 12 个同一成因：[github-connection.spec.ts](../../../../packages/boot/plugin-manager/tests/github-connection.spec.ts) 9 个（六种安装地址形式与三个代理用例）与 [manager.spec.ts](../../../../packages/boot/plugin-manager/tests/manager.spec.ts) 3 个真实 Git 安装用例。该宿主机携带 Git 的索引式命令行配置——`GIT_CONFIG_COUNT` 加上 `GIT_CONFIG_KEY_0` / `GIT_CONFIG_VALUE_0`，即 Git 交给 `git -c` 调用及其 hook 子进程的那一组变量。共享的子进程清洗（`scrubbedParentEnv`）按凭据形态的名字移除变量，于是移除了键却保留了计数；Git 先读计数，每个子进程都在打开任何配置文件之前以 `error: missing config key GIT_CONFIG_KEY_0` / `fatal: unable to parse command-line config`（退出码 128）失败。 + +## Decision + +这两个 spec 文件在派生 Git 之前，从自身进程环境里删除 Git 的命令行配置组，由 [isolateGitCommandLineConfig](../../../../packages/boot/plugin-manager/tests/git-environment.ts) 完成。这些 spec 判定的是 profile 行为——profile 的 Git 配置、真实安装——而不是宿主机状态，因此导出该组的宿主机不再改变它们的结果。辅助函数在文件结束后用 `vi.stubEnv(name, undefined)` 与 `vi.unstubAllEnvs()` 还原被移除的条目。 + +## Alternatives considered + +**在 `scrubbedParentEnv` 中整体移除该组。** 产品侧修复把计数与它的键当作一个整体，但它会改变所有消费者共享的子进程行为，而本次改动的 review 指令排除了这一点。该修复保留在分支 `deferred/git-command-line-config-scrub-20260927`，留待将来带自身论证的产品 PR。 + +**在 plugin-manager 的调用点固定 `GIT_CONFIG_COUNT: '0'`。** `packages/deliverables/workspace-changes/src/git.ts` 正是这样对待自己的子进程，因此在 `github-connection.ts` 与 `operations.ts` 加同样两行即可覆盖这一类。但那仍属产品行为改动，故不在此范围内。 + +**在 lane 的工作流里清除该组。** 该组来自宿主机镜像，而不是本仓库拥有的某个步骤，且其他会派生 Git 的 spec 仍会暴露。 + +## Verification + +`GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=core.bare GIT_CONFIG_VALUE_0=true pnpm exec vitest run packages/boot/plugin-manager/tests/github-connection.spec.ts packages/boot/plugin-manager/tests/manager.spec.ts` 在父修订上以 lane 的断言集合失败 12 个用例，加入隔离后 95/95 通过。 + +## Consequences + +这两个 spec 在导出 Git 命令行配置的宿主机上通过。产品对此类宿主机的处理未变，因此同一环境仍会破坏共享清洗的其他消费者；将来若改动 `scrubbedParentEnv`，必须回头审视本记录。 diff --git a/.agents/notes/implemented/testing/2026-09-27-web-lane-assertions-name-their-input-state.i18n.yaml b/.agents/notes/implemented/testing/2026-09-27-web-lane-assertions-name-their-input-state.i18n.yaml new file mode 100644 index 0000000000..76b9ec6213 --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-27-web-lane-assertions-name-their-input-state.i18n.yaml @@ -0,0 +1,22 @@ +# Bilingual-pair consistency record for 2026-09-27-web-lane-assertions-name-their-input-state.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-09-27-web-lane-assertions-name-their-input-state.md +/agent-note-web-lane-assertions-name-their-input-state: + en: 6b04734ce8fbeb4a + zh: 73db3bd3ac5985dc +/agent-note-web-lane-assertions-name-their-input-state/problem: + en: 12391509553e0152 + zh: 86d02884ae9c1b09 +/agent-note-web-lane-assertions-name-their-input-state/decision: + en: c6a8e79707975429 + zh: 4fe1f6abd6fd4c1e +/agent-note-web-lane-assertions-name-their-input-state/alternatives-considered: + en: 6cd5940f55500c3d + zh: ded68b931ed81e10 +/agent-note-web-lane-assertions-name-their-input-state/verification: + en: 6d11abb7a60f81ae + zh: 42bc43777a3b02b7 +/agent-note-web-lane-assertions-name-their-input-state/consequences: + en: 2ecf084ca4df49c4 + zh: bbd8823fd0910609 diff --git a/.agents/notes/implemented/testing/2026-09-27-web-lane-assertions-name-their-input-state.md b/.agents/notes/implemented/testing/2026-09-27-web-lane-assertions-name-their-input-state.md new file mode 100644 index 0000000000..acee58b51a --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-27-web-lane-assertions-name-their-input-state.md @@ -0,0 +1,49 @@ +# Agent Note: Web lane assertions name their input state + +Status: implemented + +English | [中文](2026-09-27-web-lane-assertions-name-their-input-state.zh.md) + +## Problem + +Three browser-lane scenarios captured an aria region while a state the golden records was only implied by whatever the pointer, the keyboard, or an in-flight Host read happened to be doing at that instant, so each capture could land on the other state. + +[workspace-new-session-folding](../../../../apps/web/tests/workspace-new-session-folding.e2e.ts) captures two goldens of one sidebar. `sidebar.expected.md` records the Workspace row with its row-actions cell revealed, which [Rows.module.css](../../../../packages/client/ui-workspace/src/client/rows/Rows.module.css) does under `.projectRow:hover`; `first-batch.expected.md` records the sixth session that way under `.sessionRow:hover`, the first row the batch reveals. Both captures therefore depend on where the pointer sits, and the scenario's own "Show 11 more sessions" click reflows the list under a stationary pointer. The serial self-hosted master lane failed this scenario with both goldens' requirements unmet — `treeitem "{{workspace}}"` without the actions, and the golden's hovered row rendering its plain relative time — in every one of the nine failing runs observed between 2026-09-24 and 2026-09-27. + +[turn-tail-actions](../../../../apps/web/tests/turn-tail-actions.e2e.ts) captures the Copy footer focused twice: `running.expected.md` records a `tooltip "Copy"` beside it, `settled.expected.md` records none. [Tooltip](../../../../packages/client/ui-primitives/src/Tooltip.tsx) ignores focus while the last input came from a pointer, and only a keydown clears that flag, so whether the first capture shows the bubble depends on whether the harness pressed a key after the scenario's last click. + +[plugin-install-cancel](../../../../apps/web/tests/plugin-install-cancel.e2e.ts) read the enabled plugin card's `data-plugin-status` once after the highlighted card appeared. The store's `enableInstalled` marks the card and starts the directory reload the Host answers, so the highlight is observable before the reload commits the enabled bundle into the list: the status flipped `disabled` → `running` 61 ms after the highlight in three local runs, and the run that failed read it inside that window. + +## Decision + +Each capture names the state its golden records before it captures. + +The folding scenario hovers the Workspace row before the sidebar capture and the first row the batch reveals before the first-batch capture, so both hovered rows are established rather than inherited from the layout around the Show-more click. The goldens, the folding quota, and the row rendering are unchanged; the scenario now performs the hover a reader of the golden would perform. + +The turn-tail scenario clears the pointer flag with a key that moves nothing, focuses the Copy button, and waits for the tooltip the running golden records. The settled capture keeps the plain focus, which is what its golden records once the Stop click has left the pointer owning the last input. + +The install-cancel scenario polls the card's status instead of sampling it, so the assertion observes the directory reload that the highlight precedes. The highlight stays the locator that finds the card, because the later `2400 ms` clock advance still asserts the card detaches with it. + +## Alternatives considered + +**Collapse the hovered and unhovered renderings in the aria normalizer.** The two renderings state different facts — one row is hovered, the others are not — and both goldens deliberately record the row-actions cell and the relative time. Collapsing them would delete the assertion rather than stabilize it, the same trade every lane golden that deliberately records a dated or stateful form already rejects. + +**Deliver a blank event and keep the pointer where the click leaves it.** The button moves as the batch inserts, so the row under the pointer still follows layout: the folding negative control below reproduces the failure with the pointer inside the sidebar and no row hovered. + +**Disable hover styling or the tooltip modality rule in the scenario.** Both are shipped rendering and interaction behavior the goldens are the evidence for; a scenario-local override would test a page the product does not serve. + +**Raise the capture timeout or retry the comparison.** Neither establishes which state was captured; `captureStableAria` already waits for two equal consecutive snapshots, and it was satisfied by the wrong state — the limit the [CI completion decision](2026-09-08-ci-readiness-and-completion.md) and the [connection and compaction fixture preconditions](2026-09-12-connection-and-compaction-fixture-preconditions.md) already record. + +## Verification + +Two negative controls reproduce the recorded signatures with the shipped assertions. Hovering the New Session row instead of the Workspace row before the folding scenario's first capture fails `sidebar.expected.md` with `treeitem "{{workspace}}"` where the golden records `treeitem "{{workspace}} Workspace actions …"`. A bare mouse press with no key before the turn-tail scenario focuses the Copy button raises no bubble, and the running capture then fails with the missing `tooltip "Copy"` the serial lane recorded. Both controls pass after the change. + +Measured locally, one file at a time: `DSH_SNAPSHOT=replay pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/.e2e.ts` → workspace-new-session-folding 15/15 before the change and 20/20 after, turn-tail-actions 8/8 before and 20/20 after, plugin-install-cancel 12/12 before and 20/20 after. The lane configuration `DSH_SNAPSHOT=replay DSH_WEB_SNAPSHOT_WORKERS=16 pnpm run test:web:ci` passes all three files in three consecutive local runs. + +The install-cancel scenario carries a residual exposure this change does not remove and whose cause is not diagnosed: twice on `node 24 / snapshots and artifacts`, and once locally with the pre-change file on the same lane command, the highlighted card locator at `plugin-install-cancel.e2e.ts:217` stayed unmatched for 30 s after the enable click closed the dialog. The paused page clock rules out the highlight expiry timer, so the wait is not racing that; no local focused run or the three lane runs above reproduced it, and nothing here is known to hang the store's `load()`. The poll added by this change covers the status read after the card appears, not this locator. + +The WebKit case the serial master lane also failed is not a scenario race and stays out of this change: `declared-reasoning.e2e.ts` launches Playwright's WebKit, the lane's step fetched that browser without its host libraries, and `browserType.launch` failed with "Host system is missing dependencies to run browsers". [ci.yml](../../../../.github/workflows/ci.yml) states the persistent VM image owns Playwright's Linux system packages and installs the dependency set only off the self-hosted pool, so repairing the image or the pool's ownership is a runner change, not a scenario one. Installing WebKit's libraries on a developer machine makes the file's 8 cases pass. + +## Consequences + +The three scenarios render the aria their goldens record whatever state the harness arrives in, and no golden, product surface, or timeout changed. The input state is now owned by each capture: a scenario that captures a hovered row, a focused Tooltip anchor, or a value published by a later Host read must establish that state itself. `document-preview.e2e.ts`'s spreadsheet-selection read has the same class of defect and stays with its own change. diff --git a/.agents/notes/implemented/testing/2026-09-27-web-lane-assertions-name-their-input-state.zh.md b/.agents/notes/implemented/testing/2026-09-27-web-lane-assertions-name-their-input-state.zh.md new file mode 100644 index 0000000000..7b7d3bc603 --- /dev/null +++ b/.agents/notes/implemented/testing/2026-09-27-web-lane-assertions-name-their-input-state.zh.md @@ -0,0 +1,49 @@ +# Agent Note: Web lane assertions name their input state + +Status: implemented + +[English](2026-09-27-web-lane-assertions-name-their-input-state.md) | 中文 + +## Problem + +浏览器通道的三个场景在捕获 aria 区域时，golden 记录的状态只是被指针、键盘或一次进行中的 Host 读取所隐含，因此每次捕获都可能落到另一种状态上。 + +[workspace-new-session-folding](../../../../apps/web/tests/workspace-new-session-folding.e2e.ts) 捕获同一侧边栏的两份 golden。`sidebar.expected.md` 记录的是 Workspace 行显示出行操作单元格的状态，该行为由 [Rows.module.css](../../../../packages/client/ui-workspace/src/client/rows/Rows.module.css) 的 `.projectRow:hover` 提供；`first-batch.expected.md` 则以 `.sessionRow:hover` 记录第六个会话行，即该批次展开出的第一行。两次捕获因此都取决于指针所在位置，而场景自身的 “Show 11 more sessions” 点击会在指针静止时重排列表。串行自托管 master 通道在这个场景上失败时，两份 golden 的要求都没有满足——`treeitem "{{workspace}}"` 不带操作按钮，golden 记录为悬停的那一行渲染出普通的相对时间——2026-09-24 至 2026-09-27 观察到的九次失败运行全部如此。 + +[turn-tail-actions](../../../../apps/web/tests/turn-tail-actions.e2e.ts) 两次捕获聚焦后的 Copy 页脚：`running.expected.md` 记录其旁有一个 `tooltip "Copy"`，`settled.expected.md` 则不记录。只要最后一次输入来自指针，[Tooltip](../../../../packages/client/ui-primitives/src/Tooltip.tsx) 就忽略聚焦，而只有 keydown 会清除该标记，因此第一次捕获是否出现气泡，取决于场景最后一次点击之后测试框架是否按过键。 + +[plugin-install-cancel](../../../../apps/web/tests/plugin-install-cancel.e2e.ts) 在带高亮的插件卡片出现后只读一次 `data-plugin-status`。store 的 `enableInstalled` 先标记卡片，再启动由 Host 应答的目录重载，因此高亮先于重载把已启用的 bundle 写入列表即可观察：三次本地运行中状态在 `disabled` → `running` 之间用了 61 ms，失败的那次运行正是在这个窗口内读取的。 + +## Decision + +每次捕获都先确立其 golden 所记录的状态。 + +folding 场景在侧边栏捕获前悬停 Workspace 行，在 first-batch 捕获前悬停该批次展开出的第一行，两个被悬停的行都由场景确立，而不再继承 Show-more 点击周围的布局。golden、折叠配额与行渲染均不变；场景现在执行的是 golden 读者本会执行的那次悬停。 + +turn-tail 场景先用一个不移动焦点的按键清除指针标记，再聚焦 Copy 按钮，并等待 running golden 记录的气泡。settled 捕获保留普通聚焦，这正是 Stop 点击让指针拥有最后一次输入之后、其 golden 所记录的状态。 + +install-cancel 场景改为轮询卡片状态，而不再单次采样，因此该断言观察到的是高亮所先于的目录重载。高亮仍保留在定位卡片的 locator 中，因为随后推进 `2400 ms` 时钟的那步仍以它断言卡片会脱离。 + +## Alternatives considered + +**在 aria normalizer 中折叠悬停与非悬停两种渲染。** 两者陈述不同事实——一行被悬停，其余没有被悬停——且两份 golden 都在有意记录行操作单元格与相对时间。折叠它们是在删除断言而非稳定断言，这与通道中每一份有意记录带日期或带状态形式的 golden 所拒绝的取舍相同。 + +**投递空白事件并让指针停留在点击后的位置。** 批次插入时按钮随之移动，指针下的行仍由布局决定：下面的 folding 负向对照在指针位于侧边栏内、没有任何行被悬停时复现了该失败。 + +**在场景内禁用悬停样式或 tooltip 的模态规则。** 两者都是 golden 所证明的已发布渲染与交互行为；场景级覆盖将测试一个产品并不提供的页面。 + +**提高捕获超时或重试比较。** 两者都不能确立实际捕获到的是哪个状态；`captureStableAria` 本已等待连续两次快照相等，而错误的状态同样能满足它——这一限度已由 [CI 就绪与完成决策](2026-09-08-ci-readiness-and-completion.zh.md) 与 [连接与压缩 fixture 前置条件](2026-09-12-connection-and-compaction-fixture-preconditions.zh.md) 记录。 + +## Verification + +两个负向对照用已发布的断言复现了记录到的特征。folding 场景第一次捕获前改为悬停 New Session 行而非 Workspace 行时，`sidebar.expected.md` 失败：golden 记录 `treeitem "{{workspace}} Workspace actions …"`，实际得到 `treeitem "{{workspace}}"`。turn-tail 场景在聚焦 Copy 按钮前只做一次鼠标按下而不按键时不会出现气泡，running 捕获随后失败并缺少串行通道记录到的 `tooltip "Copy"`。两个对照在改动之后均通过。 + +本地按文件实测：`DSH_SNAPSHOT=replay pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/.e2e.ts` → workspace-new-session-folding 改动前 15/15、改动后 20/20，turn-tail-actions 改动前 8/8、改动后 20/20，plugin-install-cancel 改动前 12/12、改动后 20/20。通道配置 `DSH_SNAPSHOT=replay DSH_WEB_SNAPSHOT_WORKERS=16 pnpm run test:web:ci` 连续三次运行中三个文件全部通过。 + +install-cancel 场景仍带有本次改动未消除、且原因尚未定位的残余暴露：`node 24 / snapshots and artifacts` 上有两次、把该文件恢复到改动前版本后用同一通道命令运行的本地一次，都在启用点击关闭对话框后让 `plugin-install-cancel.e2e.ts:217` 的高亮卡片 locator 持续 30 s 未匹配。页面时钟已暂停，因此可排除高亮到期计时器，该等待并非与它竞争；上述三次通道运行与所有单文件运行都未复现，且尚无证据表明 store 的 `load()` 会挂起。本次改动新增的轮询覆盖的是卡片出现之后的状态读取，而不是这个 locator。 + +串行 master 通道同时失败的 WebKit 用例不是场景竞态，也不属于本次改动：`declared-reasoning.e2e.ts` 启动 Playwright 的 WebKit，通道的步骤只取浏览器本体而未安装宿主库，于是 `browserType.launch` 以 “Host system is missing dependencies to run browsers” 失败。[ci.yml](../../../../.github/workflows/ci.yml) 明确说明持久 VM 镜像拥有 Playwright 的 Linux 系统包，并且只在非自托管池随浏览器安装依赖集，因此修复镜像或该池的归属是 runner 侧的改动，而非场景改动。在开发者机器上安装 WebKit 依赖后该文件的 8 个用例全部通过。 + +## Consequences + +三个场景无论测试框架以何种状态进入，都渲染其 golden 记录的 aria，且没有任何 golden、产品界面或超时被改动。输入状态现在由每次捕获自己拥有：凡是捕获悬停行、聚焦的 Tooltip 锚点，或由后续 Host 读取发布的值的场景，都必须自行确立该状态。`document-preview.e2e.ts` 的电子表格选区读取属于同一类缺陷，仍留给它自己的改动。 diff --git a/.github/workflows/docs-pages.yml b/.github/workflows/docs-pages.yml index 8bac404b2d..6cd25b059d 100644 --- a/.github/workflows/docs-pages.yml +++ b/.github/workflows/docs-pages.yml @@ -35,7 +35,7 @@ env: jobs: build: - runs-on: ubuntu-latest + runs-on: blacksmith-8vcpu-ubuntu-2404 permissions: contents: read pages: read diff --git a/.github/workflows/sandbox.yml b/.github/workflows/sandbox.yml index 713616f3b6..f40be2a778 100644 --- a/.github/workflows/sandbox.yml +++ b/.github/workflows/sandbox.yml @@ -1,7 +1,8 @@ -# Sandbox CI: the keyless real-kernel confinement proofs. This master-only -# reference stays outside the pull-request verdict; rationale lives in +# Sandbox CI: the keyless real-kernel confinement proofs, plus the darwin +# unit-parity job (unit-darwin) that needs the matrix's macOS image. This +# master-only reference stays outside the pull-request verdict; rationale lives in # .agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md. -# A separate workflow from ci.yml because the axis is different — these jobs +# A separate workflow from ci.yml because the axis is different — the e2e jobs # fan out over OS×runner (kernel capabilities), not node versions. The Landlock # launcher is built from native/system on each Landlock leg and installed # from the same tarballs the main-repository release workflow publishes. @@ -96,14 +97,6 @@ jobs: pnpm --dir native/system run build:ts pnpm --dir native/system run build:native - # The unit suite runs on ubuntu in `checks`; this is the one darwin leg - # in the workflow, so run it here too — the platform-dependent unit - # expectations (Seatbelt path canonicalization: /tmp IS /private/tmp) - # take their darwin branch only on this runner. - - name: Unit tests (darwin parity) - if: matrix.runner == 'seatbelt' - run: pnpm run test - - name: Sandbox e2e (real kernel confinement, world-verified) # NO_COLOR: vitest force-enables ANSI color under GITHUB_ACTIONS even # without a TTY, which would thread escape codes through the summary @@ -139,3 +132,30 @@ jobs: echo "$out" [ "$status" -eq 0 ] echo "$out" | grep -qE 'Test Files[[:space:]]+1 passed \(1\)' + + # The unit suite runs on ubuntu in ci.yml's Linux jobs; macos-latest is this + # workflow's only darwin runner, so the platform-dependent unit expectations + # (Seatbelt path canonicalization: /tmp IS /private/tmp — sandbox semantics, + # hence this workflow rather than ci-master.yml) take their darwin branch only + # here. A job of its own so the seatbelt e2e leg keeps the matrix budget. The + # budget below is a completion ceiling, not a latency target: the full suite + # takes 16 minutes on a fast macos-latest runner and was under half done at + # 20 on the slowest observed. + unit-darwin: + name: unit tests (darwin parity, macos-latest) + runs-on: macos-latest + timeout-minutes: 60 + steps: + - uses: actions/checkout@v6 + + - uses: pnpm/action-setup@v4 + + - uses: actions/setup-node@v6 + with: + node-version: 24 + + - name: Install (immutable) + run: pnpm install --frozen-lockfile + + - name: Unit tests (darwin parity) + run: pnpm run test diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 3f325012a0..e08afa0c1c 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -56,7 +56,6 @@ External packages installed for runtime use or distributed inside the prebuilt b | [`@opentelemetry/api`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 | | [`@opentelemetry/api-logs`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 | | [`@opentelemetry/core`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 | -| [`@opentelemetry/exporter-logs-otlp-http`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 | | [`@opentelemetry/otlp-exporter-base`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 | | [`@opentelemetry/otlp-transformer`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 | | [`@opentelemetry/resources`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 | diff --git a/apps/cli/composition.md b/apps/cli/composition.md index e72a1f0ce6..e627d9e47d 100644 --- a/apps/cli/composition.md +++ b/apps/cli/composition.md @@ -74,6 +74,8 @@ flowchart LR cfg --> plugin_dsh_base_storage_domain plugin_dsh_base_session_projection_cache["session-projection-cache
@deepseek-ai/dsh-session-projection-cache"] cfg --> plugin_dsh_base_session_projection_cache + plugin_dsh_base_otel["otel
@deepseek-ai/dsh-otel"] + cfg --> plugin_dsh_base_otel plugin_dsh_base_session_telemetry_otel["session-telemetry-otel
@deepseek-ai/dsh-session-telemetry-otel"] cfg --> plugin_dsh_base_session_telemetry_otel plugin_dsh_base_subprocess["subprocess
@deepseek-ai/dsh-subprocess-local"] @@ -231,6 +233,7 @@ flowchart LR | `storage-json` | `@deepseek-ai/dsh-storage-json` | | `storage-domain` | `@deepseek-ai/dsh-storage-domain` | | `session-projection-cache` | `@deepseek-ai/dsh-session-projection-cache` | +| `otel` | `@deepseek-ai/dsh-otel` | | `session-telemetry-otel` | `@deepseek-ai/dsh-session-telemetry-otel` | | `subprocess` | `@deepseek-ai/dsh-subprocess-local` | | `sandbox` | `@deepseek-ai/dsh-sandbox-local` | diff --git a/apps/cli/package.json b/apps/cli/package.json index 8b9dbbac17..be98d17216 100644 --- a/apps/cli/package.json +++ b/apps/cli/package.json @@ -39,6 +39,7 @@ "@deepseek-ai/dsh-compaction-tool-result-pruner": "workspace:*", "@deepseek-ai/dsh-cordis-client-runner": "workspace:*", "@deepseek-ai/dsh-experimental-agent-team-profile": "workspace:*", + "@deepseek-ai/dsh-experimental-schedule-bundle": "workspace:*", "@deepseek-ai/dsh-fs-local": "workspace:*", "@deepseek-ai/dsh-goal": "workspace:*", "@deepseek-ai/dsh-goal-round-driver": "workspace:*", diff --git a/apps/cli/tests/desktop-host.e2e.ts b/apps/cli/tests/desktop-host.e2e.ts index e486354a33..615270aae0 100644 --- a/apps/cli/tests/desktop-host.e2e.ts +++ b/apps/cli/tests/desktop-host.e2e.ts @@ -28,7 +28,11 @@ it.each([false, true])('settles startup after parent IPC disconnect (boot failur } writeFileSync(join(root, 'package.json'), '{"type":"module"}') writeFileSync(join(modules, 'dsh-app-boot', 'package.json'), '{"type":"module","exports":"./index.js"}') - writeFileSync(join(modules, 'dsh-app-boot', 'index.js'), 'export const loadProfileDirectory = () => ({ skippedBundles: [] }); export const reportSkippedBundles = () => {}; export const loadLayeredEnv = () => ({})') + writeFileSync(join(modules, 'dsh-app-boot', 'index.js'), ` + export const loadProfileDirectory = () => ({ skippedBundles: [] }); + export const reportSkippedBundles = () => {}; + export const loadLayeredEnv = () => ({}); + `) writeFileSync(join(modules, 'dsh', 'package.json'), '{"type":"module","exports":{"./profile-boot":"./profile-boot.js"}}') writeFileSync(join(modules, 'dsh', 'profile-boot.js'), ` import { writeFileSync } from 'node:fs'; diff --git a/apps/cli/tests/profiles/web/tests/fixtures/schedule.patch.yml b/apps/cli/tests/profiles/web/tests/fixtures/schedule.patch.yml deleted file mode 100644 index fd53f05e15..0000000000 --- a/apps/cli/tests/profiles/web/tests/fixtures/schedule.patch.yml +++ /dev/null @@ -1,2 +0,0 @@ -- id: schedule - disabled: false diff --git a/apps/cli/tests/profiles/web/tests/schedule-timing.expected.e2e.ts b/apps/cli/tests/profiles/web/tests/schedule-timing.expected.e2e.ts index 0cf380636f..a6846024da 100644 --- a/apps/cli/tests/profiles/web/tests/schedule-timing.expected.e2e.ts +++ b/apps/cli/tests/profiles/web/tests/schedule-timing.expected.e2e.ts @@ -8,7 +8,8 @@ import type { DailyScheduleRecord, ScheduleCatalogEntry } from '@deepseek-ai/dsh import { expect, it } from 'vitest' import { withDefaultWeb, webGet, webRequest } from './default-web-process.ts' -const patches = [fileURLToPath(new URL('./fixtures/schedule.patch.yml', import.meta.url))] +/** The optional Schedule bundle is the switch this built-Web scenario turns on. */ +const patches = [fileURLToPath(new URL('../../../../../../packages/experimental/schedule-bundle/cordis.patch.yml', import.meta.url))] const id = 'retained-remote-task' as DailyScheduleRecord['id'] const sessionId = 'unloaded-owner' as ScheduleCatalogEntry['sessionId'] diff --git a/apps/cli/tests/profiles/web/tests/web-default-isolation.expected.e2e.ts b/apps/cli/tests/profiles/web/tests/web-default-isolation.expected.e2e.ts index a9d9821ec4..eef3fb2908 100644 --- a/apps/cli/tests/profiles/web/tests/web-default-isolation.expected.e2e.ts +++ b/apps/cli/tests/profiles/web/tests/web-default-isolation.expected.e2e.ts @@ -29,15 +29,13 @@ it('boots default Web without experimental modules, scheduling, time context, or expect(roster.plugins.length).toBeGreaterThan(roster.entries.length) expect(roster.modules.some(url => modulePackage(url) === '@deepseek-ai/dsh')).toBe(true) expect(roster.client.entries.length).toBeGreaterThan(0) - for (const name of [ - '@deepseek-ai/dsh-client-ui-sidebar-browser', - '@deepseek-ai/dsh-time-context', - '@deepseek-ai/dsh-schedule', - '@deepseek-ai/dsh-client-ui-schedule', - ]) { - const entry = roster.entries.find(entry => entry.name === name) - expect(entry, name).toBeDefined() - expect(entry!.state, name).toBeUndefined() + const browser = roster.entries.find(entry => entry.name === '@deepseek-ai/dsh-client-ui-sidebar-browser') + expect(browser).toBeDefined() + expect(browser!.state).toBeUndefined() + expect(delivered.entries.some(entry => entry.id === '@deepseek-ai/dsh-client-ui-sidebar-browser')).toBe(false) + // The optional Schedule bundle inserts these rows; the shipped composition carries none of them. + for (const name of ['@deepseek-ai/dsh-time-context', '@deepseek-ai/dsh-schedule', '@deepseek-ai/dsh-client-ui-schedule']) { + expect(roster.entries.some(entry => entry.name === name), name).toBe(false) expect(delivered.entries.some(entry => entry.id === name), name).toBe(false) } expect(experimentalRuntimeReferences(roster)).toEqual([]) diff --git a/apps/desktop-host/tests/platform-session.spec.ts b/apps/desktop-host/tests/platform-session.spec.ts index fbc26da6e1..4abc1b2055 100644 --- a/apps/desktop-host/tests/platform-session.spec.ts +++ b/apps/desktop-host/tests/platform-session.spec.ts @@ -9,6 +9,7 @@ const state: AccountView = { } class Account extends DeepSeekAccount { + getDeviceIdentity = async () => ({ osVersion: 'test-os' }) fail = false ended = Promise.withResolvers() reading = Promise.withResolvers() diff --git a/apps/desktop/README.i18n.yaml b/apps/desktop/README.i18n.yaml index 039d4701b1..93f5641fb1 100644 --- a/apps/desktop/README.i18n.yaml +++ b/apps/desktop/README.i18n.yaml @@ -3,11 +3,11 @@ # After editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write apps/desktop/README.md /deepseek-harness-desktop: - en: 45561fc0dd3a1b20 - zh: f4b03355d4bd0693 + en: b8e4f357cf330721 + zh: cdaaf35a061f41b1 /deepseek-harness-desktop/closing-the-window-and-quitting: - en: fb852f3bd70d8602 - zh: 3d2b0a8d580d7f0a + en: c323e02e3f0305fe + zh: 3c730db632136443 /deepseek-harness-desktop/key-technical-decisions: en: 069fdfd72d2ea26a zh: 76ae549d43c99bb4 @@ -15,20 +15,20 @@ en: 31cbb7452be8e1ad zh: 502ec556e2ec301e /deepseek-harness-desktop/installation-ownership: - en: 8307baf6c5b691d0 - zh: 86e46b9552017ff6 + en: d186d3cfc9597688 + zh: 5f7094355c5f562c /deepseek-harness-desktop/installation-ownership/runtime-and-plugin-activation: en: 0d11af8639977a6d zh: 86b086b12d2210d3 /deepseek-harness-desktop/develop: - en: 9b9b362a9865e763 - zh: c748901168e2db8c + en: 40d2ad4014bf445b + zh: 6a08de06df9ed042 /deepseek-harness-desktop/develop/startup-onboarding: - en: 5e2d62207a603d81 - zh: 5fb863d4906f4a67 + en: a51346b8d880ddba + zh: 7913214c1c66063c /deepseek-harness-desktop/develop/welcome-window-appearance: - en: 7220801ccc3b2e6b - zh: 042dc97976aef979 + en: ae319a496639b38d + zh: ef044103240ac9da /deepseek-harness-desktop/package: en: 4cd8a8da6977928d zh: 9f624855a2edac37 diff --git a/apps/desktop/README.md b/apps/desktop/README.md index 0f579c249b..cf780cddc6 100644 --- a/apps/desktop/README.md +++ b/apps/desktop/README.md @@ -2,6 +2,8 @@ English | [中文](README.zh.md) +Desktop analytics follows the [product collection policy](../../packages/client/product-analytics/README.md), including its live application setting. Web usage is excluded. Update installation waits for its local analytics intake before locking API admission and stopping the Host. Intake has a one-second deadline; failure does not prevent installation, and collector delivery is not awaited. + The desktop application is an Electron shell around the complete dsh Web application. An Electron RunAsNode child starts the shared profile runner, and Electron immediately loads the packaged Web entry at `dsh-app://app/`. Its shared loading page waits for Host boot injections, then starts the client without navigating to another document. Electron forwards application HTTP requests to the authenticated Web Host, dropping connection-level response headers (`transfer-encoding`, `connection`, `keep-alive`) that describe the Node fetch rather than the resource, and marking plugin bundle responses `no-store` because their per-launch revisions would only accumulate in Chromium's disk cache; WebSocket streams connect to that Host with credentials attached only for the owned application window. Node IPC carries boot injections, readiness, and shutdown. Desktop defaults to port `19387`, separate from Web’s `3080`; a `webserver.config.port` patch can override it. The first application-menu command, **About DeepSeek Harness**, opens Electron's native About panel with the application icon, product name, and installed release version. The menu follows the Desktop shell locale. On macOS, Hide, Hide Others, Show All, and Quit use localized labels; Hide and Quit include the DeepSeek Harness product name. These commands retain their native actions and shortcuts. macOS reads the icon from its application bundle, so an unpackaged development launch displays Electron's icon; Windows receives the packaged PNG. @@ -28,6 +30,8 @@ Windows keeps a tray icon for the whole run. Its tooltip is the product name, a Every ordinary quit entry — ⌘Q, the application menu, the Dock menu, the Windows tray and caption Application menu, and the quits caused by closing the mandatory-update or welcome window — asks the Host what it would interrupt. The Host answers over the private IPC channel with two facts: active tasks under the same rule as the update restart check (running agents including subagents and approval waits, queued messages, running or stopping jobs), and armed scheduled reminders reported by the `schedule` family of `workspace/session-activity` for the sessions loaded during this run. Neither fact, the quit proceeds silently. Otherwise a native message box without an owner window — hidden windows stay hidden — shows **Quit DeepSeek Harness?** with one of three localized explanations: running tasks will be interrupted, scheduled tasks will not run while the application is closed, or both. Quit is the default button and Cancel answers Esc; macOS places Cancel left of Quit, Windows places Quit left of Cancel, and the Windows task dialog shows the application icon and stays light regardless of the application theme. A Host that has not reached ready or has failed cannot run tasks, so the quit proceeds without asking. An inspection failure or a Host that misses the two-second deadline is treated as running tasks. While the box is open, another quit request joins it instead of stacking a second one (macOS also raises it; Electron exposes no handle to the Windows task dialog), the explanation does not change when work starts or ends, Quit stops the application without re-inspecting, and Cancel changes nothing. Cancelling a quit that closing the welcome window started shows the welcome window again. +The mandatory update confirmation includes the installation wait notice on Windows; macOS uses the shorter restart explanation. + The confirmation is skipped when the installer restart already confirmed task interruption, when the fatal-recovery dialog exits or restarts, when the development Restart App and Host command runs, and during operating-system shutdown, restart, or log-off: Windows sets this on the definitive session-end message; macOS sets it on the power-off notification, and because another application can still cancel that shutdown, the next focus or show of the main window clears it. Installer-owned quit cancels any pending ordinary quit decision; late inspection results and dialog answers cannot open another confirmation or repeat cleanup. A user-initiated update download that finishes while the window is hidden defers its Install and Restart confirmation until the window is shown again; the mandatory flow keeps its taskbar and Dock attention. The Windows installer and uninstaller tell a user whose application is still running to quit it from the system tray. Desktop does not enable scheduled tasks by default, so the scheduled-task explanations appear only once that feature is on; reminders fire only in loaded sessions, and unloaded sessions are neither counted nor resumed until they are opened. The tray renderer enlarges the whale by 20% around the tile center while preserving the background and aspect ratio; application and installer icons retain their original proportions. @@ -84,6 +88,8 @@ The `dsh-app://shell/` origin serves packaged update documents, scripts, and sty The product UI retains Web actions, including "Open In..." through the shared authenticated HTTP routes. Desktop uses Web's automatic directory-picker selection and initializes new profiles with the shared Web template's bundles. +Update copy preserves the complete version, including prerelease suffixes, without adding v or V. When no update is available, the dialog title reports the result and the body shows the current version. + Electron chooses typed English or Chinese shell copy from its application locale and falls back to English. The macOS application bundle declares English and Simplified Chinese in `CFBundleLocalizations`, allowing macOS to match the initial application language to the user’s preferred languages. Saved Client UI language preferences still take precedence for the main interface. On Windows, the main document's language updates desktop menus, recovery and update prompts. The repository Client UI i18n gate checks desktop sources. Windows uses a 40-DIP caption with native window controls and colors synchronized from the application palette. Localized Application and Edit entries beside the sidebar toggle open native popup menus. They mount only after the application frame publishes its shell overlay seat, and remain absent during startup loading. Application provides Check for Updates and Exit; Edit provides undo, redo, cut, copy, paste, delete, and select all by sending the corresponding keys to the focused editor, independently of custom shortcut bindings. Plugin management uses the main application's Plugins page. No separate native menu row appears on Alt. Other platforms retain their native menus. Editable fields retain keyboard commands and a context menu without shortcut labels; Chromium supplies command availability, and selected read-only text offers Copy. @@ -130,7 +136,7 @@ pnpm run start:desktop The Web counterparts are `pnpm run dev:web` and `pnpm run start:web`, documented in the [development guide](../../docs/development.md). Workspace development runs the current CLI and private Desktop Host packages under Electron RunAsNode. Plugin management and recovery use `$DSH_HOME/profiles/desktop`, separate from the disposable workspace runtime. The Host uses runtime module resolution in both development and packaged builds without creating official-package fallback links; developer-installed packages, including links, retain native priority. Use an unpacked application to exercise Electron RunAsNode, bundled pnpm, bundled dsh resources, plugin installation and repair paths. -The [native/renderer keyboard tests](tests/keyboard.spec.ts) compile in [their own Client test project](../../tsconfig.desktop-keyboard-tests.json), reached by the repository Client typecheck. Its Desktop imports are limited to Cordis-free input, persistence, IPC, browser-guest, and overlay modules. +The [native/renderer keyboard tests](tests/keyboard.spec.ts) compile as part of the repository Client typecheck. Their Desktop imports are limited to Cordis-free input, persistence, IPC, browser-guest, and overlay modules. ### Startup onboarding @@ -138,7 +144,7 @@ The API-key input starts empty and uses `autocomplete="new-password"` to ask Chr Repeated launches and `dsh://open` keep the workspace hidden until the startup credential check or a welcome action permits entry. Entering from Welcome places keyboard focus on the document without selecting a sidebar control; Tab navigation remains available. -Desktop checks configured model API-key references after the Host starts and before opening the workspace. With no configured key, the welcome window offers the [API-key page](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=2138-44626). Save and continue writes through the existing credential service using the official DeepSeek provider's configured reference, then opens the workspace. Set up later opens the workspace without saving the draft or a completion setting; the next process launch checks credentials again. Back to sign in returns to the entry and clears the unsaved key and validation message. Buttons keep their labels and block competing actions while saving or opening the workspace. The Desktop preload marker suppresses the Web credential dialog, while retaining the Models settings page and the welcome notice. +Desktop checks configured model API-key references after the Host starts and before opening the workspace. With no configured key, the welcome window offers the API-key page. Save and continue writes through the existing credential service using the official DeepSeek provider's configured reference, then opens the workspace. Set up later opens the workspace without saving the draft or a completion setting; the next process launch checks credentials again. Back to sign in returns to the entry and clears the unsaved key and validation message. Buttons keep their labels and block competing actions while saving or opening the workspace. The Desktop preload marker suppresses the Web credential dialog, while retaining the Models settings page and the welcome notice. The welcome window reads the shared `locale.preference` before it appears. An explicit English or Chinese choice wins; otherwise Desktop picks the first supported OS language and falls back to English. The main UI reads the same preference and OS language order through its isolated preload before mounting. Language changes in Settings update the shell’s current dictionary and menu; automatic selection writes no preference. The welcome window has no language selector. @@ -146,7 +152,7 @@ The browser-login waiting page offers a copy-link action for the current pending ### Welcome window appearance -The welcome window follows system appearance with the design’s Platform light/dark colors and shows the 600 × 700 [entry layout](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=2121-39334) and the API-key form, with native window controls, a draggable title area, a local brand SVG, system sans-serif fallbacks, and locally bundled Montserrat Light for non-button text. The window uses macOS menu vibrancy or Windows acrylic with the onboarding window tint: 40% white in light mode and 50% rgb(24 25 28) in dark mode. The local React welcome entry bundles React and the shared `StateDot` loading indicator with its CSS; it uses the isolated preload without loading the main Web application. The entry, sign-in status and API-key pages share a fixed bottom action row; the back-to-sign-in link sits below it. Buttons share the platform motion timings, and Reduce Motion disables their transitions. The OS owns blur strength and outer corners. macOS Reduce Transparency suppresses translucency, and Increase Contrast forces that setting on. Save and continue writes to the development credential store; Set up later opens the real workspace without saving a key or completion flag. The generated project links the declared workspace dependency closure as well as pnpm’s hoisted packages, so unhoisted configured plugins remain resolvable. [The window note](../../.agents/notes/implemented/architecture/2026-09-08-desktop-welcome-window-material.md) owns the material and onboarding decisions. +The welcome window follows system appearance with the design’s Platform light/dark colors and shows the 600 × 700 entry layout and the API-key form, with native window controls, a draggable title area, a local brand SVG, system sans-serif fallbacks, and locally bundled Montserrat Light for non-button text. The window uses macOS menu vibrancy or Windows acrylic with the onboarding window tint: 40% white in light mode and 50% rgb(24 25 28) in dark mode. The local React welcome entry bundles React and the shared `StateDot` loading indicator with its CSS; it uses the isolated preload without loading the main Web application. The entry, sign-in status and API-key pages share a fixed bottom action row; the back-to-sign-in link sits below it. Buttons share the platform motion timings, and Reduce Motion disables their transitions. The OS owns blur strength and outer corners. macOS Reduce Transparency suppresses translucency, and Increase Contrast forces that setting on. Save and continue writes to the development credential store; Set up later opens the real workspace without saving a key or completion flag. The generated project links the declared workspace dependency closure as well as pnpm’s hoisted packages, so unhoisted configured plugins remain resolvable. [The window note](../../.agents/notes/implemented/architecture/2026-09-08-desktop-welcome-window-material.md) owns the material and onboarding decisions. ## Package diff --git a/apps/desktop/README.zh.md b/apps/desktop/README.zh.md index 62e34fad48..a64cbd2246 100644 --- a/apps/desktop/README.zh.md +++ b/apps/desktop/README.zh.md @@ -2,6 +2,8 @@ [English](README.md) | 中文 +桌面埋点遵循[产品采集策略](../../packages/client/product-analytics/README.zh.md)及其动态应用配置，不包含 Web 使用情况。安装更新会等待该操作的本地埋点接收请求结束，再锁定 API 准入并停止 Host。接收请求的时限为一秒，失败不会阻止安装，也不等待收集端完成发送。 + 桌面应用是完整 dsh Web 应用外的一层 Electron 壳。Electron RunAsNode 子进程启动共享 profile runner，Electron 立即从 `dsh-app://app/` 加载打包内的 Web 入口。共享加载页等待 Host 启动注入，然后在同一文档中启动客户端。Electron 将应用 HTTP 请求转发给已认证的 Web Host，转发时丢弃描述 Node fetch 连接而非资源本身的响应头（`transfer-encoding`、`connection`、`keep-alive`），并把插件 bundle 响应标记为 `no-store`，因为其每次启动都变化的 revision 只会在 Chromium 磁盘缓存中累积；WebSocket 流连接到该 Host，仅为归属的应用窗口附加凭据。Node IPC 承载启动注入、就绪与关闭。Desktop 默认使用端口 `19387`，与 Web 的 `3080` 分开；可通过 `webserver.config.port` patch 覆盖。 应用菜单第一项“**关于 DeepSeek Harness**”打开 Electron 原生关于面板，展示应用图标、产品名称和当前安装的发布版本。菜单文案跟随桌面壳的语言。macOS 的隐藏、隐藏其他、显示全部和退出条目使用本地化文案，隐藏和退出条目包含 DeepSeek Harness 产品名称。这些条目保留原生动作和快捷键。macOS 从应用包读取图标，因此未打包的开发启动会显示 Electron 图标；Windows 使用随包分发的 PNG。 @@ -28,6 +30,8 @@ Windows 在整个运行期间常驻托盘图标。悬停提示为产品名，单 所有普通退出入口——⌘Q、应用菜单、Dock 菜单、Windows 托盘和标题栏"应用程序"菜单，以及关闭强制更新窗口或欢迎窗口引起的退出——都先向 Host 查询退出会中断什么。Host 通过私有 IPC 通道回答两项事实：与更新重启检查同一口径的运行中任务（运行中的 agent，包括子代理和等待审批的回合、排队消息、运行中或停止中的后台任务），以及本次运行中已加载会话里由 `workspace/session-activity` 的 `schedule` family 报告的已挂定时器的提醒。两项都没有时直接退出，不弹框。否则弹出一个没有父窗口的原生消息框——隐藏的窗口保持隐藏——标题为**退出 DeepSeek Harness？**，正文为三种本地化说明之一：正在运行的任务将会中断、应用关闭期间定时任务不会运行，或两者兼有。"退出"是默认按钮，Esc 等同"取消"；macOS 上"取消"在"退出"左侧，Windows 上"退出"在"取消"左侧，Windows 任务对话框显示应用图标且不跟随应用主题、始终为浅色。Host 尚未就绪或已失败时不可能有任务在跑，直接退出。查询失败或 Host 超过两秒截止时间未答复，按运行中任务处理。弹框打开期间，再次请求退出只会并入同一弹框而不叠加新弹框（macOS 上还会把它提到前面；Electron 不暴露 Windows 任务对话框的句柄）；任务开始或结束不会改变文案；点"退出"不再重新查询即停止应用；点"取消"不发生任何变化。取消由关闭欢迎窗口引起的退出时，欢迎窗口会重新显示。 +强制更新的安装确认在 Windows 上额外显示等待提示，macOS 只显示简短的重启说明。 + 以下情况跳过确认：安装更新的重启已确认过任务中断、致命错误恢复对话框中的退出或重启、开发版"重启应用与 Host"命令，以及操作系统关机、重启或注销：Windows 在确定性的会话结束消息上设置该状态；macOS 在关机通知上设置，而其他应用仍可能取消这次关机，因此主窗口下一次获得焦点或显示时会清除它。安装器接管退出时会取消尚未结束的普通退出决策；晚到的查询结果和弹框答复不会再次打开确认框或重复清理。窗口隐藏期间完成的用户主动发起的更新下载，把"安装并重启"确认推迟到窗口再次显示时；强制更新流程沿用其任务栏和 Dock 提醒。Windows 安装程序和卸载程序在应用仍在运行时提示用户先在系统托盘中退出。Desktop 默认未开启定时任务，定时任务的说明只在该功能开启后出现；提醒只在已加载的会话中触发，未加载的会话既不计入，也要等到打开后才会继续。 托盘渲染器以底板中心为基准将鲸鱼放大 20%，保留背景和宽高比；应用和安装器图标保持原有比例。 @@ -86,6 +90,8 @@ Electron 拥有 `$DSH_HOME/profiles/desktop`。其 `dependencies` 包含 pnpm 产品 UI 保留 Web 操作，包括通过共享认证 HTTP 路由执行的“打开方式…”。Desktop 使用 Web 的自动目录选择机制，并以共享 Web 模板的 bundle 列表初始化新 profile。 +升级文案完整展示版本号（包括预发布后缀），不额外添加 v 或 V。无可用更新时，弹窗标题显示检查结果，正文显示当前版本。 + Electron 根据应用语言选择类型化的英文或中文 shell 文案，并回退到英文。macOS 应用包通过 `CFBundleLocalizations` 声明支持英语和简体中文，让 macOS 根据用户的首选语言匹配初始应用语言。主界面仍优先使用已保存的 Client UI 语言偏好。在 Windows 上，主文档的语言会更新桌面菜单、恢复与更新提示。仓库 Client UI i18n 检查覆盖桌面端源码。 Windows 使用 40 DIP 顶栏，保留原生窗口按钮，颜色随应用调色板同步。侧栏开关旁的本地化“应用”和“编辑”入口打开原生弹出菜单。仅当应用框架发布 shell overlay 席位后才挂载菜单，启动加载期间不显示。“应用”提供检查更新和退出；“编辑”向当前编辑器发送对应按键，提供撤销、重做、剪切、复制、粘贴、删除和全选，不受自定义快捷键绑定影响。插件管理使用主应用的“插件”页面。按 Alt 不会出现额外的原生菜单行。其他平台保留原生菜单。可编辑区域保留快捷键和不带快捷键标注的右键菜单；命令可用状态由 Chromium 提供，选中的只读文本提供“复制”命令。 @@ -132,7 +138,7 @@ pnpm run start:desktop Web 侧的对应命令是 `pnpm run dev:web` 与 `pnpm run start:web`，见[开发指南](../../docs/development.zh.md)。Workspace 开发使用 Electron RunAsNode 运行当前 CLI 与私有 Desktop Host 包，插件管理和恢复使用 `$DSH_HOME/profiles/desktop`，与一次性工作区运行时分离。Host 在开发与打包构建中都使用 runtime 模块解析，不创建官方包的 fallback 链接；开发者安装的包（包括链接）保留原生优先级。需要验证 Electron RunAsNode、内置 pnpm、内置 dsh 资源、插件安装和修复时，应运行未封装安装器的应用目录。 -[原生输入与渲染进程键盘测试](tests/keyboard.spec.ts)在[独立的 Client 测试项目](../../tsconfig.desktop-keyboard-tests.json)中编译，由仓库 Client 类型检查纳入。它只导入不依赖 Cordis 的 Desktop 输入、持久化、IPC、浏览器 guest 和蒙层模块。 +[原生输入与渲染进程键盘测试](tests/keyboard.spec.ts)直接纳入仓库 Client 类型检查。它只导入不依赖 Cordis 的 Desktop 输入、持久化、IPC、浏览器 guest 和蒙层模块。 ### 启动引导 @@ -140,7 +146,7 @@ API Key 输入框初始为空，并通过 `autocomplete="new-password"` 请求 C 重复启动和 `dsh://open` 会保持工作区隐藏，直到启动凭据检查或欢迎页操作允许进入。从 Welcome 进入时，键盘焦点落在文档上，不选中侧边栏控件；Tab 导航仍可使用。 -Desktop 在 Host 启动后、打开工作区前检查模型 API Key 引用是否已配置。没有已配置的密钥时，欢迎窗口提供 [API Key 页面](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=2138-44626)。“保存并继续”通过现有凭证服务写入 DeepSeek 官方提供方配置的引用，然后打开工作区。“稍后配置”打开工作区，但不保存草稿或完成标记；下次进程启动时会重新检查凭证。“返回登录”回到入口并清空未保存的密钥和校验提示。保存或打开工作区期间，按钮保持原文案并禁用竞争操作。Desktop preload 标记使 Web 凭证弹窗不再显示，同时保留模型设置页和欢迎须知。 +Desktop 在 Host 启动后、打开工作区前检查模型 API Key 引用是否已配置。没有已配置的密钥时，欢迎窗口提供 API Key 页面。“保存并继续”通过现有凭证服务写入 DeepSeek 官方提供方配置的引用，然后打开工作区。“稍后配置”打开工作区，但不保存草稿或完成标记；下次进程启动时会重新检查凭证。“返回登录”回到入口并清空未保存的密钥和校验提示。保存或打开工作区期间，按钮保持原文案并禁用竞争操作。Desktop preload 标记使 Web 凭证弹窗不再显示，同时保留模型设置页和欢迎须知。 欢迎窗口在显示前读取共享的 `locale.preference`。用户明确选择的英文或中文优先；否则 Desktop 按系统语言顺序匹配支持的语言，并以英文兜底。主界面在挂载前通过隔离 preload 读取同一偏好和系统语言顺序。在设置中切换语言会更新桌面壳的当前词典和菜单；自动选择不会写入偏好。欢迎窗口不提供语言切换入口。 @@ -148,7 +154,7 @@ Desktop 在 Host 启动后、打开工作区前检查模型 API Key 引用是否 ### 欢迎窗口外观 -欢迎窗口使用设计稿的 Platform light/dark 颜色跟随系统外观，展示 600 × 700 的[入口布局](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=2121-39334)和 API Key 表单，包含原生窗口控件、可拖动标题区域、本地品牌 SVG、系统无衬线字体回退，以及非按钮文字使用的本地 Montserrat Light 字体。窗口使用 macOS menu vibrancy 或 Windows acrylic，叠加 onboarding 的窗口背景色：浅色模式为 40% 白色，深色模式为 50% rgb(24 25 28)。本地 React 欢迎入口将 React、公共 `StateDot` 加载指示器及其 CSS 一起打包；它通过隔离 preload 工作，不加载主 Web 应用。入口、登录状态和 API Key 页面共用固定的底部操作行；“返回登录”链接位于操作行下方。按钮共用平台的过渡时序，开启“减少动态效果”会禁用过渡。操作系统控制模糊强度和外部圆角。macOS 的“降低透明度”会抑制半透明效果，“增强对比度”会强制开启该设置。“保存并继续”写入开发环境的凭证存储；“稍后配置”打开真实工作区，不保存密钥或完成标记。生成的开发项目同时链接已声明的 workspace 依赖闭包和 pnpm 提升的包，因此未提升的配置插件仍能解析。[窗口记录](../../.agents/notes/implemented/architecture/2026-09-08-desktop-welcome-window-material.zh.md)负责材质与引导决策。 +欢迎窗口使用设计稿的 Platform light/dark 颜色跟随系统外观，展示 600 × 700 的入口布局和 API Key 表单，包含原生窗口控件、可拖动标题区域、本地品牌 SVG、系统无衬线字体回退，以及非按钮文字使用的本地 Montserrat Light 字体。窗口使用 macOS menu vibrancy 或 Windows acrylic，叠加 onboarding 的窗口背景色：浅色模式为 40% 白色，深色模式为 50% rgb(24 25 28)。本地 React 欢迎入口将 React、公共 `StateDot` 加载指示器及其 CSS 一起打包；它通过隔离 preload 工作，不加载主 Web 应用。入口、登录状态和 API Key 页面共用固定的底部操作行；“返回登录”链接位于操作行下方。按钮共用平台的过渡时序，开启“减少动态效果”会禁用过渡。操作系统控制模糊强度和外部圆角。macOS 的“降低透明度”会抑制半透明效果，“增强对比度”会强制开启该设置。“保存并继续”写入开发环境的凭证存储；“稍后配置”打开真实工作区，不保存密钥或完成标记。生成的开发项目同时链接已声明的 workspace 依赖闭包和 pnpm 提升的包，因此未提升的配置插件仍能解析。[窗口记录](../../.agents/notes/implemented/architecture/2026-09-08-desktop-welcome-window-material.zh.md)负责材质与引导决策。 ## 打包 diff --git a/apps/desktop/package.json b/apps/desktop/package.json index cc0ce4f064..81c8059d55 100644 --- a/apps/desktop/package.json +++ b/apps/desktop/package.json @@ -75,6 +75,7 @@ "vite": "^6.0.0", "@deepseek-ai/dsh-client-ui-theme": "workspace:*", "@deepseek-ai/dsh-client-shortcuts": "workspace:*", - "@deepseek-ai/dsh-atomic-write": "workspace:*" + "@deepseek-ai/dsh-atomic-write": "workspace:*", + "@deepseek-ai/dsh-client-product-analytics": "workspace:*" } } diff --git a/apps/desktop/renderer/mandatory-update.css b/apps/desktop/renderer/mandatory-update.css index 89cf0cf0d5..591a82b6ab 100644 --- a/apps/desktop/renderer/mandatory-update.css +++ b/apps/desktop/renderer/mandatory-update.css @@ -9,4 +9,8 @@ #copy { min-height: 32px; padding: 3px 0; background: transparent; color: #4d6bfe; font-size: 12px; } #copy-message { color: #d93025 !important; } #manual-copy { display: block; margin-top: 8px; } -#progress { display: block; width: 100%; height: 4px; margin-top: 12px; border: 0; accent-color: #4d6bfe; } +#progress { display: block; width: 100%; height: 4px; margin-top: 12px; border: 0; appearance: none; -webkit-appearance: none; background: #e6e7eb; accent-color: #0f1115; } + +#progress::-webkit-progress-bar { background: #e6e7eb; } +#progress::-webkit-progress-value { background: #0f1115; } +#progress::-moz-progress-bar { background: #0f1115; } diff --git a/apps/desktop/src/account-backend.ts b/apps/desktop/src/account-backend.ts index 889b4371bc..770d3e4e9d 100644 --- a/apps/desktop/src/account-backend.ts +++ b/apps/desktop/src/account-backend.ts @@ -67,9 +67,13 @@ export interface DesktopAccountBackend { * @param listener - state recipient. * @param failed - stream failure recipient. * @param expired - live credential-expiry recipient. + * @param onAnalyticsEnabledChanged - optional Desktop collection-policy recipient; disconnected streams publish false. * @returns stream disposer. */ - watch(listener: (state: AccountView) => void, failed: () => void, expired: () => void): () => void + watch( + listener: (state: AccountView) => void, failed: () => void, expired: () => void, + onAnalyticsEnabledChanged?: (enabled: boolean) => void, + ): () => void } /** @@ -86,19 +90,21 @@ export function desktopAccountBackend(origin: string, invoke: AccountInvoke, coo state: () => call('getState'), start: client => call('startSignIn', { client, callbackOrigin: new URL(origin).origin, loginSource: 'desktop' }), cancel: attemptId => call('cancelSignIn', { attemptId }), signOut: client => call('signOut', { client }), - watch(listener, failed, expired) { + watch(listener, failed, expired, onAnalyticsEnabledChanged) { let closed = false let socket: WebSocket | undefined let retry: ReturnType | undefined const connect = (): void => { const streamId = randomUUID() const expiryStreamId = randomUUID() + const analyticsPolicyStreamId = randomUUID() void cookies().then((cookie) => { if (closed) return const url = new URL(REMOTE_STREAM_MUX_PATH, origin) url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:' socket = new WebSocket(url, { headers: { cookie, origin }, maxPayload: 65_536 }) socket.on('open', () => { + if (onAnalyticsEnabledChanged !== undefined) socket?.send(JSON.stringify({ type: 'open', streamId: analyticsPolicyStreamId, endpoint: 'productAnalytics/watchPolicy', payload: { args: {} } })) socket?.send(JSON.stringify({ type: 'open', streamId: expiryStreamId, endpoint: 'account/watchExpiry', payload: { args: {} } })) socket?.send(JSON.stringify({ type: 'open', streamId, endpoint: 'account/watch', payload: { args: {} } })) }) @@ -106,6 +112,11 @@ export function desktopAccountBackend(origin: string, invoke: AccountInvoke, coo try { const bytes = Array.isArray(data) ? Buffer.concat(data) : Buffer.isBuffer(data) ? data : Buffer.from(data) const frame = parseRemoteStreamServerMessage(bytes.toString('utf8')) + if (frame.streamId === analyticsPolicyStreamId) { + if (frame.type === 'item' && typeof frame.value === 'boolean') onAnalyticsEnabledChanged?.(frame.value) + else onAnalyticsEnabledChanged?.(false) + return + } if (frame.streamId === expiryStreamId && frame.type === 'item' && frame.value === 'session-expired') { expired(); return } if (frame.streamId !== streamId) throw new Error('desktop account: unexpected stream') if (frame.type === 'item') listener(accountView(frame.value)) @@ -113,11 +124,11 @@ export function desktopAccountBackend(origin: string, invoke: AccountInvoke, coo } catch { socket?.close() } }) socket.on('error', () => { socket?.close() }) - socket.on('close', () => { if (!closed) { failed(); retry = setTimeout(connect, 1000) } }) - }).catch(() => { if (!closed) { failed(); retry = setTimeout(connect, 1000) } }) + socket.on('close', () => { if (!closed) { onAnalyticsEnabledChanged?.(false); failed(); retry = setTimeout(connect, 1000) } }) + }).catch(() => { if (!closed) { onAnalyticsEnabledChanged?.(false); failed(); retry = setTimeout(connect, 1000) } }) } connect() - return () => { closed = true; clearTimeout(retry); socket?.close() } + return () => { closed = true; onAnalyticsEnabledChanged?.(false); clearTimeout(retry); socket?.close() } }, } } diff --git a/apps/desktop/src/client/WelcomePage.tsx b/apps/desktop/src/client/WelcomePage.tsx index 8fcde7768a..b367061732 100644 --- a/apps/desktop/src/client/WelcomePage.tsx +++ b/apps/desktop/src/client/WelcomePage.tsx @@ -19,6 +19,7 @@ export function Welcome({ api }: { api: WelcomeApi }) { const [expiryNotice, setExpiryNotice] = useState(false) const [page, setPage] = useState('entry') const pageRef = useRef('entry') + const visiblePage = useRef('entry') const [attempt, setAttempt] = useState(null) const attemptRef = useRef(null) const [starting, setStarting] = useState(false) @@ -69,12 +70,14 @@ export function Welcome({ api }: { api: WelcomeApi }) { }, [api, m.welcomeTitle]) useEffect(() => { + if (page === 'entry' && visiblePage.current !== 'entry') void api.analytics?.('auth_page_view', {}) + visiblePage.current = page if (page === 'key') input.current?.focus() else if (page === 'entry' && focusEntry.current) { focusEntry.current = false keyButton.current?.focus() } - }, [page]) + }, [page, api]) useEffect(() => { if (copyState !== 'copied' && copyState !== 'failed') return @@ -85,6 +88,7 @@ export function Welcome({ api }: { api: WelcomeApi }) { async function saveKey(event: FormEvent) { event.preventDefault() if (busyRef.current) return + void api.analytics?.('api_key_save_click', {}) const value = draft.trim() if (!/^[\x21-\x7e]+$/.test(value) || /^[A-Z][A-Z0-9_]*=[^=]/.test(value) || ((value.startsWith('"') || value.startsWith("'") || value.charCodeAt(0) === 96) && value.at(-1) === value[0])) { @@ -198,15 +202,15 @@ export function Welcome({ api }: { api: WelcomeApi }) { - - + + {inputSentence === null @@ -925,37 +985,70 @@ function InstallDialog({ style={registryPosition ?? { visibility: 'hidden', left: 0, top: 0 }} data-install-registry aria-label={t('registryLegend')} + onKeyDown={(event) => { + if (event.key !== 'Tab' || event.ctrlKey || event.altKey || event.metaKey || event.nativeEvent.isComposing) return + event.preventDefault() + event.stopPropagation() + const radio = event.currentTarget.querySelector('input[type="radio"]:checked') + const field = registryCustomRef.current + if (event.shiftKey && event.target === field) radio?.focus() + else if (!event.shiftKey && event.target !== field) field?.focus() + else { + onToggleRegistry() + registryToggleRef.current?.focus() + } + }} > {offeredRegistries(install.registries).map((registry) => { const checked = choice.kind === 'offered' && choice.registry === registry return ( ) })} -
+
{ + // Keep label activation from moving focus back to the radio. + if (!(event.target instanceof HTMLInputElement)) event.preventDefault() + registryCustomRef.current?.focus() + }}> { + if (pointerModality() && choice.kind !== 'custom') onChooseRegistry({ kind: 'custom', url: customRegistryDraft }) + }} onChange={(event) => { onChooseRegistry({ kind: 'custom', url: event.currentTarget.value }) }} - onKeyDown={(event) => { if (event.key === 'Enter' && !empty) onRun() }} + onCompositionStart={registryComposition.onCompositionStart} + onCompositionEnd={registryComposition.onCompositionEnd} + onBlur={registryComposition.onBlur} + onKeyDown={(event) => { + if (registryComposition.isComposing(event.nativeEvent)) return + if (event.key === 'Enter' && !empty) onRun() + }} /> {install.registryError ? @@ -1168,7 +1261,7 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode { const timer = setTimeout(clearHighlight, HIGHLIGHT_MS) return () => { clearTimeout(timer) } }, [highlight, clearHighlight]) - const noticeLine = state.notice === null ? null : noticeText(state.notice, t) + const noticeLine = state.notice === null || state.notice.kind === 'refresh-failed' ? null : noticeText(state.notice, t) // The page manages what the person installed, what the installation ships for them to switch on, and a // selected name the Host cannot read; the installation's other bundles are inspected in the Settings @@ -1178,6 +1271,7 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode { const mine = listed.filter(pkg => pkg.installed || !pkg.optional) const official = listed.filter(pkg => pkg.optional && !pkg.installed) const loaded = state.status === 'ready' || state.status === 'error' + const refreshing = state.refreshStatus === 'refreshing' const openPkg = view.kind === 'package' || view.kind === 'row' ? listed.find(pkg => pkg.name === view.name) : undefined const openItem = view.kind === 'item' ? ledger.items.find(item => item.id === view.id) : undefined const openRow = view.kind === 'row' && openPkg !== undefined ? openPkg.rows.find(row => row.rowId === view.rowId) : undefined @@ -1224,7 +1318,7 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode { ) return ( -
+
{showsCards ? (
@@ -1233,9 +1327,13 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode {

{t('intro')}

- + + + @@ -1243,11 +1341,7 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode { ) : null} - {showsCards && state.status === 'loading' ? ( -

- {t('loading')} -

- ) : null} + {showsCards && state.status === 'loading' ? : null} {showsCards && state.status === 'unavailable' ? (

{t('unavailable')} @@ -1264,11 +1358,11 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode { onDone={props.dismissNotice} /> )} - {!showsCards && state.status === 'error' + {!showsCards && state.status === 'error' && !refreshing ? (

- {t('error')} + {t(state.refreshStatus === 'failed' ? 'refreshError' : 'error')}

@@ -1317,11 +1411,11 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode { {renderGroup('bundles', t('bundlesTitle'), mine.map(packageCard))} {/* A failed package read trails the groups it left incomplete: right under Official on a first-load failure, and after the kept cards when a refresh fails over stale data. */} - {state.status === 'error' + {state.status === 'error' && !refreshing ? (

- {t('error')} + {t(state.refreshStatus === 'failed' ? 'refreshError' : 'error')}

diff --git a/packages/client/ui-plugin-manager/src/client/PluginRefreshToast.tsx b/packages/client/ui-plugin-manager/src/client/PluginRefreshToast.tsx new file mode 100644 index 0000000000..b573026f52 --- /dev/null +++ b/packages/client/ui-plugin-manager/src/client/PluginRefreshToast.tsx @@ -0,0 +1,32 @@ +/** Refresh failure feedback hosted outside the Plugins panel's lifetime. */ +import type { ReactNode } from 'react' +import { IconWarningOutlineRegular, Toast } from '@deepseek-ai/dsh-client-ui-primitives' +import type { InjectFace, PropsLocale } from '@deepseek-ai/dsh-client-ui-slots' +import type { PluginManagerFace } from './manager-store.ts' +import { noticeText } from './presentation.ts' + +/** The controller's shared notice source and dismissal action. */ +export type PluginRefreshToastFace = Pick & { + hooks: Pick +} + +/** Render inputs bound from the shared controller and plugin dictionary. */ +export type PluginRefreshToastProps = InjectFace & PropsLocale<'pluginManager'> + +/** + * Display refresh failures even after navigation leaves the Plugins panel. + * @param props - shared notice hook, dismissal action, and locale seat. + * @returns the refresh failure toast, or null for other notices. + */ +export function PluginRefreshToast({ usePluginManager, dismissNotice, t }: PluginRefreshToastProps): ReactNode { + const notice = usePluginManager(state => state.notice) + if (notice?.kind !== 'refresh-failed') return null + return ( + } + onDone={dismissNotice} + /> + ) +} diff --git a/packages/client/ui-plugin-manager/src/client/index.ts b/packages/client/ui-plugin-manager/src/client/index.ts index 0bceeabe9d..a568db4666 100644 --- a/packages/client/ui-plugin-manager/src/client/index.ts +++ b/packages/client/ui-plugin-manager/src/client/index.ts @@ -6,7 +6,7 @@ * A plugin that carries its own configuration renders it on this page through * the slots the page declares (`slot-contract.ts`). */ - +import type {} from '@deepseek-ai/dsh-client-product-analytics/client' import type {} from '@deepseek-ai/dsh-client-locale/client' import type { Context as ClientContext } from '@deepseek-ai/cordis' // Type-only: the root `main` keyed slot the page registers into, declared by @@ -21,6 +21,7 @@ import type {} from '@deepseek-ai/dsh-api-remotes/client' // through the owning package's client-safe types subpath). import type {} from '@deepseek-ai/dsh-plugin-manager/types' import { PluginManagerPage } from './PluginManagerPage.tsx' +import { PluginRefreshToast, type PluginRefreshToastFace } from './PluginRefreshToast.tsx' import { PluginsPanelIcon } from './PluginsPanelIcon.tsx' import { configLedgerSource } from './config-ledger.ts' import { PluginManagerController } from './manager-store.ts' @@ -97,6 +98,14 @@ export function apply(ctx: ClientContext): void { // the page's own; a plugin's configuration arrives through the slots the // page declares here, so the page never names a configurable plugin. const configLedger = configLedgerSource(ctx) + const face = controller.inject(configLedger, text => ctx.locale.resolveText(text)) + ctx.slots.inject('shell.overlay', () => ctx.slots.register({ + name: 'shell.overlay', id: 'plugin-manager.refresh-toast', locale: NS, + inject: (): PluginRefreshToastFace => ({ + hooks: { pluginManager: face.hooks.pluginManager }, + dismissNotice: face.dismissNotice, + }), + }, PluginRefreshToast)) ctx.slots.inject('main', function* () { const handle = createNavigationStore(), instance = handle.create() const store: typeof handle = { ...handle, create: () => instance } @@ -105,7 +114,7 @@ export function apply(ctx: ClientContext): void { key: PANEL_ID, locale: NS, store, - inject: () => controller.inject(configLedger, text => ctx.locale.resolveText(text)), + inject: () => face, children: { 'plugins.item': { kind: 'list', scope: 'root' }, 'plugins.bundle.activation': { kind: 'keyed', scope: 'root' }, diff --git a/packages/client/ui-plugin-manager/src/client/locales.ts b/packages/client/ui-plugin-manager/src/client/locales.ts index 3c4fb304f0..e28336d4e6 100644 --- a/packages/client/ui-plugin-manager/src/client/locales.ts +++ b/packages/client/ui-plugin-manager/src/client/locales.ts @@ -10,6 +10,7 @@ export const zh = { unavailable: '本部署没有可管理的 profile，无法安装或启停插件。', retry: '重试', refresh: '刷新', + refreshError: '刷新失败，请重试', empty: '还没有安装任何插件。', addPlugin: '添加插件', restartNotice: '更改将在下次启动生效', @@ -48,11 +49,11 @@ export const zh = { installTitle: '添加插件', installDescription: '输入插件的包名、GitHub 仓库地址或本地目录路径。', installSpecLabel: '包名或地址', - installSpecPlaceholder: '例如 @deepseek-ai/dsh-subagent-codex', + installSpecPlaceholder: '例如 dsh-plugin-whale-pet', installGuideToggle: '插件安装引导和示例', installGuideHide: '收起引导', installGuideIdTitle: '包名', - installGuideIdExample: '@deepseek-ai/dsh-subagent-codex', + installGuideIdExample: 'dsh-plugin-whale-pet', installGuideIdHint: '插件包名即 npm 包名（如 dsh-xxx 或 @作者/插件名），社区插件的 README 安装命令中 dsh plugin add 或 pnpm add 之后的部分。', installGuideGitTitle: 'GitHub 仓库地址', installGuideGitExample: 'https://github.com/author/dsh-plugin', @@ -69,10 +70,9 @@ export const zh = { registryDefault: '默认安装源', registryOfficial: 'npm 官方源', registryNpmmirror: '中国大陆镜像源', - registryWithHost: '{name}（{host}）', registryCustom: '自定义地址', registryCustomPlaceholder: 'https://npm.example.com/', - registryCustomHint: '公司内网或私有 npm 源；需要登录的源，把凭据放在本机的 ~/.npmrc 里', + registryCustomHint: '填写内网或私有 npm 源地址，以 http:// 或 https:// 开头。若为需要登录的源，请把凭据放在本机的 ~/.npmrc 里。', registryCustomInvalid: '请输入以 http:// 或 https:// 开头的地址', registryListSeparator: '、', installRun: '安装', @@ -203,6 +203,7 @@ export const en = { unavailable: 'This deployment runs without a manageable profile, so plugins cannot be installed or switched here.', retry: 'Retry', refresh: 'Refresh', + refreshError: 'Refresh failed. Please try again.', empty: 'No plugins are installed yet.', addPlugin: 'Add plugin', restartNotice: 'The change takes effect at the next start', @@ -241,11 +242,11 @@ export const en = { installTitle: 'Add plugin', installDescription: 'Enter the plugin\'s package name, GitHub repository address, or local directory path.', installSpecLabel: 'Package name or address', - installSpecPlaceholder: 'for example @deepseek-ai/dsh-subagent-codex', + installSpecPlaceholder: 'for example dsh-plugin-whale-pet', installGuideToggle: 'Install guide and examples', installGuideHide: 'Hide the guide', installGuideIdTitle: 'Package name', - installGuideIdExample: '@deepseek-ai/dsh-subagent-codex', + installGuideIdExample: 'dsh-plugin-whale-pet', installGuideIdHint: 'The plugin package name is the npm package name (like dsh-xxx or @author/plugin): the part after dsh plugin add or pnpm add in a community plugin\'s README install command.', installGuideGitTitle: 'GitHub repository address', installGuideGitExample: 'https://github.com/author/dsh-plugin', @@ -262,10 +263,9 @@ export const en = { registryDefault: 'Default registry', registryOfficial: 'Official npm registry', registryNpmmirror: 'Mainland China mirror', - registryWithHost: '{name} ({host})', registryCustom: 'Custom address', registryCustomPlaceholder: 'https://npm.example.com/', - registryCustomHint: 'A company or private npm registry; for one that needs a login, keep the credentials in ~/.npmrc on this machine', + registryCustomHint: 'Enter an internal or private npm registry address starting with http:// or https://. If it requires a login, store the credentials in ~/.npmrc on this machine.', registryCustomInvalid: 'Enter an address starting with http:// or https://', registryListSeparator: ', ', installRun: 'Install', diff --git a/packages/client/ui-plugin-manager/src/client/manager-store.ts b/packages/client/ui-plugin-manager/src/client/manager-store.ts index ab1c3aa038..2f319d01ea 100644 --- a/packages/client/ui-plugin-manager/src/client/manager-store.ts +++ b/packages/client/ui-plugin-manager/src/client/manager-store.ts @@ -1,3 +1,4 @@ +import { sanitizeInstallInput } from './sanitize-install-input.ts' /** * The plugin manager's state: the Host's bundles joined with its plugin * entries, the action in flight, the install run, and the confirmation an @@ -5,7 +6,7 @@ * after each action and after every `plugin-manager/changed` event, so a * change made on another surface shows here without a manual refresh. */ - +import type {} from '@deepseek-ai/dsh-client-product-analytics/client' import { randomUUID } from '@deepseek-ai/dsh-util-crypto' import type { Context as ClientContext } from '@deepseek-ai/cordis' import type { @@ -41,6 +42,7 @@ export type ManagerNotice = | { readonly kind: 'restart'; readonly packageName: string; readonly seq: number } | { readonly kind: 'overridden'; readonly packageName: string; readonly seq: number } | { readonly kind: 'cancelled'; readonly seq: number } + | { readonly kind: 'refresh-failed'; readonly seq: number } | { readonly kind: 'install'; readonly outcome: 'done' | 'failed' | 'unconfirmed' | 'applying' | 'unknown'; readonly seq: number } | { readonly kind: 'failed' @@ -105,6 +107,9 @@ export type RegistryChoice = /** The choice shown until the Host has said which registry it asks first: the one pnpm's own configuration names. */ const OFFICIAL_REGISTRY: RegistryChoice = { kind: 'offered', registry: null } +/** Hold the manual-refresh spinner at least this long so a fast read does not flash it. */ +const REFRESH_SPINNER_MIN_MS = 400 + /** * The registry a choice asks, as the Host's install plan compares registries: pnpm's own configuration stands for * the URL it names, once the Host has read it. @@ -269,6 +274,12 @@ export interface ConfirmState { export interface PluginManagerState { /** `unavailable` when the Host runs without a managed profile; `error` keeps the last packages. */ readonly status: 'idle' | 'loading' | 'ready' | 'error' | 'unavailable' + /** + * Manual refresh feedback: `refreshing` until reads settle and the 400 ms minimum elapses; + * `failed` after a failed refresh without cached inventory; otherwise `idle`, including + * cached refresh failures reported by toast. Background reads do not start the spinner. + */ + readonly refreshStatus: 'idle' | 'refreshing' | 'failed' readonly packages: readonly PackageView[] /** Package names and row keys with an action crossing the wire. */ readonly busy: readonly string[] @@ -492,11 +503,14 @@ export class PluginManagerController { private rerun = false private generation = 0 private disposed = false + /** A successful managed-profile read remains usable even when it returned no bundles. */ + private hasCachedInventory = false private pendingConfirm: (() => Promise) | undefined /** Cancels the check the dialog has in flight. */ private inspectAbort: AbortController | undefined private request: InstallRequest | undefined private noticeSeq = 0 + private analyticsAttempt: { input: string; started: number } | undefined private registryRead: RegistryRead | undefined /** The registry last used from this browser, kept across dialogs and page loads; null until one was used. */ private readonly registryMemory: SnapshotStore = createSnapshotStore(null, { @@ -510,7 +524,7 @@ export class PluginManagerController { private readonly ctx: ClientContext, ) { this.store = createSnapshotStore({ - status: 'idle', packages: [], busy: [], notice: null, + status: 'idle', refreshStatus: 'idle', packages: [], busy: [], notice: null, install: IDLE_INSTALL, confirm: null, highlight: null, }) } @@ -543,8 +557,9 @@ export class PluginManagerController { hooks: { pluginManager: this.store, configLedger, configurations: this.ctx.configForms.describe() }, configForm: id => this.ctx.configForms.get(id), ensure: () => { if (this.getSnapshot().status === 'idle') void this.load() }, - refresh: () => { void this.load() }, + refresh: () => { void this.refresh() }, openInstall: () => { + this.ctx.get('productAnalytics')?.track('plugin_add_button_click', {}) const install = this.getSnapshot().install if (install.requestId === undefined) { // A new dialog starts from the registry last used here and reads what the Host offers; a hidden install reopens as it is. @@ -563,6 +578,7 @@ export class PluginManagerController { void this.cancelInstall() return } + if (this.getSnapshot().install.phase === 'checking') this.finishAnalytics('cancelled') this.abortInspect() this.registryRead = undefined this.patch({ install: IDLE_INSTALL }) @@ -604,11 +620,14 @@ export class PluginManagerController { clearHighlight: () => { if (this.getSnapshot().highlight !== null) this.patch({ highlight: null }) }, setEnabled: (packageName, enabled) => { void this.run(packageName, { packageName, action: enabled ? 'enable' : 'disable' }, async () => { - this.applied(await this.ctx.remote.pluginManager.setBundleEnabled(packageName, enabled), packageName) + const result = await this.ctx.remote.pluginManager.setBundleEnabled(packageName, enabled) + this.applied(result, packageName) + if (result.ok && (result.value.application === 'applied' || result.value.application === 'restart-required')) this.trackToggle(packageName, enabled) }) }, uninstall: (packageName) => { this.pendingConfirm = () => this.run(packageName, { packageName, action: 'uninstall' }, async () => { + this.ctx.get('productAnalytics')?.track('confirm_uninstall_plugin', { plugin_name: packageName }) this.applied(await this.ctx.remote.pluginManager.removeBundle(packageName), packageName) }) this.patch({ confirm: { action: 'uninstall', packageName } }) @@ -617,7 +636,9 @@ export class PluginManagerController { cancelConfirm: () => { this.pendingConfirm = undefined; this.patch({ confirm: null }) }, setRowEnabled: (entryId, enabled) => { void this.run(rowKey(entryId), { packageName: entryId, action: enabled ? 'rowEnable' : 'rowDisable' }, async () => { - this.applied(await this.ctx.remote.pluginManager.setPluginEnabled(entryId, enabled), entryId) + const result = await this.ctx.remote.pluginManager.setPluginEnabled(entryId, enabled) + this.applied(result, entryId) + if (result.ok && (result.value.application === 'applied' || result.value.application === 'restart-required')) this.trackToggle(entryId, enabled, true) }) }, dismissNotice: () => { this.patch({ notice: null }) }, @@ -710,6 +731,36 @@ export class PluginManagerController { return run } + /** Keep manual refresh feedback until its coalesced reads settle, without clearing cached cards. */ + private async refresh(): Promise { + if (this.disposed || this.getSnapshot().refreshStatus === 'refreshing') return + const startedAt = Date.now() + this.patch({ + refreshStatus: 'refreshing', + ...this.getSnapshot().notice?.kind === 'refresh-failed' ? { notice: null } : {}, + }) + try { + await this.load() + } catch (_error) { + // A rejected transport request leaves the cached cards available for retry. + this.patch({ status: 'error' }) + } finally { + // Hold the spinner to its minimum so a fast read does not flash it, then settle. + const remaining = REFRESH_SPINNER_MIN_MS - (Date.now() - startedAt) + if (remaining > 0) await new Promise((resolve) => { setTimeout(resolve, remaining) }) + this.settleRefresh() + } + } + + /** Publish refresh feedback only before disposal. */ + private settleRefresh(): void { + if (this.disposed) return + const failed = this.getSnapshot().status === 'error' + this.patch(failed && this.hasCachedInventory + ? { status: 'ready', refreshStatus: 'idle', notice: { kind: 'refresh-failed', seq: ++this.noticeSeq } } + : { refreshStatus: failed ? 'failed' : 'idle' }) + } + private async read(): Promise { try { do { @@ -725,6 +776,7 @@ export class PluginManagerController { continue } if (inventory.value.managementAvailable !== true) { + this.hasCachedInventory = false this.patch({ status: 'unavailable', packages: [] }) continue } @@ -737,8 +789,10 @@ export class PluginManagerController { this.patch({ status: 'error' }) continue } + this.hasCachedInventory = true this.patch({ status: 'ready', + refreshStatus: this.getSnapshot().refreshStatus === 'refreshing' ? 'refreshing' : 'idle', packages: sortPackages(bundles.value.map(bundle => packageView(bundle, plugins.value))), }) } while (this.shouldRerun()) @@ -779,15 +833,21 @@ export class PluginManagerController { const install = state.install const spec = install.spec.trim() if (install.phase === 'checking' || isInstallPending(install.phase) || spec === '') return + if (this.ctx.get('productAnalytics')?.enabled) { + this.analyticsAttempt = { input: sanitizeInstallInput(spec), started: Date.now() } + this.ctx.get('productAnalytics')?.track('plugin_install_click', { input_value: sanitizeInstallInput(spec) }) + } // A name the list already shows is refused at once, before the Host is asked. if (state.packages.some(pkg => pkg.name === spec)) { + this.finishAnalytics('failed', 'already-installed') this.patchInstall({ phase: 'idle', inputError: { problem: 'already-installed', reason: spec } }) return } const choice = install.registry const typed = choice.kind === 'custom' ? choice.url.trim() : undefined if (typed !== undefined && !REGISTRY_URL.test(typed)) { - this.patchInstall({ phase: 'idle', registryError: true }) + this.finishAnalytics('failed', 'invalid-registry') + this.patchInstall({ phase: 'idle', registryError: true, registryOpen: true }) return } this.abortInspect() @@ -810,11 +870,13 @@ export class PluginManagerController { if (this.gone(controller.signal)) return this.inspectAbort = undefined if (!inspected.ok) { + this.finishAnalytics('failed', inspected.error.code) this.patchInstall({ phase: 'idle', inputError: { problem: 'unknown', reason: inspected.error.message } }) return } if (inspected.value.status === 'refused') { const { problem, reason, registries } = inspected.value + this.finishAnalytics('failed', problem) this.patchInstall({ phase: 'idle', inputError: { problem, reason, ...registries === undefined ? {} : { registries } } }) return } @@ -865,12 +927,14 @@ export class PluginManagerController { return } this.request = undefined + this.finishAnalytics('unknown') this.patchInstall({ phase: 'unknown', failure: null, runs: settledRuns(this.getSnapshot().install.runs, null) }) this.notifyHiddenInstall('unknown') void this.load() } private settleInstall(result: ChangeResult): void { + this.finishAnalytics(result.application === 'failed' ? 'failed' : result.application === 'cancelled' ? 'cancelled' : 'success', result.application === 'failed' ? result.error?.code : undefined, result.bundle) const { runs, attempts } = this.getSnapshot().install this.request = undefined // The Host's answer names every registry it asked, whether or not each attempt's announcement arrived. @@ -916,6 +980,7 @@ export class PluginManagerController { const install = this.getSnapshot().install const pending = install.failure?.pendingBuilds if (install.phase !== 'failed' || install.subject === null || pending === undefined || pending.length === 0) return + if (this.ctx.get('productAnalytics')?.enabled) this.analyticsAttempt = { input: sanitizeInstallInput(install.subject.spec), started: Date.now() } await this.startInstall(install.subject, pending) } @@ -927,6 +992,7 @@ export class PluginManagerController { private async cancelInstall(): Promise { const install = this.getSnapshot().install if (install.phase === 'checking' || install.phase === 'failed' || install.phase === 'unknown') { + if (install.phase === 'checking') this.finishAnalytics('cancelled') this.abortInspect() this.offerSpecAgain() return @@ -953,6 +1019,7 @@ export class PluginManagerController { return } if (result.value.status === 'cancelled') { + this.finishAnalytics('cancelled') this.offerSpecAgain({ kind: 'cancelled', seq: ++this.noticeSeq }) void this.load() } else if (result.value.status === 'too-late') { @@ -1006,6 +1073,7 @@ export class PluginManagerController { if (this.disposed) return try { this.applied(result, name) + if (result.ok && (result.value.application === 'applied' || result.value.application === 'restart-required')) this.trackToggle(name, true) } catch (error) { this.patch({ notice: failedNotice(error, { packageName: name, action: 'enable' }, ++this.noticeSeq) }) } @@ -1062,6 +1130,27 @@ export class PluginManagerController { } } + private trackToggle(name: string, enabled: boolean, row = false): void { + const bundle = this.getSnapshot().packages.find(pkg => row ? pkg.rows.some(item => item.entryId === name) : pkg.name === name) + const pluginName = row ? bundle?.rows.find(item => item.entryId === name)?.moduleName : name + if (bundle === undefined || pluginName === undefined) return + this.ctx.get('productAnalytics')?.track('plugin_toggle', { + plugin_name: pluginName, plugin_type: row ? 'plugin' : 'bundle', is_enabled: enabled, is_builtin: !bundle.installed, + }) + } + + private finishAnalytics(status: 'success' | 'failed' | 'cancelled' | 'unknown', reason?: string, name?: string): void { + const attempt = this.analyticsAttempt + this.analyticsAttempt = undefined + if (attempt === undefined || this.disposed) return + const errorReason = status === 'cancelled' ? 'user_cancelled' : status === 'unknown' ? 'unknown_result' : reason + this.ctx.get('productAnalytics')?.track('install_plugin_result', { + input_value: attempt.input, is_success: status === 'success', + duration: Math.max(0, Date.now() - attempt.started), + ...errorReason === undefined ? {} : { error_reason: errorReason }, ...name === undefined ? {} : { plugin_name: name }, + }) + } + private patch(next: Partial): void { if (this.disposed) return this.store.set({ ...this.getSnapshot(), ...next }) diff --git a/packages/client/ui-plugin-manager/src/client/presentation.ts b/packages/client/ui-plugin-manager/src/client/presentation.ts index 292d604386..727d893729 100644 --- a/packages/client/ui-plugin-manager/src/client/presentation.ts +++ b/packages/client/ui-plugin-manager/src/client/presentation.ts @@ -143,6 +143,7 @@ export function noticeText(notice: ManagerNotice, t: Translate): string { case 'restart': return t('restartNotice') case 'overridden': return t('overriddenNotice', { name: notice.packageName }) case 'cancelled': return t('installCancelled') + case 'refresh-failed': return t('refreshError') case 'install': return t(({ done: 'installBackgroundDone', failed: 'installBackgroundFailed', unconfirmed: 'installBackgroundUnconfirmed', applying: 'installBackgroundApplying', unknown: 'installBackgroundUnknown', diff --git a/packages/client/ui-plugin-manager/src/client/sanitize-install-input.ts b/packages/client/ui-plugin-manager/src/client/sanitize-install-input.ts new file mode 100644 index 0000000000..c9caed9767 --- /dev/null +++ b/packages/client/ui-plugin-manager/src/client/sanitize-install-input.ts @@ -0,0 +1,13 @@ +/** Privacy-safe installation input classification shared by click and result events. */ + +/** + * Keep registry package names and plain versions; classify other installer inputs without their contents. + * @param spec - user-entered installation spec. + * @returns an identifier safe to send without URL credentials, tokens, or local paths. + */ +export function sanitizeInstallInput(spec: string): string { + if (/^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*(?:@[a-z0-9.*^~+<>=| -]+)?$/iu.test(spec)) return spec + if (/^(?:git[+:]|git@|github:|gitlab:|bitbucket:)/iu.test(spec)) return '[git]' + if (/^[a-z][a-z0-9+.-]*:\/\//iu.test(spec)) return '[url]' + return '[path-or-other]' +} diff --git a/packages/client/ui-plugin-manager/tests/browser-plugin.client.spec.tsx b/packages/client/ui-plugin-manager/tests/browser-plugin.client.spec.tsx index f9cff227dc..155a15c69b 100644 --- a/packages/client/ui-plugin-manager/tests/browser-plugin.client.spec.tsx +++ b/packages/client/ui-plugin-manager/tests/browser-plugin.client.spec.tsx @@ -12,6 +12,7 @@ import { TestRemote, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-t import * as settings from '@deepseek-ai/dsh-client-ui-settings/client' import { apply, inject, NS, PANEL_ID } from '../src/client/index.ts' import { PluginManagerPage } from '../src/client/PluginManagerPage.tsx' +import { PluginRefreshToast, type PluginRefreshToastFace } from '../src/client/PluginRefreshToast.tsx' import { PluginsPanelIcon } from '../src/client/PluginsPanelIcon.tsx' import type { PluginManagerFace } from '../src/client/manager-store.ts' @@ -54,6 +55,7 @@ function declare(slots: SlotRegistry): () => void { name: 'root', children: { 'main': { kind: 'keyed', scope: 'root' }, + 'shell.overlay': { kind: 'list', scope: 'root' }, 'sidebar.panellist': { kind: 'list', scope: 'root' }, }, } as never, () => null) @@ -80,6 +82,41 @@ describe('ui-plugin-manager browser plugin', () => { expect(navigation.getSnapshot()).toEqual({ view: { kind: 'package', name: 'dsh-navigation-test' } }) }) + it('shares refresh failures with the overlay after navigation and releases both registrations across reloads', async () => { + const b = await bench() + const fiber = b.ctx.plugin({ inject: [...inject], apply }) + await fiber.await() + expect(b.slots.entries('shell.overlay')).toHaveLength(0) + const removeRoot = declare(b.slots) + const mainInjected: object = b.slots.entries('main')[0]!.inject!() + const face = mainInjected as PluginManagerFace + const overlayInjected: object = b.slots.entries('shell.overlay')[0]!.inject!() + const overlay = overlayInjected as PluginRefreshToastFace + expect(overlay.hooks.pluginManager).toBe(face.hooks.pluginManager) + face.ensure() + await vi.waitFor(() => { expect(face.hooks.pluginManager.getSnapshot().status).toBe('ready') }) + b.selectPanel(PANEL_ID) + b.list.mockRejectedValueOnce(new Error('offline')) + face.refresh() + b.selectPanel(null) + await vi.waitFor(() => { expect(overlay.hooks.pluginManager.getSnapshot().notice?.kind).toBe('refresh-failed') }) + overlay.dismissNotice() + expect(face.hooks.pluginManager.getSnapshot().notice).toBeNull() + removeRoot() + expect(b.slots.entries('shell.overlay')).toHaveLength(0) + expect(b.slots.entries('main')).toHaveLength(0) + declare(b.slots) + const remountedInjected: object = b.slots.entries('shell.overlay')[0]!.inject!() + expect((remountedInjected as PluginRefreshToastFace).hooks.pluginManager).toBe(face.hooks.pluginManager) + await fiber.dispose() + expect(b.slots.entries('shell.overlay')).toHaveLength(0) + expect(b.slots.entries('main')).toHaveLength(0) + await b.ctx.plugin({ inject: [...inject], apply }).await() + const reloadedInjected: object = b.slots.entries('shell.overlay')[0]!.inject!() + expect((reloadedInjected as PluginRefreshToastFace).hooks.pluginManager).not.toBe(face.hooks.pluginManager) + expect((reloadedInjected as PluginRefreshToastFace).hooks.pluginManager.getSnapshot().notice).toBeNull() + }) + it('declares only the services the page and its Remote methods use', () => { expect(inject).toEqual(['slots', 'locale', 'remote', 'remote.pluginManager', 'remote.pluginInventory', 'remote.pluginRegistryProbe', 'configForms', 'layout']) }) @@ -116,7 +153,18 @@ describe('ui-plugin-manager browser plugin', () => { for (const name of ['plugins.detail.actions', 'plugins.detail.badge', 'plugins.detail.section'] as const) { expect(b.slots.spec(name)).toMatchObject({ kind: 'list', scope: 'root' }) } - const face = (entry.inject as unknown as () => PluginManagerFace)() + const injected: object = entry.inject!() + const face = injected as PluginManagerFace + const overlay = b.slots.entries('shell.overlay')[0]! + expect(overlay.component).toBe(PluginRefreshToast) + expect(overlay.options).toMatchObject({ id: 'plugin-manager.refresh-toast' }) + expect(overlay.locale).toBe(NS) + const overlayInjected: object = overlay.inject!() + const overlayFace = overlayInjected as PluginRefreshToastFace + expect(overlayFace.hooks.pluginManager).toBe(face.hooks.pluginManager) + expect(overlayFace.dismissNotice).toBe(face.dismissNotice) + expect(Object.keys(overlayFace).sort()).toEqual(['dismissNotice', 'hooks']) + expect(Object.keys(overlayFace.hooks)).toEqual(['pluginManager']) const text = { en: 'Local tools', zh: '本地工具' } expect(face.resolveText(text)).toBe('本地工具') b.locale.setLocale('en') @@ -146,6 +194,7 @@ describe('ui-plugin-manager browser plugin', () => { await fiber.dispose() expect(b.ctx.get('pluginNavigation')).toBeUndefined() expect(b.slots.entries('main')).toHaveLength(0) + expect(b.slots.entries('shell.overlay')).toHaveLength(0) expect(b.slots.entries('sidebar.panellist')).toHaveLength(0) b.remote.emit('plugin-manager/changed', [{ reason: 'install' }]) await Promise.resolve() diff --git a/packages/client/ui-plugin-manager/tests/components.client.spec.tsx b/packages/client/ui-plugin-manager/tests/components.client.spec.tsx index 09303b9e7a..beaa13ac3d 100644 --- a/packages/client/ui-plugin-manager/tests/components.client.spec.tsx +++ b/packages/client/ui-plugin-manager/tests/components.client.spec.tsx @@ -1,7 +1,7 @@ // @vitest-environment jsdom import type { ConfigPageForm } from '../src/client/slot-contract.ts' import { act, cleanup, fireEvent, render, screen, within } from '@testing-library/react' -import { afterEach, describe, expect, it, onTestFinished, vi } from 'vitest' +import { afterEach, beforeEach, describe, expect, it, onTestFinished, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client' import type { PluginEntryId, PluginInstallRequestId } from '@deepseek-ai/dsh-api-remotes/client' @@ -11,6 +11,7 @@ import { createSnapshotStore } from '@deepseek-ai/dsh-client-store' import { StrictMode, type ReactNode } from 'react' import { createNavigationStore } from '../src/client/navigation-store.ts' import { PluginManagerPage } from '../src/client/PluginManagerPage.tsx' +import { PluginRefreshToast } from '../src/client/PluginRefreshToast.tsx' import type { PluginManagerPageProps } from '../src/client/index.ts' import type { ConfigLedger } from '../src/client/config-ledger.ts' import { rowKey, type InstallState, type PackageRow, type PackageView, type PluginManagerState } from '../src/client/manager-store.ts' @@ -54,9 +55,9 @@ const OFFICIAL = 'https://registry.npmjs.org/' const REGISTRIES = { registry: null, fallbackRegistries: [MIRROR], resolved: OFFICIAL } /** pnpm's own registry as the options label it: by npm's own name once read, the neutral default name until then. */ -const OFFICIAL_OPTION = en.registryWithHost.replace('{name}', en.registryOfficial).replace('{host}', 'registry.npmjs.org') -const UNREAD_OPTION = en.registryWithHost.replace('{name}', en.registryDefault).replace('{host}', 'registry.npmjs.org') -const MIRROR_OPTION = en.registryWithHost.replace('{name}', en.registryNpmmirror).replace('{host}', 'registry.npmmirror.com') +const OFFICIAL_OPTION = `${en.registryOfficial} registry.npmjs.org` +const UNREAD_OPTION = `${en.registryDefault} registry.npmjs.org` +const MIRROR_OPTION = `${en.registryNpmmirror} registry.npmmirror.com` const IDLE_INSTALL: InstallState = { open: false, spec: '', registries: null, registry: { kind: 'offered', registry: null }, registryOpen: false, registryError: false, attempts: null, @@ -66,6 +67,7 @@ const IDLE_INSTALL: InstallState = { const READY: PluginManagerState = { status: 'ready', + refreshStatus: 'idle', packages: [], busy: [], notice: null, @@ -163,9 +165,18 @@ function renderTab( return body(owner.view, owner, 'form' in owner ? owner.form as ConfigPageForm | undefined : undefined) }, } - const { rerender, unmount } = render() + let showPage = true + let currentT = t + const contents = () => ( + <> + {showPage ? : null} + + + ) + const { rerender, unmount } = render(contents()) return { navigation, + hidePage: () => { showPage = false; rerender(contents()) }, props, unmount, store, @@ -173,7 +184,8 @@ function renderTab( set: (next: Partial) => { act(() => { store.set({ ...store.getSnapshot(), ...next }) }) }, setLanguage: (dict: typeof en) => { locale.setLocale(dict === zh ? 'zh' : 'en') - rerender() + currentT = translate(dict) + rerender(contents()) }, } } @@ -203,9 +215,14 @@ describe('PluginManagerPage', () => { it('asks the store once mounted and renders the loading, unavailable, error, and empty states', () => { const { actions, set } = renderTab({ status: 'loading' }) expect(actions.ensure).toHaveBeenCalledTimes(1) - expect(screen.getByText(en.loading).querySelector('[data-state="ongoing"]')).not.toBeNull() + const loading = screen.getByRole('status', { name: en.loading }) + expect(loading.querySelectorAll('li')).toHaveLength(4) + expect(loading.querySelector('ul')?.getAttribute('aria-hidden')).toBe('true') + expect(loading.querySelector('button, input, [data-state="ongoing"]')).toBeNull() + expect(document.querySelector('[data-plugin-panel]')?.getAttribute('aria-busy')).toBe('true') expect(screen.getByRole('button', { name: en.addPlugin })).toHaveProperty('disabled', true) set({ status: 'unavailable' }) + expect(screen.queryByRole('status', { name: en.loading })).toBeNull() expect(screen.getByRole('status').querySelector('[data-state="idle"]')).not.toBeNull() set({ status: 'error' }) expect(screen.getByRole('alert').querySelector('[data-state="error"]')).not.toBeNull() @@ -219,6 +236,134 @@ describe('PluginManagerPage', () => { expect(actions.openInstall).toHaveBeenCalledTimes(1) }) + it('shows skeletons only while loading and keeps ready cards during refresh and switching', () => { + const { actions, set } = renderTab({ status: 'idle' }) + expect(screen.queryByRole('status', { name: en.loading })).toBeNull() + set({ status: 'loading' }) + expect(screen.getByRole('status', { name: en.loading })).toBeTruthy() + set({ status: 'ready', packages: [pkg()] }) + expect(screen.queryByRole('status', { name: en.loading })).toBeNull() + expect(document.querySelector('[data-plugin-panel]')?.getAttribute('aria-busy')).toBe('false') + fireEvent.click(screen.getByRole('button', { name: en.refresh })) + expect(actions.refresh).toHaveBeenCalledTimes(1) + set({ busy: ['dsh-better-sidebar'] }) + expect(screen.queryByRole('status', { name: en.loading })).toBeNull() + expect(screen.getByRole('button', { name: en.openDetail.replace('{name}', 'dsh-better-sidebar') })).toBeTruthy() + expect(screen.getByRole('switch', { name: en.enableToggle.replace('{name}', 'dsh-better-sidebar') })).toHaveProperty('disabled', true) + }) + + it('shows refresh progress on the disabled button while preserving cards, then restores it without a toast', () => { + const { actions, set } = renderTab({ packages: [pkg()] }) + const refresh = screen.getByRole('button', { name: en.refresh }) + const detailName = en.openDetail.replace('{name}', 'dsh-better-sidebar') + const card = screen.getByRole('button', { name: detailName }) + expect(refresh).toHaveProperty('disabled', false) + expect(refresh.getAttribute('title')).toBeNull() + fireEvent.click(refresh) + expect(actions.refresh).toHaveBeenCalledOnce() + set({ refreshStatus: 'refreshing' }) + expect(refresh).toHaveProperty('disabled', true) + expect(refresh.getAttribute('aria-busy')).toBe('true') + expect(refresh.querySelector('[data-state="ongoing"]')).not.toBeNull() + expect(screen.getByRole('button', { name: detailName })).toBe(card) + expect(screen.queryByRole('status', { name: en.loading })).toBeNull() + expect(screen.queryByRole('alert')).toBeNull() + fireEvent.click(refresh) + expect(actions.refresh).toHaveBeenCalledOnce() + set({ refreshStatus: 'idle' }) + expect(refresh).toHaveProperty('disabled', false) + expect(refresh.getAttribute('aria-busy')).toBe('false') + expect(refresh.querySelector('[data-state="ongoing"]')).toBeNull() + expect(screen.getByRole('button', { name: detailName })).toBe(card) + expect(screen.queryByRole('alert')).toBeNull() + expect(actions.dismissNotice).not.toHaveBeenCalled() + }) + + it.each(['list', 'detail'] as const)('keeps cached %s content with one localized refresh toast and no inline retry', (view) => { + const { set, setLanguage } = renderTab({ packages: [pkg()] }) + if (view === 'detail') fireEvent.click(screen.getByRole('button', { name: en.openDetail.replace('{name}', 'dsh-better-sidebar') })) + const content = document.querySelector(view === 'detail' ? '[data-plugin-detail]' : '[data-plugin-package]') + for (const dict of [en, zh]) { + setLanguage(dict) + set({ status: 'ready', refreshStatus: 'idle', notice: { kind: 'refresh-failed', seq: 1 } }) + expect(screen.getAllByRole('alert')).toHaveLength(1) + const toast = screen.getByRole('alert') + expect(toast.textContent).toBe(dict.refreshError) + expect(toast.parentElement).toBe(document.body) + expect(document.querySelector('[data-plugin-panel]')?.contains(toast)).toBe(false) + expect(screen.queryByRole('button', { name: dict.retry })).toBeNull() + expect(content?.isConnected).toBe(true) + set({ refreshStatus: 'refreshing', notice: null }) + expect(screen.queryByRole('alert')).toBeNull() + expect(content?.isConnected).toBe(true) + set({ refreshStatus: 'idle' }) + expect(screen.queryByRole('alert')).toBeNull() + } + }) + + it.each(['list', 'configuration detail'] as const)('keeps an uncached refresh failure inline in %s and hides it during retry', (view) => { + const { actions, set, setLanguage } = renderTab( + { status: 'error', refreshStatus: 'failed' }, + { items: [{ id: 'bash', label: 'Shell' }] }, + ) + if (view === 'configuration detail') fireEvent.click(screen.getByRole('button', { name: en.openDetail.replace('{name}', 'Shell') })) + for (const dict of [en, zh]) { + setLanguage(dict) + set({ status: 'error', refreshStatus: 'failed' }) + const alert = screen.getByRole('alert') + expect(alert.textContent).toBe(dict.refreshError) + expect(document.querySelector('[data-plugin-panel]')?.contains(alert)).toBe(true) + fireEvent.click(screen.getByRole('button', { name: dict.retry })) + set({ refreshStatus: 'refreshing' }) + expect(screen.queryByRole('alert')).toBeNull() + expect(screen.queryByRole('button', { name: dict.retry })).toBeNull() + } + expect(actions.refresh).toHaveBeenCalledTimes(2) + }) + + it.each(['before', 'after'] as const)('keeps the refresh toast when navigation leaves %s the failure arrives', (navigation) => { + vi.useFakeTimers() + try { + const { actions, set, hidePage } = renderTab({ packages: [pkg()] }) + set({ refreshStatus: 'refreshing' }) + if (navigation === 'before') hidePage() + set({ refreshStatus: 'idle', notice: { kind: 'refresh-failed', seq: 1 } }) + const toast = screen.getByRole('alert') + expect(toast.textContent).toBe(en.refreshError) + if (navigation === 'after') hidePage() + expect(document.querySelector('[data-plugin-panel]')).toBeNull() + expect(screen.getByRole('alert')).toBe(toast) + expect(toast.style.getPropertyValue('--dsh-toast-hold')).toBe('3000ms') + act(() => { vi.advanceTimersByTime(3_999) }) + expect(actions.dismissNotice).not.toHaveBeenCalled() + act(() => { vi.advanceTimersByTime(1) }) + expect(actions.dismissNotice).toHaveBeenCalledOnce() + set({ notice: null }) + expect(screen.queryByRole('alert')).toBeNull() + } finally { + cleanup() + vi.useRealTimers() + } + }) + + it('gives a repeated refresh failure its own toast lifetime without extending it for locale changes', () => { + vi.useFakeTimers() + try { + const { actions, set, setLanguage } = renderTab({ notice: { kind: 'refresh-failed', seq: 1 } }) + act(() => { vi.advanceTimersByTime(2_000) }) + set({ notice: { kind: 'refresh-failed', seq: 2 } }) + act(() => { vi.advanceTimersByTime(2_000) }) + expect(actions.dismissNotice).not.toHaveBeenCalled() + setLanguage(zh) + expect(screen.getByRole('alert').textContent).toBe(zh.refreshError) + act(() => { vi.advanceTimersByTime(2_000) }) + expect(actions.dismissNotice).toHaveBeenCalledOnce() + } finally { + cleanup() + vi.useRealTimers() + } + }) + it('keeps the read failure and its retry visible while a detail page is open', () => { const { actions, set } = renderTab({ packages: [pkg()] }) fireEvent.click(screen.getByRole('button', { name: en.openDetail.replace('{name}', 'dsh-better-sidebar') })) @@ -735,6 +880,19 @@ describe('PluginManagerPage', () => { expect(document.querySelector('[data-plugin-name]')?.textContent).toBe(name) }) + it.each([ + { locale: en, placeholder: 'for example dsh-plugin-whale-pet' }, + { locale: zh, placeholder: '例如 dsh-plugin-whale-pet' }, + ])('uses the package example in $placeholder and the install guide', ({ locale, placeholder }) => { + const { actions, setLanguage } = renderTab({ install: { ...IDLE_INSTALL, open: true } }) + setLanguage(locale) + expect(screen.getByPlaceholderText(placeholder)).toBeTruthy() + fireEvent.click(screen.getByRole('button', { name: locale.installGuideToggle })) + expect(screen.getByText('dsh-plugin-whale-pet')).toBeTruthy() + fireEvent.click(screen.getByRole('button', { name: locale.installGuideFillAria.replace('{example}', 'dsh-plugin-whale-pet') })) + expect(actions.editInstallSpec).toHaveBeenCalledExactlyOnceWith('dsh-plugin-whale-pet') + }) + it('opens a guide under the field and drops an example into it', () => { const { actions } = renderTab({ install: { ...IDLE_INSTALL, open: true } }) expect(screen.queryByText(en.installGuideIdHint)).toBeNull() @@ -857,6 +1015,100 @@ describe('PluginManagerPage', () => { expect(within(detail).getByText(en.rowStateIdle)).toBeTruthy() }) + describe.each(['package', 'custom registry'] as const)('%s input IME confirmation', (input) => { + beforeEach(() => { vi.useFakeTimers() }) + afterEach(() => { cleanup(); vi.useRealTimers() }) + const inputName = input === 'package' ? en.installSpecLabel : en.registryCustom + const open: InstallState = { + ...IDLE_INSTALL, open: true, spec: 'dsh-new', registryOpen: true, + registry: { kind: 'custom', url: 'https://npm.corp.example/' }, + } + const enter = (field: HTMLElement) => { + // oxlint-disable-next-line typescript/no-deprecated -- Exercise native Enter's legacy keyCode in the IME regression. + const event = new KeyboardEvent('keydown', { key: 'Enter', isComposing: false, keyCode: 13, bubbles: true, cancelable: true }) + fireEvent(field, event) + expect(event.defaultPrevented).toBe(false) + } + + it('guards active composition and the first 10ms after compositionend without native flags', () => { + const { actions } = renderTab({ install: open }) + const field = screen.getByRole('textbox', { name: inputName }) + fireEvent.compositionStart(field) + enter(field) + expect(actions.runInstall).not.toHaveBeenCalled() + fireEvent.compositionEnd(field) + enter(field) + act(() => { vi.advanceTimersByTime(9) }) + enter(field) + expect(actions.runInstall).not.toHaveBeenCalled() + act(() => { vi.advanceTimersByTime(1) }) + enter(field) + expect(actions.runInstall).toHaveBeenCalledOnce() + }) + + it('keeps composition state independent from the other input', () => { + const { actions } = renderTab({ install: open }) + const field = screen.getByRole('textbox', { name: inputName }) + const other = screen.getByRole('textbox', { name: input === 'package' ? en.registryCustom : en.installSpecLabel }) + fireEvent.compositionStart(field) + enter(other) + expect(actions.runInstall).toHaveBeenCalledOnce() + enter(field) + expect(actions.runInstall).toHaveBeenCalledOnce() + }) + + it.each(['active', 'ended'] as const)('clears %s composition on blur and dialog reopen', (phase) => { + const { actions, set } = renderTab({ install: open }) + const field = screen.getByRole('textbox', { name: inputName }) + fireEvent.compositionStart(field) + if (phase === 'ended') fireEvent.compositionEnd(field) + fireEvent.blur(field) + enter(field) + expect(actions.runInstall).toHaveBeenCalledOnce() + fireEvent.compositionStart(field) + if (phase === 'ended') fireEvent.compositionEnd(field) + set({ install: { ...open, open: false } }) + set({ install: open }) + enter(screen.getByRole('textbox', { name: inputName })) + expect(actions.runInstall).toHaveBeenCalledTimes(2) + }) + + if (input === 'custom registry') { + it('clears composition when the registry menu closes and reopens', () => { + const { actions, set } = renderTab({ install: open }) + fireEvent.compositionStart(screen.getByRole('textbox', { name: inputName })) + set({ install: { ...open, registryOpen: false } }) + set({ install: open }) + enter(screen.getByRole('textbox', { name: inputName })) + expect(actions.runInstall).toHaveBeenCalledOnce() + }) + } + + it.each([ + { signal: 'isComposing', isComposing: true, keyCode: 13 }, + { signal: 'legacy keyCode 229', isComposing: false, keyCode: 229 }, + ])('leaves $signal Enter to the IME and installs on the next ordinary Enter', ({ isComposing, keyCode }) => { + const { actions } = renderTab({ + install: { + ...IDLE_INSTALL, open: true, spec: 'dsh-new', registryOpen: input === 'custom registry', + registry: { kind: 'custom', url: 'https://npm.corp.example/' }, + }, + }) + const field = screen.getByRole('textbox', { name: input === 'package' ? en.installSpecLabel : en.registryCustom }) + fireEvent.compositionStart(field) + if (!isComposing) fireEvent.compositionEnd(field) + // oxlint-disable-next-line typescript/no-deprecated -- Exercise the legacy IME signal when isComposing is false. + const confirm = new KeyboardEvent('keydown', { key: 'Enter', isComposing, keyCode, bubbles: true, cancelable: true }) + fireEvent(field, confirm) + expect(actions.runInstall).not.toHaveBeenCalled() + expect(confirm.defaultPrevented).toBe(false) + if (isComposing) fireEvent.compositionEnd(field) + act(() => { vi.advanceTimersByTime(10) }) + fireEvent.keyDown(field, { key: 'Enter', isComposing: false, keyCode: 13 }) + expect(actions.runInstall).toHaveBeenCalledOnce() + }) + }) + it('takes a spec, checks it, and words what the check refused', () => { const { actions, set } = renderTab({ install: { ...IDLE_INSTALL, open: true } }) expect(screen.getByText(en.installDescription)).toBeTruthy() @@ -1197,6 +1449,86 @@ describe('PluginManagerPage', () => { } }) + it('selects the custom registry from its whole area and focuses the address without clearing it', () => { + const open = { ...IDLE_INSTALL, open: true, registryOpen: true, registries: REGISTRIES } + const { actions, set } = renderTab({ install: open }) + const field = screen.getByRole('textbox', { name: en.registryCustom }) + const label = screen.getByRole('radio', { name: en.registryCustom }).parentElement! + const area = label.parentElement! + expect(field).toHaveProperty('disabled', false) + for (const target of [area, label, screen.getByText(en.registryCustomHint)]) { + field.blur() + set({ install: open }) + actions.chooseRegistry.mockClear() + fireEvent.pointerDown(target) + fireEvent.click(target) + expect(actions.chooseRegistry).toHaveBeenCalledExactlyOnceWith({ kind: 'custom', url: '' }) + expect(document.activeElement).toBe(field) + } + set({ install: { ...open, registry: { kind: 'custom', url: 'https://npm.corp/' } } }) + field.blur() + actions.chooseRegistry.mockClear() + field.focus() + fireEvent.click(field) + fireEvent.click(area) + expect(document.activeElement).toBe(field) + expect(field).toHaveProperty('value', 'https://npm.corp/') + expect(actions.chooseRegistry).not.toHaveBeenCalled() + field.blur() + fireEvent.click(screen.getByRole('radio', { name: OFFICIAL_OPTION })) + set({ install: open }) + expect(field).toHaveProperty('value', 'https://npm.corp/') + fireEvent.click(screen.getByRole('radio', { name: MIRROR_OPTION })) + set({ install: { ...open, registry: { kind: 'offered', registry: MIRROR } } }) + fireEvent.click(area) + expect(actions.chooseRegistry).toHaveBeenLastCalledWith({ kind: 'custom', url: 'https://npm.corp/' }) + expect(document.activeElement).toBe(field) + }) + + it('keeps the selected registry on keyboard focus and selects custom through its radio', () => { + const open = { ...IDLE_INSTALL, open: true, registryOpen: true, registries: REGISTRIES } + const { actions } = renderTab({ install: open }) + const field = screen.getByRole('textbox', { name: en.registryCustom }) + const official = screen.getByRole('radio', { name: OFFICIAL_OPTION }) + official.focus() + fireEvent.keyDown(official, { key: 'Tab' }) + expect(document.activeElement).toBe(field) + expect(official).toHaveProperty('checked', true) + expect(actions.chooseRegistry).not.toHaveBeenCalled() + fireEvent.keyDown(field, { key: 'Tab', shiftKey: true }) + expect(document.activeElement).toBe(official) + fireEvent.keyDown(official, { key: 'Tab', shiftKey: true }) + const toggle = screen.getByRole('button', { name: `${en.registryToggle} ${en.registryOfficial}` }) + expect(document.activeElement).toBe(toggle) + expect(actions.toggleRegistryOptions).toHaveBeenCalledOnce() + actions.toggleRegistryOptions.mockClear() + field.focus() + fireEvent.keyDown(field, { key: 'Tab' }) + expect(document.activeElement).toBe(toggle) + expect(actions.toggleRegistryOptions).toHaveBeenCalledOnce() + const custom = screen.getByRole('radio', { name: en.registryCustom }) + custom.focus() + fireEvent.keyDown(custom, { key: ' ' }) + fireEvent.click(custom) + expect(actions.chooseRegistry).toHaveBeenCalledExactlyOnceWith({ kind: 'custom', url: '' }) + expect(document.activeElement).toBe(field) + }) + + it('focuses an invalid custom address when submission opens its registry menu', () => { + const open = { ...IDLE_INSTALL, open: true, spec: 'dsh-new', registry: { kind: 'custom' as const, url: 'invalid' } } + const { actions, set } = renderTab({ install: open }) + fireEvent.click(screen.getByRole('button', { name: en.installRun })) + expect(actions.runInstall).toHaveBeenCalledOnce() + set({ install: { ...open, registryOpen: true, registryError: true } }) + const field = screen.getByRole('textbox', { name: en.registryCustom }) + expect(document.activeElement).toBe(field) + expect(field.getAttribute('aria-invalid')).toBe('true') + expect(screen.getByRole('alert').textContent).toBe(en.registryCustomInvalid) + fireEvent.keyDown(field, { key: 'Escape' }) + expect(actions.toggleRegistryOptions).toHaveBeenCalledOnce() + expect(actions.closeInstall).not.toHaveBeenCalled() + }) + it('offers the registries under the spec, folded by default, and picks or types one', () => { const open = { ...IDLE_INSTALL, open: true, registries: REGISTRIES } const { actions, set } = renderTab({ install: open }) diff --git a/packages/client/ui-plugin-manager/tests/manager-store.client.spec.ts b/packages/client/ui-plugin-manager/tests/manager-store.client.spec.ts index 0cd5683e0e..895a4feccd 100644 --- a/packages/client/ui-plugin-manager/tests/manager-store.client.spec.ts +++ b/packages/client/ui-plugin-manager/tests/manager-store.client.spec.ts @@ -71,10 +71,12 @@ const NO_CONFIG: HostObservable = { subscribe: () => () => {}, } -function bench(overrides: Partial>> = {}) { +function bench(overrides: Partial>> = {}, enabled = true) { const inventory = { list: overrides.inventory ?? vi.fn(() => Promise.resolve(ok({ entries: [], managementAvailable: true }))) } const plugins = { - listBundles: vi.fn(() => Promise.resolve(ok([BUNDLE]))), + listBundles: vi.fn<() => Promise> | ReturnType>>( + () => Promise.resolve(ok([BUNDLE])), + ), listPlugins: vi.fn(() => Promise.resolve(ok(PLUGINS))), inspect: vi.fn(() => Promise.resolve(ok(INSPECTED))), registries: vi.fn(() => Promise.resolve(ok(REGISTRIES))), @@ -87,7 +89,9 @@ function bench(overrides: Partial>> = {} ...overrides, } const probe = { fastest: overrides.fastest ?? vi.fn(() => Promise.resolve(ok(null))) } + const track = vi.fn() const ctx = { + get: () => ({ enabled, track }), configForms: { describe: () => ({ getSnapshot: () => ({ view: { namespaces: [] } }), subscribe: () => () => {} }), get: vi.fn((id: string) => `form:${id}`) }, remote: { pluginManager: plugins, pluginInventory: inventory, pluginRegistryProbe: probe }, } as never @@ -100,7 +104,7 @@ function bench(overrides: Partial>> = {} await vi.waitFor(() => { expect(state().install.phase).toBe('starting') }) return state().install.requestId as PluginInstallRequestId } - return { plugins, inventory, probe, controller, face, state, started } + return { plugins, inventory, probe, controller, face, state, started, track } } it('hands a custom page the shared configuration form of its entry', () => { @@ -224,7 +228,229 @@ describe('PluginManagerController', () => { expect(plugins.listBundles).toHaveBeenCalledTimes(2) }) + it('keeps cached packages while a manual refresh reads and ignores repeated refreshes without a success notice', async () => { + vi.useFakeTimers() + onTestFinished(() => { vi.useRealTimers() }) + const { plugins, inventory, face, state, controller } = bench() + await controller.load() + const packages = state().packages + const gate = deferred>>() + plugins.listBundles.mockReturnValueOnce(gate.promise) + face.refresh() + expect(state()).toMatchObject({ status: 'ready', refreshStatus: 'refreshing', notice: null }) + expect(state().packages).toBe(packages) + await vi.advanceTimersByTimeAsync(0) + expect(plugins.listBundles).toHaveBeenCalledTimes(2) + face.refresh() + face.refresh() + gate.resolve(ok([{ ...BUNDLE, version: '0.17.0' }])) + await vi.advanceTimersByTimeAsync(399) + expect(state().refreshStatus).toBe('refreshing') + await vi.advanceTimersByTimeAsync(1) + expect(state().refreshStatus).toBe('idle') + expect(state().packages[0]?.version).toBe('0.17.0') + expect(state().status).toBe('ready') + expect(state().notice).toBeNull() + expect(inventory.list).toHaveBeenCalledTimes(2) + expect(plugins.listBundles).toHaveBeenCalledTimes(2) + expect(plugins.listPlugins).toHaveBeenCalledTimes(2) + }) + + it.each(['refused', 'rejected'] as const)('keeps cached packages ready after a %s refresh and clears its toast when retry starts', async (failure) => { + vi.useFakeTimers() + onTestFinished(() => { vi.useRealTimers() }) + const { inventory, plugins, face, state, controller } = bench() + await controller.load() + const packages = state().packages + if (failure === 'refused') inventory.list.mockResolvedValueOnce(refused('gateway/internal', 'offline')) + else inventory.list.mockRejectedValueOnce(new Error('transport down')) + face.refresh() + await vi.advanceTimersByTimeAsync(400) + expect(state().refreshStatus).toBe('idle') + expect(state()).toMatchObject({ status: 'ready', notice: { kind: 'refresh-failed', seq: 1 } }) + expect(state().packages).toBe(packages) + const gate = deferred>>() + plugins.listBundles.mockReturnValueOnce(gate.promise) + face.refresh() + expect(state()).toMatchObject({ status: 'ready', refreshStatus: 'refreshing', notice: null }) + expect(state().packages).toBe(packages) + await vi.advanceTimersByTimeAsync(0) + expect(plugins.listBundles).toHaveBeenCalledTimes(2) + gate.resolve(ok([BUNDLE])) + await vi.advanceTimersByTimeAsync(400) + expect(state().refreshStatus).toBe('idle') + expect(state()).toMatchObject({ status: 'ready', notice: null }) + inventory.list.mockResolvedValueOnce(refused('gateway/internal', 'offline again')) + face.refresh() + await vi.advanceTimersByTimeAsync(400) + expect(state().notice).toEqual({ kind: 'refresh-failed', seq: 2 }) + face.dismissNotice() + expect(state().notice).toBeNull() + }) + + it.each(['refused', 'rejected'] as const)('keeps a %s first refresh failure inline without a toast', async (failure) => { + vi.useFakeTimers() + onTestFinished(() => { vi.useRealTimers() }) + const inventory = failure === 'refused' + ? vi.fn().mockResolvedValueOnce(refused('gateway/internal', 'offline')) + : vi.fn().mockRejectedValueOnce(new Error('transport down')) + const { face, state } = bench({ inventory }) + face.refresh() + await vi.advanceTimersByTimeAsync(400) + expect(state().refreshStatus).toBe('failed') + expect(state()).toMatchObject({ status: 'error', packages: [], notice: null }) + }) + + it('treats an empty successful inventory as cached for refresh failures', async () => { + vi.useFakeTimers() + onTestFinished(() => { vi.useRealTimers() }) + const { inventory, face, state, controller } = bench({ listBundles: vi.fn().mockResolvedValue(ok([])) }) + await controller.load() + expect(state().packages).toEqual([]) + inventory.list.mockResolvedValueOnce(refused('gateway/internal', 'offline')) + face.refresh() + await vi.advanceTimersByTimeAsync(400) + expect(state().refreshStatus).toBe('idle') + expect(state()).toMatchObject({ status: 'ready', packages: [], notice: { kind: 'refresh-failed' } }) + }) + + it('forgets cached inventory when the managed profile becomes unavailable', async () => { + vi.useFakeTimers() + onTestFinished(() => { vi.useRealTimers() }) + const { inventory, face, state, controller } = bench() + await controller.load() + inventory.list.mockResolvedValueOnce(ok({ entries: [], managementAvailable: false })) + await controller.load() + expect(state()).toMatchObject({ status: 'unavailable', packages: [] }) + inventory.list.mockResolvedValueOnce(refused('gateway/internal', 'offline')) + face.refresh() + await vi.advanceTimersByTimeAsync(400) + expect(state().refreshStatus).toBe('failed') + expect(state()).toMatchObject({ status: 'error', packages: [], notice: null }) + }) + + it('preserves unrelated notices when a manual refresh starts and succeeds', async () => { + vi.useFakeTimers() + onTestFinished(() => { vi.useRealTimers() }) + const { face, state, controller } = bench({ + setBundleEnabled: vi.fn().mockResolvedValue(ok({ ...APPLIED, application: 'restart-required' })), + }) + await controller.load() + face.setEnabled(BUNDLE.name, true) + await vi.advanceTimersByTimeAsync(0) + expect(state().notice?.kind).toBe('restart') + const notice = state().notice + face.refresh() + expect(state().notice).toBe(notice) + await vi.advanceTimersByTimeAsync(400) + expect(state().refreshStatus).toBe('idle') + expect(state().notice).toBe(notice) + }) + + it('keeps background reads quiet and clears an uncached refresh failure when they succeed', async () => { + vi.useFakeTimers() + onTestFinished(() => { vi.useRealTimers() }) + const { plugins, face, state, controller } = bench({ + inventory: vi.fn().mockResolvedValueOnce(refused('gateway/internal', 'offline')) + .mockResolvedValue(ok({ entries: [], managementAvailable: true })), + }) + face.refresh() + await vi.advanceTimersByTimeAsync(400) + expect(state().refreshStatus).toBe('failed') + const gate = deferred>>() + plugins.listBundles.mockReturnValueOnce(gate.promise) + const loading = controller.load() + await vi.advanceTimersByTimeAsync(0) + expect(plugins.listBundles).toHaveBeenCalledOnce() + expect(state().refreshStatus).toBe('failed') + gate.resolve(ok([BUNDLE])) + await loading + expect(state()).toMatchObject({ status: 'ready', refreshStatus: 'idle', notice: null }) + }) + + it.each(['background', 'manual'] as const)('holds the refresh indicator through coalesced reads when %s starts first', async (first) => { + vi.useFakeTimers() + onTestFinished(() => { vi.useRealTimers() }) + const { plugins, face, state, controller } = bench() + await controller.load() + const initial = deferred>>() + const rerun = deferred>>() + plugins.listBundles.mockReturnValueOnce(initial.promise).mockReturnValueOnce(rerun.promise) + const background = first === 'background' ? controller.load() : undefined + if (first === 'manual') face.refresh() + await vi.advanceTimersByTimeAsync(0) + expect(plugins.listBundles).toHaveBeenCalledTimes(2) + expect(state().refreshStatus).toBe(first === 'background' ? 'idle' : 'refreshing') + const completion = background ?? controller.load() + if (first === 'background') face.refresh() + initial.resolve(ok([{ ...BUNDLE, version: '0.17.0' }])) + await vi.advanceTimersByTimeAsync(400) + expect(plugins.listBundles).toHaveBeenCalledTimes(3) + expect(state()).toMatchObject({ status: 'ready', refreshStatus: 'refreshing', notice: null }) + expect(state().packages[0]?.version).toBe('0.17.0') + face.refresh() + rerun.resolve(ok([{ ...BUNDLE, version: '0.18.0' }])) + await completion + await vi.advanceTimersByTimeAsync(0) + expect(state().refreshStatus).toBe('idle') + expect(state().packages[0]?.version).toBe('0.18.0') + expect(state().notice).toBeNull() + expect(plugins.listBundles).toHaveBeenCalledTimes(3) + }) + + it.each([false, true])('reports only the final coalesced refresh result (failure: %s)', async (failure) => { + vi.useFakeTimers() + onTestFinished(() => { vi.useRealTimers() }) + const { plugins, face, state, controller } = bench() + await controller.load() + const initial = deferred> | ReturnType>() + const rerun = deferred> | ReturnType>() + plugins.listBundles.mockReturnValueOnce(initial.promise).mockReturnValueOnce(rerun.promise) + face.refresh() + await vi.advanceTimersByTimeAsync(0) + expect(plugins.listBundles).toHaveBeenCalledTimes(2) + const loading = controller.load() + initial.resolve(failure ? ok([BUNDLE]) : refused('gateway/internal', 'offline')) + await vi.advanceTimersByTimeAsync(0) + expect(plugins.listBundles).toHaveBeenCalledTimes(3) + expect(state().refreshStatus).toBe('refreshing') + expect(state().notice).toBeNull() + rerun.resolve(failure ? refused('gateway/internal', 'offline') : ok([BUNDLE])) + await loading + await vi.advanceTimersByTimeAsync(400) + expect(state().refreshStatus).toBe('idle') + expect(state().status).toBe('ready') + expect(state().notice).toEqual(failure ? { kind: 'refresh-failed', seq: 1 } : null) + }) + + it.each([false, true])('does not publish a manual refresh that settles after disposal (failure: %s)', async (failure) => { + vi.useFakeTimers() + onTestFinished(() => { vi.useRealTimers() }) + const { plugins, face, state, controller } = bench() + await controller.load() + const gate = deferred> | ReturnType>() + plugins.listBundles.mockReturnValueOnce(gate.promise) + face.refresh() + await vi.advanceTimersByTimeAsync(0) + expect(plugins.listBundles).toHaveBeenCalledTimes(2) + const completion = controller.load() + const before = state() + const listener = vi.fn() + const unsubscribe = face.hooks.pluginManager.subscribe(listener) + onTestFinished(unsubscribe) + controller.dispose() + gate.resolve(failure ? refused('gateway/internal', 'offline') : ok([{ ...BUNDLE, version: '0.17.0' }])) + await completion + face.refresh() + await vi.advanceTimersByTimeAsync(400) + expect(state()).toBe(before) + expect(listener).not.toHaveBeenCalled() + expect(plugins.listBundles).toHaveBeenCalledTimes(2) + }) + it('reports a Host without a managed profile as unavailable and keeps the last packages across a failed read', async () => { + vi.useFakeTimers() + onTestFinished(() => { vi.useRealTimers() }) const { inventory, plugins, face, state, controller } = bench() await controller.load() expect(state().packages).toHaveLength(1) @@ -239,11 +465,12 @@ describe('PluginManagerController', () => { plugins.listPlugins.mockResolvedValueOnce(refused('gateway/internal', 'offline') as never) await controller.load() expect(state()).toMatchObject({ status: 'error', packages: [packageView(BUNDLE, PLUGINS)] }) - plugins.listBundles.mockResolvedValueOnce(refused('gateway/internal', 'offline') as never) + plugins.listBundles.mockResolvedValueOnce(refused('gateway/internal', 'offline')) await controller.load() expect(state().status).toBe('error') face.refresh() - await vi.waitFor(() => { expect(state().status).toBe('ready') }) + await vi.advanceTimersByTimeAsync(400) + expect(state().status).toBe('ready') }) it('enables a bundle, marks it busy meanwhile, and says when a restart is needed or a layer overrides it', async () => { @@ -311,7 +538,7 @@ describe('PluginManagerController', () => { }) it('always asks before uninstalling, and cancelling runs nothing', async () => { - const { plugins, face, state, controller } = bench() + const { plugins, face, state, controller, track } = bench() await controller.load() face.uninstall(BUNDLE.name) expect(state().confirm).toEqual({ action: 'uninstall', packageName: BUNDLE.name }) @@ -319,10 +546,12 @@ describe('PluginManagerController', () => { expect(state().confirm).toBeNull() face.confirm() expect(plugins.removeBundle).not.toHaveBeenCalled() + expect(track).not.toHaveBeenCalled() face.uninstall(BUNDLE.name) face.confirm() expect(state().confirm).toBeNull() await vi.waitFor(() => { expect(plugins.removeBundle).toHaveBeenCalledExactlyOnceWith(BUNDLE.name) }) + expect(track).toHaveBeenCalledExactlyOnceWith('confirm_uninstall_plugin', { plugin_name: BUNDLE.name }) await vi.waitFor(() => { expect(state().busy).toEqual([]) }) // A refused removal names the action it was. plugins.removeBundle.mockResolvedValueOnce(ok({ ...failed(), stage: 'remove', error: { code: 'not-removable' } }) as never) @@ -857,7 +1086,7 @@ describe('PluginManagerController', () => { expect(state().highlight).toBeNull() }) - it('offers the scripts a blocked run left pending, and retries the same spec with them allowed', async () => { + it.each([true, false])('offers the scripts a blocked run left pending, and retries with analytics enabled=%s', async (enabled) => { const gates: ReturnType> | ReturnType>>>[] = [] const { face, state, controller, plugins, started } = bench({ installBundle: vi.fn(() => { @@ -865,7 +1094,7 @@ describe('PluginManagerController', () => { gates.push(gate) return gate.promise }), - }) + }, enabled) await controller.load() face.openInstall() face.editInstallSpec('x') @@ -1049,6 +1278,52 @@ describe('PluginManagerController', () => { await loading expect(state()).toBe(before) }) + + it.each([false, true])('drops refresh feedback when disposed during the spinner hold (failure: %s)', async (failure) => { + vi.useFakeTimers() + try { + const { plugins, face, state, controller } = bench() + await controller.load() + plugins.listBundles.mockResolvedValueOnce(failure ? refused('gateway/internal', 'offline') : ok([BUNDLE])) + face.refresh() + await vi.advanceTimersByTimeAsync(0) + expect(state().refreshStatus).toBe('refreshing') + expect(vi.getTimerCount()).toBe(1) + const before = state() + const listener = vi.fn() + const unsubscribe = face.hooks.pluginManager.subscribe(listener) + onTestFinished(unsubscribe) + controller.dispose() + await vi.advanceTimersByTimeAsync(400) + expect(state()).toBe(before) + expect(listener).not.toHaveBeenCalled() + expect(vi.getTimerCount()).toBe(0) + } finally { + vi.useRealTimers() + } + }) + + it('settles a manual refresh whose read outlasts the spinner minimum without an extra hold', async () => { + vi.useFakeTimers() + try { + const { plugins, face, state, controller } = bench() + await controller.load() + const gate = deferred>>() + plugins.listBundles.mockReturnValueOnce(gate.promise) + face.refresh() + await vi.advanceTimersByTimeAsync(401) + expect(plugins.listBundles).toHaveBeenCalledTimes(2) + expect(state().refreshStatus).toBe('refreshing') + gate.resolve(ok([{ ...BUNDLE, version: '0.42.0' }])) + await vi.advanceTimersByTimeAsync(0) + expect(state().refreshStatus).toBe('idle') + expect(state().packages[0]?.version).toBe('0.42.0') + expect(state().status).toBe('ready') + expect(vi.getTimerCount()).toBe(0) + } finally { + vi.useRealTimers() + } + }) it('offers the registries the Host configured, starts from its first, and asks the check and the run to start where the person chose', async () => { const gate = deferred>>() const { plugins, face, state, controller, started } = bench({ @@ -1152,15 +1427,18 @@ describe('PluginManagerController', () => { removeItem: (key: string) => { storage.delete(key) }, }) try { - const { plugins, face, state } = bench({ + const { plugins, face, state, track } = bench({ inspect: vi.fn(() => Promise.resolve(ok({ ...INSPECTED, registry: 'https://npm.corp.example/' }))), }) face.openInstall() face.editInstallSpec('dsh-new') face.chooseRegistry({ kind: 'custom', url: ' npm.corp.example ' }) face.runInstall() - expect(state().install).toMatchObject({ phase: 'idle', registryError: true }) + expect(state().install).toMatchObject({ phase: 'idle', registryError: true, registryOpen: true }) expect(plugins.inspect).not.toHaveBeenCalled() + expect(track.mock.calls.filter(([event]) => event === 'install_plugin_result')).toEqual([ + ['install_plugin_result', expect.objectContaining({ input_value: 'dsh-new', is_success: false, error_reason: 'invalid-registry' })], + ]) // Typing again clears the refusal; a URL is asked as typed, trimmed. face.chooseRegistry({ kind: 'custom', url: ' https://npm.corp.example ' }) expect(state().install.registryError).toBe(false) @@ -1168,6 +1446,9 @@ describe('PluginManagerController', () => { expect(plugins.inspect).toHaveBeenCalledWith('dsh-new', { registry: 'https://npm.corp.example' }, expect.any(AbortSignal)) await vi.waitFor(() => { expect(state().install.phase).toBe('done') }) expect(plugins.installBundle).toHaveBeenCalledWith('dsh-new', expect.objectContaining({ registry: 'https://npm.corp.example/' })) + const results = track.mock.calls.filter(([event]) => event === 'install_plugin_result') + expect(results).toHaveLength(2) + expect(results[1]).toEqual(['install_plugin_result', expect.objectContaining({ is_success: true, plugin_name: 'dsh-new' })]) // A dialog opened later, by another controller, starts from the registry last used. const later = bench() later.face.openInstall() @@ -1412,3 +1693,102 @@ it('recognizes the official registry without a trailing slash and with uppercase face.openInstall() await vi.waitFor(() => { expect(state().install.registry).toEqual({ kind: 'offered', registry: MIRROR }) }) }) + + +describe('desktop analytics outcomes', () => { + it('redacts authenticated installer URLs from click and failed-result events', async () => { + const b = bench({ inspect: vi.fn(async () => ok({ status: 'refused', problem: 'not-bundle', reason: 'refused' })) }) + b.face.openInstall() + b.face.editInstallSpec('git+https://user:private-token@example.invalid/repo.git?token=private-token') + b.face.runInstall() + await vi.waitFor(() => { expect(b.track).toHaveBeenCalledWith('install_plugin_result', expect.objectContaining({ input_value: '[git]' })) }) + expect(b.track).toHaveBeenCalledWith('plugin_install_click', { input_value: '[git]' }) + expect(JSON.stringify(b.track.mock.calls)).not.toContain('private-token') + }) + + it('reports input inspection failure separately from cancellation', async () => { + const b = bench({ inspect: vi.fn(async () => ok({ status: 'refused', problem: 'not-bundle', reason: 'not a bundle' })) }) + b.face.openInstall() + b.face.editInstallSpec('dsh-new') + b.face.runInstall() + await vi.waitFor(() => { expect(b.track).toHaveBeenCalledWith('install_plugin_result', expect.objectContaining({ input_value: 'dsh-new', is_success: false, error_reason: 'not-bundle', duration: expect.any(Number) as number })) }) + expect(b.track).toHaveBeenCalledWith('plugin_install_click', { input_value: 'dsh-new' }) + }) + + it('reports unknown only after recovery confirms the result is absent', async () => { + const lost = deferred>>() + const b = bench({ installBundle: vi.fn(async () => refused('gateway/internal', 'offline')), waitForInstall: vi.fn(() => lost.promise) }) + b.face.openInstall() + b.face.editInstallSpec('dsh-new') + b.face.runInstall() + await vi.waitFor(() => { expect(b.plugins.waitForInstall).toHaveBeenCalledTimes(1) }) + expect(b.track.mock.calls.filter(call => call[0] === 'install_plugin_result')).toEqual([]) + lost.resolve(ok(null)) + await vi.waitFor(() => { expect(b.track).toHaveBeenCalledWith('install_plugin_result', expect.objectContaining({ error_reason: 'unknown_result', is_success: false })) }) + b.face.reconcileInstall() + expect(b.track.mock.calls.filter(call => call[0] === 'install_plugin_result')).toHaveLength(1) + }) + + it('closing during inspection reports user_cancelled once', async () => { + const inspecting = deferred>>() + const b = bench({ inspect: vi.fn(() => inspecting.promise) }) + b.face.openInstall() + b.face.editInstallSpec('dsh-new') + b.face.runInstall() + await vi.waitFor(() => { expect(b.plugins.inspect).toHaveBeenCalledTimes(1) }) + b.face.closeInstall() + inspecting.resolve(ok(INSPECTED)) + await Promise.resolve() + const results = b.track.mock.calls.filter(call => call[0] === 'install_plugin_result') + expect(results).toHaveLength(1) + expect(results[0]?.[1]).toMatchObject({ error_reason: 'user_cancelled', is_success: false }) + expect(results[0]?.[1]).not.toHaveProperty('result_status') + expect(results[0]?.[1]).not.toHaveProperty('plugin_type') + expect(b.plugins.installBundle).not.toHaveBeenCalled() + }) + + it('uses bundle and plugin types only after successful changes', async () => { + const b = bench() + await b.controller.load() + b.face.setEnabled(BUNDLE.name, true) + await vi.waitFor(() => { expect(b.track).toHaveBeenCalledWith('plugin_toggle', { plugin_name: BUNDLE.name, plugin_type: 'bundle', is_enabled: true, is_builtin: false }) }) + b.face.setRowEnabled(ROW_ENTRY, false) + await vi.waitFor(() => { expect(b.track).toHaveBeenCalledWith('plugin_toggle', { plugin_name: BUNDLE.name, plugin_type: 'plugin', is_enabled: false, is_builtin: false }) }) + b.plugins.setBundleEnabled.mockResolvedValueOnce(ok({ ...APPLIED, application: 'cancelled' })) + b.face.setEnabled(BUNDLE.name, false) + await vi.waitFor(() => { expect(b.state().busy).toEqual([]) }) + expect(b.track.mock.calls.filter(call => call[0] === 'plugin_toggle')).toHaveLength(2) + }) +}) + + +it('does not retain install identity when analytics is disabled', async () => { + const b = bench({}, false) + b.face.openInstall() + b.face.editInstallSpec('dsh-new') + b.face.runInstall() + await vi.waitFor(() => { expect(b.state().install.phase).toBe('done') }) + expect(b.track.mock.calls.filter(([name]) => name === 'plugin_install_click' || name === 'install_plugin_result')).toEqual([]) +}) + +it('reports restart-required row toggles and tolerates a vanished inventory entry', async () => { + const b = bench({ setPluginEnabled: vi.fn(async () => ok({ ...APPLIED, application: 'restart-required' })) }) + await b.controller.load() + b.face.setRowEnabled(ROW_ENTRY, true) + await vi.waitFor(() => { expect(b.track).toHaveBeenCalledWith('plugin_toggle', expect.objectContaining({ plugin_type: 'plugin' })) }) + b.face.setEnabled('vanished-package', true) + await vi.waitFor(() => { expect(b.state().busy).toEqual([]) }) + expect(b.track.mock.calls.filter(([name]) => name === 'plugin_toggle')).toHaveLength(1) +}) + +it('reports a successful install with only documented result fields', async () => { + const b = bench() + b.face.openInstall() + b.face.editInstallSpec('dsh-new') + b.face.runInstall() + await vi.waitFor(() => { expect(b.state().install.phase).toBe('done') }) + const results = b.track.mock.calls.filter(([name]) => name === 'install_plugin_result') + expect(results).toEqual([['install_plugin_result', { + input_value: 'dsh-new', is_success: true, duration: expect.any(Number) as number, plugin_name: 'dsh-new', + }]]) +}) diff --git a/packages/client/ui-plugin-manager/tests/sanitize-install-input.client.spec.ts b/packages/client/ui-plugin-manager/tests/sanitize-install-input.client.spec.ts new file mode 100644 index 0000000000..d3e3e2bc17 --- /dev/null +++ b/packages/client/ui-plugin-manager/tests/sanitize-install-input.client.spec.ts @@ -0,0 +1,17 @@ +import { expect, it } from 'vitest' +import { sanitizeInstallInput } from '../src/client/sanitize-install-input.ts' + +it.each(['dsh-example', '@scope/plugin', '@scope/plugin@1.2.3', 'plugin@latest'])('retains a registry identifier: %s', (spec) => { + expect(sanitizeInstallInput(spec)).toBe(spec) +}) + +it.each([ + ['git+https://user:secret@example.invalid/org/repo.git?token=secret#secret', '[git]'], + ['https://user:secret@example.invalid/archive.tgz?signature=secret#secret', '[url]'], + ['git@example.invalid:private/repo', '[git]'], + ['/Users/private-name/plugin', '[path-or-other]'], + ['C:\\Users\\private-name\\plugin', '[path-or-other]'], + ['plugin@https://user:secret@example.invalid/archive.tgz', '[path-or-other]'], +])('removes private installer input: %s', (spec, expected) => { + expect(sanitizeInstallInput(spec)).toBe(expected) +}) diff --git a/packages/client/ui-plugin-manager/tsconfig.client.json b/packages/client/ui-plugin-manager/tsconfig.client.json index 4d56e3dee7..5f8c1f5e42 100644 --- a/packages/client/ui-plugin-manager/tsconfig.client.json +++ b/packages/client/ui-plugin-manager/tsconfig.client.json @@ -47,6 +47,9 @@ }, { "path": "../ui-settings/tsconfig.client.json" + }, + { + "path": "../product-analytics/tsconfig.client.json" } ], "include": [ diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml index 6203412c5d..9df146dd15 100644 --- a/packages/client/ui-primitives/README.i18n.yaml +++ b/packages/client/ui-primitives/README.i18n.yaml @@ -18,8 +18,8 @@ en: ddec1f6f9b018747 zh: 9555f132daf8901c /deepseek-ai-dsh-client-ui-primitives/use-this-package/component-catalog: - en: 54ced5d959bd06c6 - zh: 5a7fc2504f92a788 + en: 27c3b3715866df73 + zh: 65c07b00516149ad /deepseek-ai-dsh-client-ui-primitives/use-this-package/controls-and-icons: en: 83052e14c3fb34cf zh: 0adb09885723296a diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md index c9f0cb4a5a..0da0f9f934 100644 --- a/packages/client/ui-primitives/README.md +++ b/packages/client/ui-primitives/README.md @@ -55,7 +55,7 @@ Check this table before writing a control in a feature package. A plugin cannot | `DisclosureRow` | 24px compact disclosure that lays title and content side by side. Memoized with shallow prop comparison; keep callbacks and React-node props stable when their content is unchanged. | | `Modal` | Centered dialog over a page mask. A nested dialog can intercept keys with `onKeyDownCapture` before document Escape handlers. The tint and dialog fade in while backdrop blur stays fully applied, honoring reduced motion. Set `backdropBlur={false}` when the caller already blurs the source page. | | `RiskConfirmation` | Sensitive action gated behind an explicit checkbox. | -| `Tooltip` | Hover text anchored to a cloned child; optional `portal` rendering escapes clipping containers and ancestor stacking contexts that cap the bubble's z-index. | +| `Tooltip` | Hover and keyboard-focus text anchored to a cloned child; optional `delayMs` controls hover delay and `focusDelayMs` controls keyboard-focus delay, both defaulting to 0 ms. Optional `portal` rendering escapes clipping containers and ancestor stacking contexts that cap the bubble's z-index. | | `HoverCard` | Hover preview the pointer can rest on and select from; optional copy button. | | `ImageLightbox` | Shared image modal with focus restoration and Escape dismissal. | | `Toast` | Transient top-center banner held for the owner's `holdMs`. | diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md index de6adf1a2d..f22fa7b540 100644 --- a/packages/client/ui-primitives/README.zh.md +++ b/packages/client/ui-primitives/README.zh.md @@ -55,7 +55,7 @@ kind: "package-library" | `DisclosureRow` | 24px 紧凑折叠行，标题与内容左右排列。使用浅层 prop 比较进行 memo；内容未变时，保持回调与 React 节点 prop 的引用稳定。 | | `Modal` | 页面遮罩之上的居中对话框。嵌套对话框可通过 `onKeyDownCapture` 在文档级 Escape 处理器之前拦截按键。 色层与弹窗淡入，背景模糊始终完整生效，并遵循减少动态效果偏好。调用方已模糊源页面时设置 `backdropBlur={false}`。 | | `RiskConfirmation` | 以显式复选框把关的敏感操作确认。 | -| `Tooltip` | 锚定在克隆子元素上的悬停文本；可通过 `portal` 渲染到外层，避免被容器裁剪，或受祖先层叠上下文限制其 z-index。 | +| `Tooltip` | 锚定在克隆子元素上的悬停与键盘聚焦提示；可选的 `delayMs` 控制悬停延迟，`focusDelayMs` 控制键盘聚焦延迟，均默认为 0 毫秒。可通过 `portal` 渲染到外层，避免被容器裁剪，或受祖先层叠上下文限制其 z-index。 | | `HoverCard` | 指针可停留、可选中的悬停预览；可选带复制按钮。 | | `ImageLightbox` | 共享图片浮层，支持焦点恢复与 Esc 关闭。 | | `Toast` | 顶部居中的瞬时横幅，保持时长由所有者的 `holdMs` 决定。 | diff --git a/packages/client/ui-primitives/src/Tooltip.tsx b/packages/client/ui-primitives/src/Tooltip.tsx index 3d0783c422..b997279f54 100644 --- a/packages/client/ui-primitives/src/Tooltip.tsx +++ b/packages/client/ui-primitives/src/Tooltip.tsx @@ -40,7 +40,9 @@ type TooltipLabel = string | (() => string) * bubble would overlap); default 'center'. Ignored for side 'right'. * @param props.portal - render the bubble under document.body, so an ancestor's clipping or its * stacking context (which confines the bubble's z-index to that context) cannot hide it. - * @param props.delayMs - hover delay in milliseconds; keyboard focus remains immediate. + * @param props.delayMs - hover delay in milliseconds (default 0). + * @param props.focusDelayMs - keyboard focus delay in milliseconds (default 0); blur, click, + * mouse leave, disabling, and unmount cancel a pending show. * @param props.gap - anchor-to-bubble distance in pixels for 'bottom'/'top' bubbles (default 8); * ignored for side 'right'. * @param props.disabled - suppress the bubble while true; the anchor renders identically so @@ -53,7 +55,7 @@ type TooltipLabel = string | (() => string) * anchor dismisses the bubble until the next trigger, and focus arriving after a pointer * interaction (a closing menu refocusing its trigger) never raises it. */ -export function Tooltip({ label, shortcutKeys, side = 'right', align = 'center', delayMs = 0, gap = 8, disabled = false, portal = false, maxWidth, children }: { label: TooltipLabel; shortcutKeys?: readonly string[] | undefined; side?: TooltipSide; align?: 'center' | 'end'; delayMs?: number; gap?: number; disabled?: boolean; portal?: boolean; maxWidth?: number; children: ReactElement }) { +export function Tooltip({ label, shortcutKeys, side = 'right', align = 'center', delayMs = 0, focusDelayMs = 0, gap = 8, disabled = false, portal = false, maxWidth, children }: { label: TooltipLabel; shortcutKeys?: readonly string[] | undefined; side?: TooltipSide; align?: 'center' | 'end'; delayMs?: number; focusDelayMs?: number; gap?: number; disabled?: boolean; portal?: boolean; maxWidth?: number; children: ReactElement }) { const anchor = useRef(null) // React 18 keeps the element's ref outside props; forward it so wrapping an // anchor in Tooltip never silently severs the owner's ref. @@ -157,16 +159,16 @@ export function Tooltip({ label, shortcutKeys, side = 'right', align = 'center', }) announce(true) } - const showAfterHoverDelay = () => { + const showAfterDelay = (delay: number) => { cancelShow() - if (delayMs <= 0) { + if (delay <= 0) { show() return } showTimer.current = setTimeout(() => { showTimer.current = null show() - }, delayMs) + }, delay) } const withdraw = () => { setPos(null) @@ -198,13 +200,18 @@ export function Tooltip({ label, shortcutKeys, side = 'right', align = 'center', {cloneElement(children, { ref: mergedRef, - onMouseEnter: (e) => { children.props.onMouseEnter?.(e); triggers.current.hover = true; showAfterHoverDelay() }, + onMouseEnter: (e) => { children.props.onMouseEnter?.(e); triggers.current.hover = true; showAfterDelay(delayMs) }, onMouseLeave: (e) => { children.props.onMouseLeave?.(e); triggers.current.hover = false; cancelShow(); withdraw() }, // Activating the anchor dismisses the bubble: the action often changes // what the anchor now does (pin → unpin), and the click leaves the // anchor focused, which would otherwise pin the relabelled bubble up. onClick: (e) => { children.props.onClick?.(e); triggers.current.focus = false; cancelShow(); withdraw() }, - onFocus: (e) => { children.props.onFocus?.(e); if (pointerModality()) return; triggers.current.focus = true; cancelShow(); show() }, + onFocus: (e) => { + children.props.onFocus?.(e) + if (pointerModality()) return + triggers.current.focus = true + showAfterDelay(focusDelayMs) + }, onBlur: (e) => { children.props.onBlur?.(e); triggers.current.focus = false; hide() }, })} {portal ? (content !== false && createPortal(content, document.body)) : content} diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts index 0e4cc0a527..57511f4dab 100644 --- a/packages/client/ui-primitives/src/index.ts +++ b/packages/client/ui-primitives/src/index.ts @@ -59,6 +59,7 @@ export type { export { projectUserText, type UserTextReferences } from './user-text.tsx' export { Tooltip } from './Tooltip.tsx' export type { TooltipSide } from './Tooltip.tsx' +export { pointerModality } from './input-modality.ts' export { Toast } from './Toast.tsx' export { fileSizeText } from './file-size.ts' export { writeClipboard } from './clipboard.ts' diff --git a/packages/client/ui-primitives/src/plugin-artwork.tsx b/packages/client/ui-primitives/src/plugin-artwork.tsx index 374d99e138..8fdbadb711 100644 --- a/packages/client/ui-primitives/src/plugin-artwork.tsx +++ b/packages/client/ui-primitives/src/plugin-artwork.tsx @@ -70,13 +70,13 @@ export const PluginArtworkSearch = ({ size = 36, className }: IconProps) => { const uid = useArtworkId() return ( - +
{ expect(container.querySelector('foreignObject div')).not.toBeNull() }) + it('pairs the search green with the loop upper-right blue-violet in its ring and handle', () => { + const { container } = render() + const ring = container.querySelector('foreignObject div') + expect(ring?.style.background).toBe('conic-gradient(from 90deg, rgb(65, 225, 172) 0deg, rgb(101, 142, 255) 62.0619deg, rgb(65, 225, 172) 360deg)') + expect(container.querySelector('path[stroke]')?.getAttribute('stroke')).toBe('#658EFF') + }) + + it('uses light blue for both terminal strokes', () => { + const { container } = render() + const strokes = [...container.querySelectorAll('path')].map(path => path.getAttribute('stroke')) + expect(strokes).toEqual(['#679EFE', '#679EFE']) + expect(container.querySelector('linearGradient')).toBeNull() + }) + it.each(Object.entries(artworks))('%s renders at 36 by default and repeats without document-global ids', (_name, Artwork) => { const { container } = render( <> @@ -46,8 +60,8 @@ describe('plugin artwork', () => { for (const svg of container.querySelectorAll('svg')) expect(svg.getAttribute('width')).toBe('36') const ids = [...container.querySelectorAll('[id]')].map(node => node.id) expect(new Set(ids).size).toBe(ids.length) - for (const reference of container.querySelectorAll('[fill^="url("], [clip-path^="url("]')) { - const target = (reference.getAttribute('fill') ?? reference.getAttribute('clip-path') ?? '').slice('url(#'.length, -1) + for (const reference of container.querySelectorAll('[fill^="url("], [stroke^="url("], [clip-path^="url("]')) { + const target = (reference.getAttribute('fill') ?? reference.getAttribute('stroke') ?? reference.getAttribute('clip-path') ?? '').slice('url(#'.length, -1) expect(ids).toContain(target) } }) diff --git a/packages/client/ui-primitives/tests/tooltip.client.spec.tsx b/packages/client/ui-primitives/tests/tooltip.client.spec.tsx index 3d109a91bf..e681afae06 100644 --- a/packages/client/ui-primitives/tests/tooltip.client.spec.tsx +++ b/packages/client/ui-primitives/tests/tooltip.client.spec.tsx @@ -120,6 +120,85 @@ describe('Tooltip', () => { } }) + describe('keyboard focus delay', () => { + beforeEach(() => { + vi.useFakeTimers() + fireEvent.keyDown(document.body, { key: 'Tab' }) + }) + afterEach(() => { + cleanup() + vi.useRealTimers() + fireEvent.keyDown(document.body, { key: 'Tab' }) + }) + + it('shows at 500ms, but not at 499ms', () => { + const label = vi.fn(() => 'Refresh') + render() + fireEvent.focus(screen.getByText('anchor')) + expect(screen.queryByRole('tooltip')).toBeNull() + act(() => { vi.advanceTimersByTime(499) }) + expect(screen.queryByRole('tooltip')).toBeNull() + expect(label).not.toHaveBeenCalled() + act(() => { vi.advanceTimersByTime(1) }) + expect(screen.getByRole('tooltip').textContent).toBe('Refresh') + }) + + it.each(['blur', 'click', 'mouseLeave', 'disabled', 'unmount'] as const)( + 'cancels a pending focus bubble on %s', (cancel) => { + const view = render() + const anchor = screen.getByText('anchor') + const initialTimers = vi.getTimerCount() + fireEvent.focus(anchor) + expect(vi.getTimerCount()).toBe(initialTimers + 1) + act(() => { vi.advanceTimersByTime(499) }) + if (cancel === 'disabled') { + view.rerender() + } else if (cancel === 'unmount') { + view.unmount() + } else { + fireEvent[cancel](anchor) + } + expect(vi.getTimerCount()).toBe(initialTimers) + act(() => { vi.advanceTimersByTime(500) }) + expect(screen.queryByRole('tooltip')).toBeNull() + if (cancel === 'disabled') { + view.rerender() + expect(screen.queryByRole('tooltip')).toBeNull() + } + }, + ) + + it('keeps default focus immediate and cancels a pending hover delay', () => { + render() + const anchor = screen.getByText('anchor') + const initialTimers = vi.getTimerCount() + fireEvent.mouseEnter(anchor) + act(() => { vi.advanceTimersByTime(499) }) + expect(screen.queryByRole('tooltip')).toBeNull() + fireEvent.focus(anchor) + expect(screen.getByRole('tooltip').textContent).toBe('Refresh') + expect(vi.getTimerCount()).toBe(initialTimers) + }) + + it('does not schedule pointer-driven focus and resumes delay after a key press', () => { + render() + const anchor = screen.getByText('anchor') + const initialTimers = vi.getTimerCount() + fireEvent.pointerDown(document.body) + fireEvent.focus(anchor) + expect(vi.getTimerCount()).toBe(initialTimers) + act(() => { vi.advanceTimersByTime(500) }) + expect(screen.queryByRole('tooltip')).toBeNull() + fireEvent.blur(anchor) + fireEvent.keyDown(document.body, { key: 'Tab' }) + fireEvent.focus(anchor) + act(() => { vi.advanceTimersByTime(499) }) + expect(screen.queryByRole('tooltip')).toBeNull() + act(() => { vi.advanceTimersByTime(1) }) + expect(screen.getByRole('tooltip').textContent).toBe('Refresh') + }) + }) + it('shows the bubble to the right on hover and hides it on leave', () => { render( diff --git a/packages/client/ui-schedule/README.i18n.yaml b/packages/client/ui-schedule/README.i18n.yaml index 9797b69beb..8866d6e127 100644 --- a/packages/client/ui-schedule/README.i18n.yaml +++ b/packages/client/ui-schedule/README.i18n.yaml @@ -15,8 +15,8 @@ en: d152484eb41ac6b4 zh: 405b30feaf48c087 /deepseek-ai-dsh-client-ui-schedule/use-this-package: - en: 3594ab6704cbd7b9 - zh: 99a965f43187501b + en: c129ae5d0a150a5d + zh: d81976f2840cb059 /deepseek-ai-dsh-client-ui-schedule/use-this-package/time-zone-data-source: en: 6bd6882dbbbefcb0 zh: 03aa15f1a65d13dc diff --git a/packages/client/ui-schedule/README.md b/packages/client/ui-schedule/README.md index 577e9e4ccc..ed9431a6b5 100644 --- a/packages/client/ui-schedule/README.md +++ b/packages/client/ui-schedule/README.md @@ -25,7 +25,7 @@ Manage active and inactive tasks from the Automation tasks page and the right Si ## Use this package -The shipped Web bundle mounts `ui-schedule` with the Host Schedule service and the clock context that supplies the model's current time. The Automation tasks sidebar entry opens a global page without selecting or activating a Session. The page header's New action starts a new Session, where the reminder is created by asking the model; the page itself has no creation form. Its task list supports text search and one All, Enabled, and Inactive status filter row; search matches the stored task name, the instruction, and the internal Session id, not a resolved Session title, and the empty state keeps the heading's New action beside the notice. Selecting an active or inactive task opens a second detail level with Rules and Delivery records tabs. Every list row shows the task's stored title with its status, frequency, and next run and never the original Session name; the detail's name control shows the stored title. Rules contains the complete reminder, status, next target for active tasks, original recurrence rule, and task id. Daily rule labels show the saved local time and exact stored IANA zone, preserving nonzero seconds and milliseconds rather than substituting the browser's zone. The Linked session entry in the detail tab strip names the linked Session by its catalog title, falling back to the Session id when no title is available. It opens an available, unarchived Session after metadata loads; pending Session or Workspace metadata, an archived Session, missing Session membership, or a Workspace query error keeps it disabled with an explanation. The click rechecks availability; browsing does not unarchive the Session. Only this action requests Session activation. Deletion is available from the More task actions menu in the detail's top strip, separate from navigation. +The shipped Web composition carries no `ui-schedule` row; enable the optional experimental bundle `@deepseek-ai/dsh-experimental-schedule-bundle` from the Plugins page (Official group), or list it in a profile's `dsh.profile.bundles`, to insert and mount `ui-schedule` with the Host Schedule service and the clock context that supplies the model's current time. The Automation tasks sidebar entry opens a global page without selecting or activating a Session. The page header's New action starts a new Session, where the reminder is created by asking the model; the page itself has no creation form. Its task list supports text search and one All, Enabled, and Inactive status filter row; search matches the stored task name, the instruction, and the internal Session id, not a resolved Session title, and the empty state keeps the heading's New action beside the notice. Selecting an active or inactive task opens a second detail level with Rules and Delivery records tabs. Every list row shows the task's stored title with its status, frequency, and next run and never the original Session name; the detail's name control shows the stored title. Rules contains the complete reminder, status, next target for active tasks, original recurrence rule, and task id. Daily rule labels show the saved local time and exact stored IANA zone, preserving nonzero seconds and milliseconds rather than substituting the browser's zone. The Linked session entry in the detail tab strip names the linked Session by its catalog title, falling back to the Session id when no title is available. It opens an available, unarchived Session after metadata loads; pending Session or Workspace metadata, an archived Session, missing Session membership, or a Workspace query error keeps it disabled with an explanation. The click rechecks availability; browsing does not unarchive the Session. Only this action requests Session activation. Deletion is available from the More task actions menu in the detail's top strip, separate from navigation. Selecting a task from the list opens Rules; refreshing that task preserves the selected tab. Rules edits an active task's name, instruction, and run time; the edits stay in a local draft until saved, and inactive tasks remain read-only. Unmodified Left/Right arrows cycle the tabs, Home/End select the first/last tab, and keyboard focus follows the selection. The tabs do not consume these keys with Alt, Ctrl, Meta, or Shift. The linked-Session control in the detail tab strip stays available on the Rules tab, and confirmed deletion is available from either view. diff --git a/packages/client/ui-schedule/README.zh.md b/packages/client/ui-schedule/README.zh.md index 743d8a5525..d03aefa658 100644 --- a/packages/client/ui-schedule/README.zh.md +++ b/packages/client/ui-schedule/README.zh.md @@ -25,7 +25,7 @@ kind: "package-reference" ## 使用本包 -发布的 Web bundle 将 `ui-schedule` 与 Host Schedule 服务、以及为模型提供当前时间的时钟上下文一起挂载。侧栏的自动化任务入口打开全局页面，不选择或激活会话。页面页头的“新建”操作会打开一个新会话，提醒由模型在该会话中创建；页面本身没有创建表单。列表支持文本搜索和一行“全部/已开启/未运行”状态筛选；搜索匹配任务已存储的名称、指令和内部会话 id，不匹配解析出的会话标题，空状态在提示旁保留页头的“新建”操作。选择活动或未运行任务后，进入含“规则”和“任务运行记录”页签的第二层详情。每条列表行显示任务已存储的标题及其状态、频率和下次运行，不显示原会话名称；详情中的名称输入框显示任务已存储的标题。“规则”显示完整提醒、状态、活动任务的下一目标时间、原始重复规则和任务 id。每天的规则标签显示已保存的本地时间与精确的存储 IANA 时区，保留非零秒与毫秒，而不替换为浏览器时区。详情页签条内的“关联会话”入口按会话标题显示，取不到标题时回退显示会话 id。元数据加载后，它可打开可用且未归档的会话；会话或 Workspace 元数据尚未就绪、会话已归档、会话不在列表中或 Workspace 查询失败时，入口保持禁用并显示原因。点击时会重新检查可用性；浏览不会取消会话归档。仅此操作请求激活会话。删除位于详情顶部条带的“更多任务操作”菜单。 +随发行版交付的 Web 组合不含 `ui-schedule` 行；在插件管理页的“官方”分组中启用可选实验性 bundle `@deepseek-ai/dsh-experimental-schedule-bundle`，或把它列进 profile 的 `dsh.profile.bundles`，即可插入 `ui-schedule` 并将它与 Host Schedule 服务、以及为模型提供当前时间的时钟上下文一起挂载。侧栏的自动化任务入口打开全局页面，不选择或激活会话。页面页头的“新建”操作会打开一个新会话，提醒由模型在该会话中创建；页面本身没有创建表单。列表支持文本搜索和一行“全部/已开启/未运行”状态筛选；搜索匹配任务已存储的名称、指令和内部会话 id，不匹配解析出的会话标题，空状态在提示旁保留页头的“新建”操作。选择活动或未运行任务后，进入含“规则”和“任务运行记录”页签的第二层详情。每条列表行显示任务已存储的标题及其状态、频率和下次运行，不显示原会话名称；详情中的名称输入框显示任务已存储的标题。“规则”显示完整提醒、状态、活动任务的下一目标时间、原始重复规则和任务 id。每天的规则标签显示已保存的本地时间与精确的存储 IANA 时区，保留非零秒与毫秒，而不替换为浏览器时区。详情页签条内的“关联会话”入口按会话标题显示，取不到标题时回退显示会话 id。元数据加载后，它可打开可用且未归档的会话；会话或 Workspace 元数据尚未就绪、会话已归档、会话不在列表中或 Workspace 查询失败时，入口保持禁用并显示原因。点击时会重新检查可用性；浏览不会取消会话归档。仅此操作请求激活会话。删除位于详情顶部条带的“更多任务操作”菜单。 从列表选择任务时默认打开“规则”；刷新同一任务会保留当前页签。活动任务的“规则”修改名称、指令和运行时间；这些修改保留在本地草稿中直到保存，未运行任务保持只读。不带修饰键的左右方向键循环切换页签，Home/End 选择第一个/最后一个页签，键盘焦点随选择移动。页签不会拦截这些键与 Alt、Ctrl、Meta 或 Shift 的组合。共用的会话入口位于详情页签条内，在“规则”页签可见；确认删除操作在两种页签下都可用。 diff --git a/packages/client/ui-schedule/locale/en.json b/packages/client/ui-schedule/locale/en.json new file mode 100644 index 0000000000..7564e0fff7 --- /dev/null +++ b/packages/client/ui-schedule/locale/en.json @@ -0,0 +1,6 @@ +{ + "meta": { + "title": "Task interface", + "description": "The Automation tasks page in the sidebar, plus task cards and reminder marks in sessions." + } +} diff --git a/packages/client/ui-schedule/locale/zh.json b/packages/client/ui-schedule/locale/zh.json new file mode 100644 index 0000000000..b9b7495eaa --- /dev/null +++ b/packages/client/ui-schedule/locale/zh.json @@ -0,0 +1,6 @@ +{ + "meta": { + "title": "任务界面", + "description": "侧栏的自动化任务页面，以及会话里的任务卡片和提醒标记。" + } +} diff --git a/packages/client/ui-schedule/package.json b/packages/client/ui-schedule/package.json index f4979f5921..665d1bca90 100644 --- a/packages/client/ui-schedule/package.json +++ b/packages/client/ui-schedule/package.json @@ -15,7 +15,8 @@ "default": "./lib/client.js" }, "./src/*": "./src/*", - "./package.json": "./package.json" + "./package.json": "./package.json", + "./locale/*.json": "./locale/*.json" }, "dsh": { "client": { @@ -81,6 +82,7 @@ "react-dom": "^18.2.0" }, "files": [ + "locale/*.json", "lib/index.js", "lib/client.js", "lib/types/**/*.d.ts" diff --git a/packages/client/ui-settings-account/README.i18n.yaml b/packages/client/ui-settings-account/README.i18n.yaml index 75f9483e09..cb0531a5d8 100644 --- a/packages/client/ui-settings-account/README.i18n.yaml +++ b/packages/client/ui-settings-account/README.i18n.yaml @@ -6,8 +6,8 @@ en: 1fcba8f273b661fb zh: 14e1236f84ae39d7 /deepseek-ai-dsh-client-ui-settings-account: - en: 76e18729c08888be - zh: 170a2032838071b4 + en: 9ff7ac2d70f70b59 + zh: ded522c4cfd6e040 /deepseek-ai-dsh-client-ui-settings-account/summary: en: 9ff357621753be69 zh: 3f7ede82acc9fa31 diff --git a/packages/client/ui-settings-account/README.md b/packages/client/ui-settings-account/README.md index e93210f5fe..a417443c7b 100644 --- a/packages/client/ui-settings-account/README.md +++ b/packages/client/ui-settings-account/README.md @@ -7,6 +7,8 @@ kind: "package-reference" English | [中文](README.zh.md) +Desktop product events use the optional [product analytics service](../product-analytics/README.md); ordinary Web interactions are excluded. Workspace login dialogs emit no authentication events; native welcome owns authentication analytics. + Server-expired account credentials clear the displayed account details and emit a localized sign-in reminder toast once; account snapshot replay does not repeat it. ## Summary diff --git a/packages/client/ui-settings-account/README.zh.md b/packages/client/ui-settings-account/README.zh.md index 44c442f7be..2d357ee54c 100644 --- a/packages/client/ui-settings-account/README.zh.md +++ b/packages/client/ui-settings-account/README.zh.md @@ -7,6 +7,8 @@ kind: "package-reference" [English](README.md) | 中文 +桌面端产品事件使用可选的[产品埋点服务](../product-analytics/README.zh.md)，不包含普通 Web 交互。工作区内的登录弹窗不发送认证事件；认证埋点由原生欢迎页负责。 + 账号凭据被服务端判定失效后，清空显示的账号详情，并弹出一次本地化的重新登录提示 toast；账号快照重放不会重复提示。 ## 概述 diff --git a/packages/client/ui-settings-account/package.json b/packages/client/ui-settings-account/package.json index 479ec0f0a6..c895148b8a 100644 --- a/packages/client/ui-settings-account/package.json +++ b/packages/client/ui-settings-account/package.json @@ -69,7 +69,8 @@ "@deepseek-ai/dsh-client-ui-settings-models": "workspace:*", "@types/react-dom": "~18.3.0", "@deepseek-ai/dsh-host-webserver": "workspace:*", - "big.js": "^7.0.1" + "big.js": "^7.0.1", + "@deepseek-ai/dsh-client-product-analytics": "workspace:*" }, "files": [ "lib/index.js", diff --git a/packages/client/ui-settings-account/src/client/DesktopOnboarding.tsx b/packages/client/ui-settings-account/src/client/DesktopOnboarding.tsx index 5bfd37dfd2..99c1bc4d2a 100644 --- a/packages/client/ui-settings-account/src/client/DesktopOnboarding.tsx +++ b/packages/client/ui-settings-account/src/client/DesktopOnboarding.tsx @@ -1,4 +1,5 @@ /** Coordinates onboarding navigation, transitions and the shared native recharge page. */ +import type { ProductEventMap } from '@deepseek-ai/dsh-client-product-analytics/client' import { useEffect, useRef, useState } from 'react' import { Button } from '@deepseek-ai/dsh-client-ui-primitives' import { hasOnboardingCredit } from './onboarding-balance.ts' @@ -12,12 +13,20 @@ import { OnboardingConfirmation, type OnboardingConfirmationKind } from './Onboa import backIcon from './assets/onboarding-back.svg' import css from './DesktopOnboarding.module.css' +const onboardingPages = { + welcome: 'onboarding_welcome', + credit: 'onboarding_recharge', + purpose: 'onboarding_use_case', + process: 'onboarding_process', + done: undefined, +} as const + /** * @param props - durable choices, account state, localized copy and the shared recharge page channel. * @returns the active first-run page. */ export function DesktopOnboarding({ - state, account, openPlatformPage, update, complete, retry, t, locale, exiting = false, + state, account, openPlatformPage, update, complete, retry, t, locale, track, exiting = false, }: DesktopOnboardingProps) { const [dialog, setDialog] = useState(null) const heading = useRef(null) @@ -44,10 +53,37 @@ export function DesktopOnboarding({ return () => { animation.cancel() } }, [targetStep, step, state.visible]) useEffect(() => { heading.current?.focus() }, [step]) + const pageName = onboardingPages[step] + const shownPage = useRef(null) + useEffect(() => { + if (!state.visible || pageName === undefined || exiting) { + shownPage.current = null + return + } + if (state.status === 'loading') return + if (shownPage.current === pageName) return + shownPage.current = pageName + track?.('onboarding_page_view', { page_name: pageName }) + }, [state.visible, state.status, step, pageName, exiting, track]) + const shownPopup = useRef(null) + useEffect(() => { + if (dialog === null || !state.visible || state.status === 'loading' || step === 'done') { shownPopup.current = null; return } + if (shownPopup.current === dialog) return + shownPopup.current = dialog + track?.('onboarding_popup_view', { popup_name: dialog === 'skip' ? 'skip_setting' : 'skip_charge' }) + }, [dialog, track, state.visible, state.status, step]) + const popupClick = (button_name: ProductEventMap['onboarding_popup_click']['button_name']) => { + track?.('onboarding_popup_click', { popup_name: dialog === 'skip' ? 'skip_setting' : 'skip_charge', button_name }) + } if (state.visible && state.status === 'loading') return
{t('onboardingLoading')}
 - if (!state.visible || step === 'done') return null + if (!state.visible || pageName === undefined) return null + const click = (button_name: ProductEventMap['onboarding_page_click']['button_name']) => { + const selected_content = step === 'purpose' && progress.purpose !== null ? ({ office: 'office', development: 'code', both: 'code_office' } as const)[progress.purpose] + : step === 'process' && progress.process !== null ? ({ compact: 'focus_result', standard: 'key_detail', detailed: 'full_process' } as const)[progress.process] : undefined + track?.('onboarding_page_click', { page_name: pageName, button_name, ...selected_content === undefined ? {} : { selected_content } }) + } const go = (next: 'welcome' | 'credit' | 'purpose' | 'process') => { void update({ step: next }) } const canRecharge = openPlatformPage !== undefined const recharge = () => { @@ -68,22 +104,22 @@ export function DesktopOnboarding({ return <>
- {step === 'welcome' && { go('credit') }} />} + {step === 'welcome' && { click('next'); go('credit') }} />} {step === 'credit' && { go('purpose') }} onRecharge={recharge} onLater={later} />} + funded={state.creditFunded} canRecharge={canRecharge} onContinue={() => { click('continue'); go('purpose') }} onRecharge={() => { click('charge'); recharge() }} onLater={() => { click('later'); later() }} />} {step === 'purpose' && { void update({ purpose }) }} onContinue={purposeNext} />} + onSelect={(purpose) => { void update({ purpose }) }} onContinue={() => { click('next'); purposeNext() }} />} {step === 'process' && { void update({ process }) }} onComplete={() => { void complete('completed') }} />} + onSelect={(process) => { void update({ process }) }} onComplete={() => { click('next'); void complete('completed') }} />} {state.error !== null &&
{t('onboardingSaveFailed')}
} {step !== 'welcome' &&
- - + +
}
{dialog !== null && { setDialog(null) }} onContinue={() => { setDialog(null); go('purpose') }} onRecharge={recharge} - onSkip={() => { void complete('skipped').then(() => { setDialog(null) }) }} />} + onClose={() => { popupClick('close'); setDialog(null) }} onContinueSetup={() => { popupClick('setting'); setDialog(null) }} onContinue={() => { popupClick('know'); setDialog(null); go('purpose') }} onRecharge={() => { popupClick('charge'); recharge() }} + onSkip={() => { popupClick(dialog === 'skip' ? 'enter' : 'know'); void complete('skipped').then(() => { setDialog(null) }) }} />} } diff --git a/packages/client/ui-settings-account/src/client/OnboardingConfirmation.tsx b/packages/client/ui-settings-account/src/client/OnboardingConfirmation.tsx index 6793520a6e..6899334678 100644 --- a/packages/client/ui-settings-account/src/client/OnboardingConfirmation.tsx +++ b/packages/client/ui-settings-account/src/client/OnboardingConfirmation.tsx @@ -7,12 +7,13 @@ import css from './DesktopOnboarding.module.css' export type OnboardingConfirmationKind = 'credit' | 'credit-skip' | 'skip' /** @param props - confirmation action, localized copy and navigation callbacks. @returns a focus-contained dialog. */ -export function OnboardingConfirmation({ kind, t, busy, canRecharge, onClose, onContinue, onRecharge, onSkip }: +export function OnboardingConfirmation({ kind, t, busy, canRecharge, onClose, onContinueSetup, onContinue, onRecharge, onSkip }: Pick & { kind: OnboardingConfirmationKind busy: boolean canRecharge: boolean onClose: () => void + onContinueSetup: () => void onContinue: () => void onRecharge: () => void onSkip: () => void @@ -26,7 +27,7 @@ export function OnboardingConfirmation({ kind, t, busy, canRecharge, onClose, on

{t(credit ? 'onboardingNoCreditDescription' : 'onboardingSkipDescription')}

- +
diff --git a/packages/client/ui-settings-account/src/client/index.ts b/packages/client/ui-settings-account/src/client/index.ts index 9e4eef835c..e165c063b7 100644 --- a/packages/client/ui-settings-account/src/client/index.ts +++ b/packages/client/ui-settings-account/src/client/index.ts @@ -1,4 +1,5 @@ /** Desktop account settings registration and reconnecting Remote subscription. */ +import type {} from '@deepseek-ai/dsh-client-product-analytics/client' import type { TranscriptViewMode } from '@deepseek-ai/dsh-client-ui-chat/client' import type { Context } from '@deepseek-ai/cordis' import type {} from '@deepseek-ai/dsh-client-locale/client' @@ -24,7 +25,7 @@ import { en, zh, type AccountKey } from './locales.ts' import { AccountQuotaNotice, type AccountQuotaNoticeInjected } from './AccountQuotaNotice.tsx' import { DESKTOP_ONBOARDING_NAMESPACE, type OnboardingSettings } from '../onboarding-settings.ts' import { DesktopOnboardingController } from './onboarding-state.ts' -import { DesktopOnboardingEntry } from './DesktopOnboardingEntry.tsx' +import { DesktopOnboardingEntry, type DesktopOnboardingInjected } from './DesktopOnboardingEntry.tsx' import { readOnboardingApiKeyPresence } from './onboarding-credentials.ts' import { refreshAfterReturn } from './account-refresh.ts' export type { AccountSectionInjected, AccountSectionProps } from './AccountSection.tsx' @@ -211,7 +212,7 @@ export function apply(ctx: Context): void { if ('dshDesktop' in globalThis) { const controller = new DesktopOnboardingController( ctx.configForms.get(DESKTOP_ONBOARDING_NAMESPACE), - ctx.configForms.get<{ transcriptView: TranscriptViewMode; performanceUsage: 'compact' | 'detailed' }>('ui-chat'), + ctx.configForms.get<{ transcriptView?: TranscriptViewMode | null; performanceUsage: 'compact' | 'detailed' }>('ui-chat'), enabled => ctx.configForms.developerTools.setEnabled(enabled), operations.hooks.account, readOnboardingApiKeyPresence, @@ -229,13 +230,14 @@ export function apply(ctx: Context): void { }, 'account: desktop credential readiness') ctx.slots.inject('shell.overlay', () => ctx.slots.register({ name: 'shell.overlay', id: 'desktop-onboarding', locale: 'settings.account', - inject: () => ({ + inject: (): DesktopOnboardingInjected => ({ hooks: { account: operations.hooks.account, onboarding: controller.state }, // Onboarding's recharge return re-reads profile and balance only. ...nativePlatform === undefined ? {} : { openPlatformPage: platformPageOpener(refresh) }, update: (change: OnboardingChange) => controller.update(change), complete: (reason: 'completed' | 'skipped') => controller.complete(reason), retry: () => controller.retry(), + track: (name, attributes) => ctx.get('productAnalytics')?.track(name, attributes), }), }, DesktopOnboardingEntry)) } diff --git a/packages/client/ui-settings-account/src/client/onboarding-contract.ts b/packages/client/ui-settings-account/src/client/onboarding-contract.ts index 5c1a82081c..4d3815d90e 100644 --- a/packages/client/ui-settings-account/src/client/onboarding-contract.ts +++ b/packages/client/ui-settings-account/src/client/onboarding-contract.ts @@ -1,4 +1,5 @@ /** Pure view inputs for the desktop onboarding flow. */ +import type { TrackProductEvent } from '@deepseek-ai/dsh-client-product-analytics/client' import type { OnboardingProgress } from '../onboarding-settings.ts' import type { AccountSnapshot } from './AccountSection.tsx' import type { PlatformPages } from './platform-pages.ts' @@ -21,6 +22,8 @@ export type OnboardingChange = Partial, - private readonly chat: ConfigForm<{ transcriptView: TranscriptViewMode; performanceUsage: 'compact' | 'detailed' }>, + private readonly chat: ConfigForm<{ transcriptView?: TranscriptViewMode | null; performanceUsage: 'compact' | 'detailed' }>, private readonly setDeveloperTools: (enabled: boolean) => Promise, private readonly account: HostObservable, private readonly readApiKeyPresence: () => Promise, diff --git a/packages/client/ui-settings-account/tests/apply.client.spec.ts b/packages/client/ui-settings-account/tests/apply.client.spec.ts index 20a430fec6..393d5232ec 100644 --- a/packages/client/ui-settings-account/tests/apply.client.spec.ts +++ b/packages/client/ui-settings-account/tests/apply.client.spec.ts @@ -271,8 +271,13 @@ it('re-reads profile and balance but no bonus for the onboarding recharge return vi.stubGlobal('dshPlatform', { open: vi.fn(), setBounds: vi.fn(), close: vi.fn() }) await c.reload(SELF) const actions = operations(c) + const track = vi.fn() + c.ctx.provide('productAnalytics', { track } as never) + expect(actions).not.toHaveProperty('track') const onboarding = injectedOf(c.ctx.slots.entries('shell.overlay') .find(entry => entry.options.id === 'desktop-onboarding')!) as DesktopOnboardingInjected + onboarding.track?.('onboarding_page_view', { page_name: 'onboarding_recharge' }) + expect(track).toHaveBeenCalledWith('onboarding_page_view', { page_name: 'onboarding_recharge' }) const host = injectedOf(platformHostEntry(c)!) as AccountPlatformHostInjected c.mock.remote.account.getProfile.mockResolvedValue(ok(profile)) c.mock.remote.account.getBalance.mockResolvedValue(ok(null)) diff --git a/packages/client/ui-settings-account/tests/desktop-onboarding.client.spec.tsx b/packages/client/ui-settings-account/tests/desktop-onboarding.client.spec.tsx index 80f0d38930..8152510505 100644 --- a/packages/client/ui-settings-account/tests/desktop-onboarding.client.spec.tsx +++ b/packages/client/ui-settings-account/tests/desktop-onboarding.client.spec.tsx @@ -10,6 +10,7 @@ afterEach(() => { cleanup(); vi.unstubAllGlobals() }) function mount(step: DesktopOnboardingState['progress']['step'] = 'welcome', balance: 'zero' | 'positive' | 'bonus' | 'failed' | 'loading' = 'positive', status: DesktopOnboardingState['status'] = 'ready', copy: typeof zh = zh, creditFunded = false) { vi.stubGlobal('ResizeObserver', class { observe() {} disconnect() {} }) + const track = vi.fn() const complete = vi.fn(async () => true) const retry = vi.fn(async () => true) // The shared host owns the native view; this flow only requests a page from it. @@ -19,13 +20,15 @@ function mount(step: DesktopOnboardingState['progress']['step'] = 'welcome', bal returnFromPage = onClose return release }) + let changeStatus: (value: DesktopOnboardingState['status']) => void = () => {} const update = vi.fn(async (_change: Parameters[0]) => true) function App() { const [state, setState] = useState({ status, visible: true, error: status === 'error' ? 'settings' : null, creditFunded, progress: { version: 1, step, purpose: null, process: null, completion: null, usage: 'compact', developerTools: false }, }) - return copy[key]} complete={complete} retry={retry} + changeStatus = (value) => { setState(current => ({ ...current, status: value })) } + return copy[key]} complete={complete} retry={retry} update={async (change) => { setState(current => ({ ...current, status: 'saving' })) const saved = await update(change) @@ -38,7 +41,7 @@ function mount(step: DesktopOnboardingState['progress']['step'] = 'welcome', bal } render() return { - complete, openPlatformPage, release, update, retry, + complete, openPlatformPage, release, update, retry, track, changeStatus: (value: DesktopOnboardingState['status']) => { changeStatus(value) }, /** The viewer returning through the shared host's Back action. */ back: () => { returnFromPage?.() }, } @@ -330,3 +333,39 @@ it('returns from purpose to credit without dropping the selected purpose', async await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh.onboardingBack })) }) expect(h.update).toHaveBeenCalledWith({ step: 'credit' }) }) + + +it('reports visible pages once, funded Continue, and popup close', async () => { + const b = mount('credit', 'positive', 'ready', zh, true) + expect(b.track).toHaveBeenCalledExactlyOnceWith('onboarding_page_view', { page_name: 'onboarding_recharge' }) + await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh.onboardingSkip })) }) + expect(b.track).toHaveBeenCalledWith('onboarding_popup_view', { popup_name: 'skip_charge' }) + b.track.mockClear() + await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh.close })) }) + expect(b.track).toHaveBeenCalledExactlyOnceWith('onboarding_popup_click', { popup_name: 'skip_charge', button_name: 'close' }) + await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh.onboardingContinue })) }) + expect(b.track).toHaveBeenCalledWith('onboarding_page_click', { page_name: 'onboarding_recharge', button_name: 'continue' }) + expect(b.track).toHaveBeenCalledWith('onboarding_page_view', { page_name: 'onboarding_use_case' }) +}) + +it('does not report the loading surface as a page', () => { + expect(mount('welcome', 'loading', 'loading').track).not.toHaveBeenCalled() +}) + + +it('does not repeat page or popup exposure during save and refresh', () => { + const b = mount('credit') + fireEvent.click(screen.getByRole('button', { name: zh.onboardingSkip })) + act(() => { b.changeStatus('saving') }) + act(() => { b.changeStatus('loading') }) + act(() => { b.changeStatus('ready') }) + expect(b.track.mock.calls.filter(([name]) => name === 'onboarding_page_view')).toHaveLength(1) +}) + +it('reports closing the skip-settings popup', () => { + const b = mount('purpose') + fireEvent.click(screen.getByRole('button', { name: zh.onboardingSkip })) + b.track.mockClear() + fireEvent.click(screen.getByRole('button', { name: zh.close })) + expect(b.track).toHaveBeenCalledExactlyOnceWith('onboarding_popup_click', { popup_name: 'skip_setting', button_name: 'close' }) +}) diff --git a/packages/client/ui-settings-account/tests/sign-in-dialog.client.spec.tsx b/packages/client/ui-settings-account/tests/sign-in-dialog.client.spec.tsx index 0cf569c39a..c03b3613d8 100644 --- a/packages/client/ui-settings-account/tests/sign-in-dialog.client.spec.tsx +++ b/packages/client/ui-settings-account/tests/sign-in-dialog.client.spec.tsx @@ -178,3 +178,16 @@ it('keeps an outstanding start open until the request settles', async () => { await act(async () => { pending.resolve(undefined); await pending.promise }) expect(screen.getByRole('button', { name: en.signIn }).hasAttribute('disabled')).toBe(false) }) + +// Workspace login remains outside native welcome analytics even if a caller forwards a sender. +it('does not report workspace login views or login choices', async () => { + const track = vi.fn() + const props = { ...dialogProps(null), track } + const view = render() + view.rerender() + await act(async () => { fireEvent.click(screen.getByRole('button', { name: en.signIn })) }) + expect(props.start).toHaveBeenCalledOnce() + await act(async () => { fireEvent.click(screen.getByRole('button', { name: en.addApiKey })) }) + expect(props.useApiKey).toHaveBeenCalledOnce() + expect(track).not.toHaveBeenCalled() +}) diff --git a/packages/client/ui-settings-account/tsconfig.json b/packages/client/ui-settings-account/tsconfig.json index a2c29cb37a..ac170f07db 100644 --- a/packages/client/ui-settings-account/tsconfig.json +++ b/packages/client/ui-settings-account/tsconfig.json @@ -55,6 +55,9 @@ }, { "path": "../../settings/settings" + }, + { + "path": "../product-analytics/tsconfig.client.json" } ] } diff --git a/packages/client/ui-settings-general/README.i18n.yaml b/packages/client/ui-settings-general/README.i18n.yaml index 1b6dd64dde..42484f8a4a 100644 --- a/packages/client/ui-settings-general/README.i18n.yaml +++ b/packages/client/ui-settings-general/README.i18n.yaml @@ -15,8 +15,8 @@ en: aeb9c4bfdb19bc56 zh: 45a29bea90cff239 /deepseek-ai-dsh-client-ui-settings-general/use-this-package: - en: da896a9cf06fe5a5 - zh: 27545af457695988 + en: 473e1f0843f7a896 + zh: acfbc21efc458bbf /deepseek-ai-dsh-client-ui-settings-general/use-this-package/the-general-section: en: 8b8a7c6287bb303b zh: 19535112531aedd5 diff --git a/packages/client/ui-settings-general/README.md b/packages/client/ui-settings-general/README.md index 95b38c7103..29a1a7d544 100644 --- a/packages/client/ui-settings-general/README.md +++ b/packages/client/ui-settings-general/README.md @@ -31,7 +31,7 @@ Users reach the shell through the sidebar's bottom Settings control; feature plu When the section navigation exceeds the panel's available height, the list scrolls independently of the settings content and keeps the Settings title fixed. -In Desktop, the account-row update control shows availability, progress, verification, readiness, and persistent retry feedback. It shares the connection indicator’s 28px height, 8px corners, 14px icon slot, 4px icon gap, and 12px medium text with an 18px line height; update-state border, fill, and text colors remain independently defined. Retry text and its dot use the same brand blue as other update labels; numeric download progress has no ellipsis. The preload carries semantic phase, version, progress, and classified failures; the component resolves every visible and accessible string from the active `settings` locale, including after an in-application language change. Selecting an available update starts downloading; installation requires a separate shell-owned confirmation. A collapsed sidebar shows the same status as a brand-blue dot on its top expand button, including failures. Connection feedback takes priority except during shell-reported installation, when the expected backend disconnect must not hide update status. Failure restores connection feedback. Both controls share one carrier subscription; browser code cannot choose packages or authorize installation. [Desktop updates](../../../apps/desktop/README.md) owns the release workflow. +In Desktop, the account-row update control shows availability, progress, verification, readiness, and persistent retry feedback. It shares the connection indicator’s 28px height, 8px corners, 14px icon slot, 4px icon gap, and 12px medium text with an 18px line height; update-state border, fill, and text colors remain independently defined. Retry text and its dot use the same brand blue as other update labels; numeric download progress has no ellipsis. The preload carries semantic phase, version, progress, and classified failures; the component resolves every visible and accessible string from the active `settings` locale, including after an in-application language change. Selecting an available update starts downloading; installation requires a separate shell-owned confirmation. A collapsed sidebar shows the same status as a brand-blue dot on its top expand button, including failures. Connection feedback takes priority except during shell-reported installation, when the expected backend disconnect must not hide update status. Failure restores connection feedback. Both controls share one carrier subscription; browser code cannot choose packages or authorize installation. [Desktop updates](../../../apps/desktop/README.md) owns the release workflow. Checking, verifying, and preparing-to-restart tooltips show only the supplied version; without a version, they retain the state label. Desktop update tooltips preserve the complete version and prerelease suffix without adding v or V; their error summaries match the shell update dialogs. Settings visibility and section selection live in the shell owner store. The shell supplies the effective Settings binding to the contributed launcher for menu keycaps and `aria-keyshortcuts`; the fallback button uses the same binding for hover and keyboard-focus hints and `aria-keyshortcuts`. The Settings command (`Mod+,` by default) toggles the dialog when Settings is in front or no modal is open; the sidebar control opens the same dialog. The command cannot open or close Settings while the shortcut reference or another modal is in front. Held-key repeats do nothing. Initial focus lands on the selected section in the navigation, or on the title when no sections are available, without drawing a focus outline. Tab and directional navigation retain their visible focus indicators. `Mod+/` can open the shortcut reference above Settings; `Escape` closes the top dialog and restores focus to its invoking control. Return focus omits outlines after shortcut, Escape, or pointer dismissal. diff --git a/packages/client/ui-settings-general/README.zh.md b/packages/client/ui-settings-general/README.zh.md index 6874f1e5f8..f43966253f 100644 --- a/packages/client/ui-settings-general/README.zh.md +++ b/packages/client/ui-settings-general/README.zh.md @@ -31,7 +31,7 @@ kind: "package-reference" 当分区导航超出面板可用高度时，列表独立于设置内容滚动，并保持「设置」标题固定。 -在 Desktop 中，账户行更新控件显示可用版本、进度、验证、就绪和持久重试反馈。它与连接指示器共用 28px 高度、8px 圆角、14px 图标占位、4px 图文间距，以及 12px 中等字重文字和 18px 行高；更新状态的边框、填充和文字颜色独立定义。重试文字及其圆点与其他更新文案使用相同的品牌蓝色；数字下载进度不带省略号。预加载仅传递语义化阶段、版本、进度和失败类别；组件从当前 `settings` locale 解析全部可见与无障碍文案，并在应用内语言变化后同步更新。选择可用更新即开始下载；安装需要独立的壳拥有的确认。侧栏收起时，其顶部展开按钮以品牌蓝色圆点显示相同状态，包括失败状态。连接反馈通常优先展示，但壳报告正在安装时，预期的后端断开不能遮盖更新状态；失败后恢复连接反馈。两个控件共用一次载体订阅；浏览器代码不能选择安装包或授权安装。[Desktop 更新](../../../apps/desktop/README.zh.md)负责发布流程。 +在 Desktop 中，账户行更新控件显示可用版本、进度、验证、就绪和持久重试反馈。它与连接指示器共用 28px 高度、8px 圆角、14px 图标占位、4px 图文间距，以及 12px 中等字重文字和 18px 行高；更新状态的边框、填充和文字颜色独立定义。重试文字及其圆点与其他更新文案使用相同的品牌蓝色；数字下载进度不带省略号。预加载仅传递语义化阶段、版本、进度和失败类别；组件从当前 `settings` locale 解析全部可见与无障碍文案，并在应用内语言变化后同步更新。选择可用更新即开始下载；安装需要独立的壳拥有的确认。侧栏收起时，其顶部展开按钮以品牌蓝色圆点显示相同状态，包括失败状态。连接反馈通常优先展示，但壳报告正在安装时，预期的后端断开不能遮盖更新状态；失败后恢复连接反馈。两个控件共用一次载体订阅；浏览器代码不能选择安装包或授权安装。[Desktop 更新](../../../apps/desktop/README.zh.md)负责发布流程。检查中、校验中和准备重启状态的悬浮提示只显示已提供的版本号；没有版本号时保留状态文案。桌面更新提示完整保留版本号及预发布后缀，不额外添加 v 或 V；错误提示与桌面升级弹窗保持一致。 设置的可见状态和分区选择由 shell owner store 保存。外壳将设置命令的有效绑定传给入口贡献，用于菜单键帽和 `aria-keyshortcuts`；回退按钮使用相同绑定提供悬停、键盘聚焦提示和 `aria-keyshortcuts`。设置位于最前方或没有模态弹窗时，设置命令（默认为 `Mod+,`）切换设置弹窗的开关；侧栏控件打开同一弹窗。快捷键速查或其他模态弹窗位于前方时，该命令不能打开或关闭设置。长按产生的重复按键不执行操作。初始焦点落在导航中选中的分区；没有可用分区时落在标题上，均不绘制焦点外轮廓线。Tab 和方向键导航保留可见焦点提示。`Mod+/` 可在设置上方打开快捷键速查；`Escape` 关闭最上层弹窗，焦点返回触发该弹窗的控件。通过快捷键、Esc 或鼠标关闭后的回焦均不绘制外轮廓线。 diff --git a/packages/client/ui-settings-general/src/client/DesktopUpdateIndicator.tsx b/packages/client/ui-settings-general/src/client/DesktopUpdateIndicator.tsx index 15c671155b..588b3befdb 100644 --- a/packages/client/ui-settings-general/src/client/DesktopUpdateIndicator.tsx +++ b/packages/client/ui-settings-general/src/client/DesktopUpdateIndicator.tsx @@ -23,6 +23,9 @@ function updateCopy(state: DesktopUpdatePresentation, t: SettingsTranslate): { l error: t('desktop.update.retry'), } const label = labels[state.phase] + if (state.phase === 'checking' || state.phase === 'verifying' || state.phase === 'installing') { + return { label, detail: state.version ?? label } + } if (state.phase === 'error') { const failures: Readonly> = { check: t('desktop.update.checkFailed'), diff --git a/packages/client/ui-settings-general/src/client/locales.ts b/packages/client/ui-settings-general/src/client/locales.ts index e5a3bd1855..777af69935 100644 --- a/packages/client/ui-settings-general/src/client/locales.ts +++ b/packages/client/ui-settings-general/src/client/locales.ts @@ -11,16 +11,16 @@ export const zh = { 'desktop.update.installing': '正在准备重启…', 'desktop.update.ready': '安装并重启', 'desktop.update.retry': '重试更新', - 'desktop.update.versionDetail': '{label} — V{version}', - 'desktop.update.downloadDetail': '正在下载更新：{percent}%\n目标版本：V{version}', + 'desktop.update.versionDetail': '{label}：{version}', + 'desktop.update.downloadDetail': '正在下载更新：{percent}%\n目标版本：{version}', 'desktop.update.checkFailed': '检查更新失败，请稍后重试。', 'desktop.update.downloadFailed': '下载更新失败，请重试。', 'desktop.update.installFailed': '安装更新失败，请稍后重试。', - 'desktop.update.checkNetworkFailed': '检查更新失败，请稍后重试。网络连接异常，请检查网络后重试。', - 'desktop.update.downloadNetworkFailed': '下载更新失败，请重试。网络连接异常，请检查网络后重试。', - 'desktop.update.installNetworkFailed': '安装更新失败，请稍后重试。网络连接异常，请检查网络后重试。', - 'desktop.update.stopFailed': '未能安全停止任务，更新未安装。请稍后重试。', - 'desktop.update.tasksChanged': '有新任务开始，请重新确认更新。', + 'desktop.update.checkNetworkFailed': '检查更新失败，请检查网络连接后重试。', + 'desktop.update.downloadNetworkFailed': '下载更新失败，请检查网络连接后重试。', + 'desktop.update.installNetworkFailed': '安装更新失败，请检查网络连接后重试。', + 'desktop.update.stopFailed': '未能安全停止任务，更新尚未安装，请稍后重试。', + 'desktop.update.tasksChanged': '有新任务开始运行，请重新确认是否停止任务并更新。', 'desktop.update.tasksUnavailable': '无法确认任务状态，请在工作区就绪后重试更新。', 'title': '设置', 'close': '关闭', @@ -52,16 +52,16 @@ export const en = { 'desktop.update.installing': 'Preparing to restart…', 'desktop.update.ready': 'Install and Restart', 'desktop.update.retry': 'Retry update', - 'desktop.update.versionDetail': '{label} — V{version}', - 'desktop.update.downloadDetail': 'Downloading update: {percent}%\nTarget version: V{version}', + 'desktop.update.versionDetail': '{label}: {version}', + 'desktop.update.downloadDetail': 'Downloading update: {percent}%\nTarget version: {version}', 'desktop.update.checkFailed': 'Could not check for updates. Please try again later.', 'desktop.update.downloadFailed': 'Could not download the update. Please try again.', 'desktop.update.installFailed': 'Could not install the update. Please try again later.', - 'desktop.update.checkNetworkFailed': 'Could not check for updates. Please try again later. The connection was interrupted. Check your network and try again.', - 'desktop.update.downloadNetworkFailed': 'Could not download the update. Please try again. The connection was interrupted. Check your network and try again.', - 'desktop.update.installNetworkFailed': 'Could not install the update. Please try again later. The connection was interrupted. Check your network and try again.', - 'desktop.update.stopFailed': 'Tasks could not be stopped safely. The update was not installed. Please try again later.', - 'desktop.update.tasksChanged': 'New tasks started. Review the update confirmation again.', + 'desktop.update.checkNetworkFailed': 'Could not check for updates. Check your connection and try again.', + 'desktop.update.downloadNetworkFailed': 'Could not download the update. Check your connection and try again.', + 'desktop.update.installNetworkFailed': 'Could not install the update. Check your connection and try again.', + 'desktop.update.stopFailed': 'Could not safely stop the tasks. The update has not been installed. Please try again later.', + 'desktop.update.tasksChanged': 'New tasks have started. Confirm again to stop the tasks and update.', 'desktop.update.tasksUnavailable': 'Task status is unavailable. Try updating again when the workspace is ready.', 'title': 'Settings', 'close': 'Close', diff --git a/packages/client/ui-settings-general/tests/desktop-update.client.spec.tsx b/packages/client/ui-settings-general/tests/desktop-update.client.spec.tsx index 7e81c3f649..505a02d969 100644 --- a/packages/client/ui-settings-general/tests/desktop-update.client.spec.tsx +++ b/packages/client/ui-settings-general/tests/desktop-update.client.spec.tsx @@ -152,3 +152,28 @@ it('shows fallback progress and error details when the shell omits optional fiel expect((await screen.findByRole('tooltip')).textContent).toBe('安装更新失败，请稍后重试。') } finally { f.view.unmount(); f.status.resolve({ phase: 'idle' }) } }) + +it.each(['checking', 'verifying', 'installing'] as const)('shows only the version during %s in both locales', async (phase) => { + const f = fixture() + try { + await f.emit({ phase, version: '0.1.7-alpha.2' }) + fireEvent.focus(screen.getByRole('button')) + expect((await screen.findByRole('tooltip')).textContent).toBe('0.1.7-alpha.2') + f.view.rerender() + fireEvent.focus(screen.getByRole('button')) + expect((await screen.findByRole('tooltip')).textContent).toBe('0.1.7-alpha.2') + } finally { f.view.unmount(); f.status.resolve({ phase: 'idle' }) } +}) + +it.each([ + ['checking', '正在检查更新…'], + ['verifying', '正在校验更新文件…'], + ['installing', '正在准备重启…'], +] as const)('retains the state label when %s has no version', async (phase, label) => { + const f = fixture() + try { + await f.emit({ phase }) + fireEvent.focus(screen.getByRole('button', { name: label })) + expect((await screen.findByRole('tooltip')).textContent).toBe(label) + } finally { f.view.unmount(); f.status.resolve({ phase: 'idle' }) } +}) diff --git a/packages/client/ui-settings-models/README.i18n.yaml b/packages/client/ui-settings-models/README.i18n.yaml index 3e3c096cab..dbd67087e4 100644 --- a/packages/client/ui-settings-models/README.i18n.yaml +++ b/packages/client/ui-settings-models/README.i18n.yaml @@ -6,8 +6,8 @@ en: d1bc4d9ef67bfb19 zh: d095e4dc76f1c5e0 /deepseek-ai-dsh-client-ui-settings-models: - en: 65e1e8a17a23e576 - zh: 01de4e98a002d376 + en: 0db6fa836e1ff511 + zh: 0e2968763e1fb7a5 /deepseek-ai-dsh-client-ui-settings-models/summary: en: 53301a5d29936f69 zh: 9ac408a33571dbdd diff --git a/packages/client/ui-settings-models/README.md b/packages/client/ui-settings-models/README.md index ead2111e2b..c974239fed 100644 --- a/packages/client/ui-settings-models/README.md +++ b/packages/client/ui-settings-models/README.md @@ -7,6 +7,8 @@ kind: "package-reference" English | [中文](README.zh.md) +Desktop product events use the optional [product analytics service](../product-analytics/README.md); ordinary Web interactions are excluded. + ## Summary `dsh-client-ui-settings-models` is the Models settings page of the dsh web client: users configure API keys (stored write-only under the profile's credential reference), edit each provider's model list, and hand-declare custom pi-ai routes, with provider rows and one editor card at a time. The page joins the provider directory, the settings document, and the credential descriptions into one shared snapshot, so a row's state stays consistent across all three. It also walks first-run users through two ordered dialogs — a versioned internal-testing notice and the conditional official-DeepSeek credential step. diff --git a/packages/client/ui-settings-models/README.zh.md b/packages/client/ui-settings-models/README.zh.md index 8f8e0720fb..3ac2bb0480 100644 --- a/packages/client/ui-settings-models/README.zh.md +++ b/packages/client/ui-settings-models/README.zh.md @@ -7,6 +7,8 @@ kind: "package-reference" [English](README.md) | 中文 +桌面端产品事件使用可选的[产品埋点服务](../product-analytics/README.zh.md)，不包含普通 Web 交互。 + ## 概述 `dsh-client-ui-settings-models` 是 dsh Web 客户端的 Models 设置页面：用户可以配置 API 密钥（以只写方式存入 profile 的凭据引用之下）、编辑每个提供商的模型列表，并手工声明自定义 pi-ai 路由；页面以提供商行展示，一次只展开一张编辑卡片。该页面把提供商目录、设置文档与凭据描述合并为一个共享快照，因此行的状态在三个方面始终一致。它还会带首次运行的用户走两个有序弹窗——版本化内测声明，以及按条件显示的官方 DeepSeek 凭据步骤。 diff --git a/packages/client/ui-settings-models/package.json b/packages/client/ui-settings-models/package.json index 3d39cc682d..169aac59b9 100644 --- a/packages/client/ui-settings-models/package.json +++ b/packages/client/ui-settings-models/package.json @@ -57,7 +57,8 @@ "react": "^18.2.0", "@deepseek-ai/dsh-client-ui-renderer": "workspace:*", "@deepseek-ai/dsh-util-values": "workspace:*", - "@deepseek-ai/dsh-remote-mock": "workspace:*" + "@deepseek-ai/dsh-remote-mock": "workspace:*", + "@deepseek-ai/dsh-client-product-analytics": "workspace:*" }, "dependencies": { "@deepseek-ai/schemastery": "workspace:~" diff --git a/packages/client/ui-settings-models/src/client/DeepSeekOnboardingDialog.tsx b/packages/client/ui-settings-models/src/client/DeepSeekOnboardingDialog.tsx index fdc32c4045..63c090b3d5 100644 --- a/packages/client/ui-settings-models/src/client/DeepSeekOnboardingDialog.tsx +++ b/packages/client/ui-settings-models/src/client/DeepSeekOnboardingDialog.tsx @@ -5,7 +5,7 @@ * official DeepSeek route. The step reuses that page's credential editor in * the onboarding plugin's shared modal, so the key is entered once. */ - +import type { TrackProductEvent } from '@deepseek-ai/dsh-client-product-analytics/client' import { useEffect, useState } from 'react' import type { ReactNode } from 'react' import type { SnapshotStore } from '@deepseek-ai/dsh-client-store' @@ -22,6 +22,8 @@ import styles from './DeepSeekOnboardingDialog.module.css' /** Registration-side dependencies of {@link DeepSeekOnboardingDialog}. */ export interface DeepSeekOnboardingInjected { + /** Desktop-only event collection. */ + track?: TrackProductEvent /** Whether first-run setup should show automatically. Explicit requests remain available. */ automatic: boolean hooks: { @@ -120,6 +122,7 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps): readOnly={false} hideTitle credentialOnly + onSubmitCredential={() => { props.track?.('api_key_save_click', {}) }} credentialRequired autoFocusCredential cancelLabelKey="onboardingLater" diff --git a/packages/client/ui-settings-models/src/client/ProviderEditor.tsx b/packages/client/ui-settings-models/src/client/ProviderEditor.tsx index 41dac376d1..cd6656fdd5 100644 --- a/packages/client/ui-settings-models/src/client/ProviderEditor.tsx +++ b/packages/client/ui-settings-models/src/client/ProviderEditor.tsx @@ -87,6 +87,8 @@ export interface ProviderEditorProps { submitBusyLabelKey?: keyof typeof en /** Close the editor; `changed` reports whether an Apply committed. */ onClose: (changed: boolean) => void + /** Called on a credential form submission before the save starts. */ + onSubmitCredential?: () => void /** * Called once per change with whether the apply or the model list's * endpoint interrogation is in flight, so the owner can hold its surface @@ -530,7 +532,7 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode { submitBusyLabelKey={props.submitBusyLabelKey ?? 'applying'} {...props.cancelLabelKey === undefined ? {} : { cancelLabelKey: props.cancelLabelKey }} onCancel={() => { props.onClose(false) }} - onSubmit={() => { void apply() }} + onSubmit={() => { props.onSubmitCredential?.(); void apply() }} /> ) diff --git a/packages/client/ui-settings-models/src/client/index.ts b/packages/client/ui-settings-models/src/client/index.ts index a96665b11f..c80634a2b6 100644 --- a/packages/client/ui-settings-models/src/client/index.ts +++ b/packages/client/ui-settings-models/src/client/index.ts @@ -6,6 +6,7 @@ * Export discipline: * packages/client/AGENTS.md. */ +import type {} from '@deepseek-ai/dsh-client-product-analytics/client' import type { Context as ClientContext } from '@deepseek-ai/cordis' // Type-only: pulls the shell's SlotMap merge (the 'settings.section' entry). import type {} from '@deepseek-ai/dsh-client-ui-settings/client' @@ -98,6 +99,7 @@ export function apply(ctx: ClientContext): void { }) const deepSeekOnboardingInjected = (): DeepSeekOnboardingInjected => ({ automatic: credentialOnboarding, + track: (name, attributes) => ctx.get('productAnalytics')?.track(name, attributes), controller, hooks: { models: controller.store }, operations, diff --git a/packages/client/ui-settings-models/tests/apply.client.spec.ts b/packages/client/ui-settings-models/tests/apply.client.spec.ts index 62196478f7..2372690ba2 100644 --- a/packages/client/ui-settings-models/tests/apply.client.spec.ts +++ b/packages/client/ui-settings-models/tests/apply.client.spec.ts @@ -141,6 +141,12 @@ describe('ui-settings-models apply', () => { }) const deepSeek = onboarding.find(entry => entry.options.id === 'deepseek-official')! expect(deepSeek.component).toBe(DeepSeekOnboardingDialog) + const analytics = (deepSeek.inject!() as object) as import('../src/client/DeepSeekOnboardingDialog.tsx').DeepSeekOnboardingInjected + analytics.track?.('api_key_save_click', {}) + const track = vi.fn() + before.ctx.provide('productAnalytics', { track } as never) + analytics.track?.('api_key_save_click', {}) + expect(track).toHaveBeenCalledWith('api_key_save_click', {}) expect(deepSeek.options).toMatchObject({ id: 'deepseek-official', order: 0 }) const deepSeekInjected = ( deepSeek.inject as unknown as () => import('../src/client/DeepSeekOnboardingDialog.tsx').DeepSeekOnboardingInjected diff --git a/packages/client/ui-settings-models/tsconfig.json b/packages/client/ui-settings-models/tsconfig.json index 13bf556904..121f44cdde 100644 --- a/packages/client/ui-settings-models/tsconfig.json +++ b/packages/client/ui-settings-models/tsconfig.json @@ -8,8 +8,12 @@ "src" ], "references": [ - { "path": "../../host/webserver" }, - { "path": "../../../vendor/schemastery" }, + { + "path": "../../host/webserver" + }, + { + "path": "../../../vendor/schemastery" + }, { "path": "../../../vendor/cordis" }, @@ -33,6 +37,9 @@ }, { "path": "../../api/remotes/tsconfig.client.json" + }, + { + "path": "../product-analytics/tsconfig.client.json" } ] } diff --git a/packages/client/ui-settings-plugin-inventory/README.i18n.yaml b/packages/client/ui-settings-plugin-inventory/README.i18n.yaml index 6b7ff6a2bf..b30b1c29f8 100644 --- a/packages/client/ui-settings-plugin-inventory/README.i18n.yaml +++ b/packages/client/ui-settings-plugin-inventory/README.i18n.yaml @@ -9,8 +9,8 @@ en: 463eecf002ec0f54 zh: b8dc6003ddccd14a /deepseek-ai-dsh-client-ui-settings-plugin-inventory/summary: - en: 56f5349b6e502525 - zh: 691a0fe90b739e9d + en: f52353cf99816eb8 + zh: e172c1751289882f /deepseek-ai-dsh-client-ui-settings-plugin-inventory/table-of-contents: en: d152484eb41ac6b4 zh: 09388d293f9be9cb @@ -18,14 +18,14 @@ en: 67637808e7940157 zh: d4d0716ea4d33e4a /deepseek-ai-dsh-client-ui-settings-plugin-inventory/use-this-package/reading-a-card: - en: e615aaa891b5055f - zh: 38769e763c8e54ca + en: 141d6a73e99fee51 + zh: 2aa28b174867c967 /deepseek-ai-dsh-client-ui-settings-plugin-inventory/use-this-package/the-preset-switcher: en: 84e5938329199a22 zh: 6f5cfaac56433e8b /deepseek-ai-dsh-client-ui-settings-plugin-inventory/use-this-package/retrying-a-failed-read: - en: 2859449aaae5ab59 - zh: 06380059ae429026 + en: 673c7574e14078be + zh: b093e897f0341973 /deepseek-ai-dsh-client-ui-settings-plugin-inventory/understand-the-implementation: en: cab883d26642c932 zh: 54e7321bd781b400 @@ -33,8 +33,8 @@ en: e4792880c5916ce0 zh: 4c8171a446dd153f /deepseek-ai-dsh-client-ui-settings-plugin-inventory/understand-the-implementation/rendering: - en: b9aa850e5f101b68 - zh: 8a29025f19f6ce37 + en: 779146e3d3732803 + zh: 0dfafa328dfeda75 /deepseek-ai-dsh-client-ui-settings-plugin-inventory/further-exploration: en: ae3819f0c5da95bd zh: 40972ab96d5c95e2 diff --git a/packages/client/ui-settings-plugin-inventory/README.md b/packages/client/ui-settings-plugin-inventory/README.md index 7353f14d11..f6aa2312b8 100644 --- a/packages/client/ui-settings-plugin-inventory/README.md +++ b/packages/client/ui-settings-plugin-inventory/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -The **Plugin list** tab lets Web users inspect plugins without changing their configuration. It lists agent presets, then the global inventory; both start collapsed and open on demand or during a search. Cards show localized titles and descriptions when available, identify instances by stable entry id, and expose enablement, source details, runtime status, disabled conditions, and discovery failures; preset-provided global entries name their presets. Search covers both groups and points to matches in other presets. The tab handles loading, empty, no-match, failure, and retry states without exposing transport details, and still shows the global inventory without a preset roster. +The **Plugin list** tab lets Web users inspect plugins without changing their configuration. It lists agent presets, open by default, then the collapsed global inventory; a search opens both. Cards show localized titles and descriptions when available, identify instances by stable entry id, and expose enablement, source details, runtime status, disabled conditions, and discovery failures; preset-provided global entries name their presets. Search covers both groups and points to matches in other presets. The tab handles loading, empty, no-match, failure, and retry states without exposing transport details, and still shows the global inventory without a preset roster. ## Table of Contents @@ -31,9 +31,9 @@ A failed installation with pending pnpm build permissions offers **Allow these s ### Reading a card -Each collapsed card uses the plugin's localized title and description when available. Settings shortens literal package-name or module-name fallbacks by removing the npm scope and the `cordis:`, `cordis-plugin-`, or `dsh-`/`dsh-host-`/`dsh-client-` prefix; locale titles remain unchanged. The Host supplies locale and package-field fallbacks in `meta`; the Client selects the current language. Full module specifiers remain available in details and search. Missing descriptions are omitted, and metadata diagnostics appear with the card. This compact naming applies only to Settings, not the sidebar's Plugins page. +Each collapsed card uses the plugin's localized title and description when available; a description shows at most two lines until its card is expanded. Settings shortens literal package-name or module-name fallbacks by removing the npm scope and the `cordis:`, `cordis-plugin-`, or `dsh-`/`dsh-host-`/`dsh-client-` prefix; locale titles remain unchanged. The Host supplies locale and package-field fallbacks in `meta`; the Client selects the current language. Full module specifiers remain available in details and search. Missing descriptions are omitted, and metadata diagnostics appear with the card. This compact naming applies only to Settings, not the sidebar's Plugins page. -The stable entry id appears underneath the title, alongside a small enablement tag; a colored root-fiber status dot marks only the phases the tag cannot state: `pending` maps to idle, while `loading` and `unloading` map to ongoing. An `active` or `failed` fiber shows its tag without a dot. A composition-generated subtitle omits its leading `include:` marker, while hover, search, the accessible name, and expanded details retain the complete id. Long entry ids truncate in the row and remain available on hover. Expanding one card reveals the declared entry id, the full module specifier, and the state facts: a preset row names the preset it comes from, its runtime status when the composition is live, and its disable condition when it carries one; a preset-provided global row explains that agent presets provide it per session, names the presets that enable it, and offers a jump into the preset group. Preset names resolve through the shared `presetDisplayText` fold (`dsh-agent-preset-registry/display`) over [`ui-agent-preset`](../ui-agent-preset/README.md)'s dictionaries: shipped presets follow the active locale while user-authored ones keep their own metadata, so an English surface never echoes the preset declarations' Chinese names. Search filters both groups by localized title and description, module name, and entry id. +A small enablement tag marks only the states that differ from plainly enabled: disabled, conditional, provided by presets, and failed; a plainly enabled row carries no tag. A colored root-fiber status dot marks the live phases no tag states: `pending` maps to idle, while `loading` and `unloading` map to ongoing; an `active` or `failed` fiber shows no dot. The stable entry id appears in a code chip at the card's bottom-left, in line with the title, only when it differs from the title: a composition-generated id drops its leading `include:` marker there, and an id that then repeats the title is omitted. Whenever the chip shows, its hover text and the card's accessible name carry the complete id; search and expanded details always retain it. Long entry ids truncate in the chip and remain available on hover. Expanding one card reveals its full description, the declared entry id, the full module specifier, and the state facts: a preset row names the preset it comes from, its runtime status when the composition is live, and its disable condition when it carries one; a preset-provided global row explains that agent presets provide it per session, names the presets that enable it, and offers a jump into the preset group. Preset names resolve through the shared `presetDisplayText` fold (`dsh-agent-preset-registry/display`) over [`ui-agent-preset`](../ui-agent-preset/README.md)'s dictionaries: shipped presets follow the active locale while user-authored ones keep their own metadata, so an English surface never echoes the preset declarations' Chinese names. Search filters both groups by localized title and description, module name, and entry id. ### The preset switcher @@ -41,7 +41,7 @@ The switcher is the same selector-pill-plus-menu control the General settings ro ### Retrying a failed read -A failed read renders the shared error marker inside the tab; loading and current-page synchronization use the shared ongoing loader. Retrying re-runs the lazy `list()` call without exposing transport details. +A failed read renders the shared error marker inside the tab. Loading shows skeleton cards in the card grid, and current-page synchronization uses the shared ongoing loader. Retrying re-runs the lazy `list()` call without exposing transport details. The Plugin list also shows synchronization failures on the current page. Its retry reapplies the latest client graph without changing Host enablement or refreshing the page. @@ -61,7 +61,7 @@ The browser plugin registers one localized `settings.plugins.tab` contribution w ### Rendering -Row keys are scope-qualified (`global:`, `preset::`), so one module appearing in both scopes keeps distinct disclosure state; a declared entry id appears in expanded details and supplies the collapsed subtitle after removal of a leading composition `include:` marker, while a row without one stays unlabeled. The preset-provided marking is derived client-side: a global entry carries it when it is disabled there while at least one preset row for the same module specifier is actually enabled, so a module every preset gates off (or declares only conditionally) stays plainly disabled rather than over-claiming provision. +Row keys are scope-qualified (`global:`, `preset::`), so one module appearing in both scopes keeps distinct disclosure state; a declared entry id appears in expanded details and, after removal of a leading composition `include:` marker, supplies the collapsed id chip when the result differs from the title, while a row without one stays unlabeled. The preset-provided marking is derived client-side: a global entry carries it when it is disabled there while at least one preset row for the same module specifier is actually enabled, so a module every preset gates off (or declares only conditionally) stays plainly disabled rather than over-claiming provision. diff --git a/packages/client/ui-settings-plugin-inventory/README.zh.md b/packages/client/ui-settings-plugin-inventory/README.zh.md index 9078f8074a..cb0c2ce723 100644 --- a/packages/client/ui-settings-plugin-inventory/README.zh.md +++ b/packages/client/ui-settings-plugin-inventory/README.zh.md @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -**插件列表**标签页让 Web 用户查看插件，而不改变其配置。它先列 agent（智能体）预设分组，再列全局清单；两个分组默认都收起，按需展开，搜索期间保持展开。卡片显示可用的本地化标题与描述，以稳定的条目 id 标识实例，并展示启停状态、出处、运行状态、禁用条件与发现失败；由预设提供的全局条目会列出对应预设。搜索覆盖两个分组，并指出其他预设中的匹配。标签页处理加载、空结果、无匹配、失败与重试状态，且不暴露传输细节；没有预设 roster 时仍会展示全局清单。 +**插件列表**标签页让 Web 用户查看插件，而不改变其配置。它先列 agent（智能体）预设分组，再列全局清单；预设分组默认展开，全局分组默认收起，搜索期间两组都展开。卡片显示可用的本地化标题与描述，以稳定的条目 id 标识实例，并展示启停状态、出处、运行状态、禁用条件与发现失败；由预设提供的全局条目会列出对应预设。搜索覆盖两个分组，并指出其他预设中的匹配。标签页处理加载、空结果、无匹配、失败与重试状态，且不暴露传输细节；没有预设 roster 时仍会展示全局清单。 ## 目录 @@ -31,9 +31,9 @@ kind: "package-reference" ### 阅读卡片 -每张收起的卡片使用插件可用的本地化标题与描述。设置页会缩短字面的包名或模块名回退值，移除 npm scope 以及 `cordis:`、`cordis-plugin-` 或 `dsh-`/`dsh-host-`/`dsh-client-` 前缀；locale 标题保持原样。Host 在 `meta` 中提供 locale 与包字段的回退结果，Client 选择当前语言。详情与搜索仍保留完整模块标识。缺失的描述不显示，元信息诊断随卡片展示。这种短名显示仅用于设置页，不影响侧栏的插件页。 +每张收起的卡片使用插件可用的本地化标题与描述；描述最多显示两行，展开卡片后显示全文。设置页会缩短字面的包名或模块名回退值，移除 npm scope 以及 `cordis:`、`cordis-plugin-` 或 `dsh-`/`dsh-host-`/`dsh-client-` 前缀；locale 标题保持原样。Host 在 `meta` 中提供 locale 与包字段的回退结果，Client 选择当前语言。详情与搜索仍保留完整模块标识。缺失的描述不显示，元信息诊断随卡片展示。这种短名显示仅用于设置页，不影响侧栏的插件页。 -稳定的条目 id 显示在标题下方，卡片带有表示启停状态的小标签；彩色根 fiber 状态圆点只标记标签无法表达的阶段：`pending` 映射为 idle，`loading` 与 `unloading` 映射为 ongoing。`active` 或 `failed` fiber 只显示标签，不显示圆点。组合生成的次标题省略开头的 `include:` 标记；悬停、搜索、无障碍名称与展开详情仍保留完整 id。长条目 id 会在行内截断，悬停时仍可查看完整值。展开卡片后会显示声明的条目 id、完整模块标识与状态事实：预设行说明它来自哪个预设、组合存活时的运行状态，以及它携带的禁用条件；被预设提供的全局行说明它由 Agent 预设按会话提供、列出启用它的预设，并提供跳转到预设组的入口。预设名经共享的 `presetDisplayText` 纯函数（`dsh-agent-preset-registry/display`）叠在 [`ui-agent-preset`](../ui-agent-preset/README.zh.md) 的字典上解析：内置预设走当前语言，用户自建预设保留自己的元数据，因此英文界面不会回显预设声明里的中文名。搜索按本地化标题与描述、模块名称及条目 id 过滤两组。 +表示启停状态的小标签只标记与普通启用不同的状态：已停用、条件启用、由预设提供与启动失败；普通启用的行不带标签。彩色根 fiber 状态圆点标记没有标签表达的存活阶段：`pending` 映射为 idle，`loading` 与 `unloading` 映射为 ongoing；`active` 或 `failed` fiber 不显示圆点。稳定的条目 id 仅在与标题不同时显示，位于卡片左下角的代码标签中，与标题左对齐：组合生成的 id 在此省略开头的 `include:` 标记，省略后与标题相同的 id 不再重复显示。显示代码标签时，其悬停提示与卡片的无障碍名称带完整 id；搜索与展开详情始终保留完整 id。长条目 id 会在代码标签内截断，悬停时仍可查看完整值。展开卡片后会显示完整描述、声明的条目 id、完整模块标识与状态事实：预设行说明它来自哪个预设、组合存活时的运行状态，以及它携带的禁用条件；被预设提供的全局行说明它由 Agent 预设按会话提供、列出启用它的预设，并提供跳转到预设组的入口。预设名经共享的 `presetDisplayText` 纯函数（`dsh-agent-preset-registry/display`）叠在 [`ui-agent-preset`](../ui-agent-preset/README.zh.md) 的字典上解析：内置预设走当前语言，用户自建预设保留自己的元数据，因此英文界面不会回显预设声明里的中文名。搜索按本地化标题与描述、模块名称及条目 id 过滤两组。 ### 预设切换器 @@ -41,7 +41,7 @@ kind: "package-reference" ### 重试失败的读取 -读取失败会在标签页内渲染共享 error 标记；加载与当前页面同步使用共享 ongoing loading。重试会重新执行懒 `list()` 调用，且不会暴露传输细节。 +读取失败会在标签页内渲染共享 error 标记。加载时在卡片网格中显示骨架卡片，当前页面同步使用共享 ongoing loading。重试会重新执行懒 `list()` 调用，且不会暴露传输细节。 插件列表还显示当前页面的同步失败。重试会重新应用最新客户端图，不改变 Host 启用状态，也不刷新页面。 @@ -61,7 +61,7 @@ kind: "package-reference" ### 渲染 -行 key 按作用域限定（`global:`、`preset::`），因此同一模块出现在两个作用域时保持各自的展开状态；声明的条目 id 出现在展开详情中，并在去掉开头的组合 `include:` 标记后作为收起次标题，没有 id 的行不显示次级标签。预设提供标记在客户端推导：一个全局条目在全局被停用、且至少一个预设行对同一模块标识实际启用时才携带它，因此被所有预设关掉（或仅条件声明）的模块保持单纯的已停用，而不是夸大提供关系。 +行 key 按作用域限定（`global:`、`preset::`），因此同一模块出现在两个作用域时保持各自的展开状态；声明的条目 id 出现在展开详情中；去掉开头的组合 `include:` 标记后若与标题不同，则作为收起卡片的 id 代码标签，没有 id 的行不显示次级标签。预设提供标记在客户端推导：一个全局条目在全局被停用、且至少一个预设行对同一模块标识实际启用时才携带它，因此被所有预设关掉（或仅条件声明）的模块保持单纯的已停用，而不是夸大提供关系。 diff --git a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css index 87b29d442f..be3aa42773 100644 --- a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css +++ b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css @@ -1,4 +1,6 @@ +/* The tab's own width, not the window's, decides the card columns below. */ .section { + container: plugin-inventory / inline-size; display: flex; flex-direction: column; gap: 14px; @@ -7,7 +9,6 @@ color: var(--dsw-alias-label-primary); } -.catalogHeading h3, .status, .failure p { margin: 0; @@ -85,37 +86,21 @@ box-shadow: 0 0 0 2px color-mix(in srgb, var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary)) 18%, transparent); } -.catalogHeading { - display: flex; - align-items: baseline; - gap: 7px; - padding: 0 2px; -} - -.catalogHeading h3 { - font-size: 13px; - line-height: 20px; - font-weight: 600; -} - -.catalogHeading span { - font-size: 12px; - line-height: 18px; - color: var(--dsw-alias-label-tertiary); - font-variant-numeric: tabular-nums; -} - .cards { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); - align-items: start; gap: 10px; margin: 0; padding: 0; list-style: none; } +/* Cards stretch to their grid row's height. The button fills a stretched card: + the title row and description stay at the top, in line with the other card's, + and the spare height sits above the entry id chip or at the bottom. */ .card { + display: flex; + flex-direction: column; min-width: 0; overflow: hidden; border: 0.5px solid var(--dsw-alias-settings-card-stroke); @@ -127,11 +112,22 @@ border-color: var(--dsw-alias-border-l3); } +/* The other card in an expanded card's row keeps its own height instead of + stretching alongside the details. The selectors assume the two columns + `.cards` declares, where each row starts at an odd position, and must change + with that count; in one column the matched card sits alone in its row. */ +.card:nth-child(odd)[data-open='true'] + .card, +.card:nth-child(odd):has(+ .card[data-open='true']) { + align-self: start; +} + .cardContent { box-sizing: border-box; display: flex; + flex: 1 1 auto; flex-direction: column; align-items: stretch; + gap: 2px; width: 100%; min-height: 52px; border: 0; @@ -173,11 +169,35 @@ min-width: 0; font-size: 14px; line-height: 20px; - font-weight: 600; + font-weight: 500; } -/* The Loader entry id keeps one size in the card subtitle and the row it expands into; - the collapsed subtitle stays on the quieter label tier, while the expanded row carries +/* Two lines at most while collapsed; the expanded card shows the full text. */ +.cardDescription { + display: -webkit-box; + overflow: hidden; + color: var(--dsw-alias-label-tertiary); + font-size: 12px; + line-height: 18px; + text-wrap: pretty; + -webkit-box-orient: vertical; + -webkit-line-clamp: 2; +} + +.card[data-open='true'] .cardDescription { + display: block; +} + +/* The entry id is metadata, not prose: a code chip in the card's bottom-left + corner whose left edge lines up with the title. */ +.cardMeta { + display: flex; + margin-top: auto; + padding-top: 6px; +} + +/* The Loader entry id keeps one size in the card chip and the row it expands into; + the collapsed chip stays on the quieter label tier, while the expanded row carries the card's primary value. */ .cardIdentity, .entryValue { @@ -188,15 +208,19 @@ .cardIdentity { display: block; - width: 100%; - color: var(--dsw-alias-label-tertiary); + box-sizing: border-box; + max-width: 100%; + border-radius: var(--dsw-radius-xs); + padding: 1px 6px; + background: var(--dsw-alias-bg-module-platform); + color: var(--dsw-alias-label-secondary); } .cardTrailing { display: inline-flex; flex: none; align-items: center; - gap: 7px; + gap: 8px; color: var(--dsw-alias-label-tertiary); } @@ -213,11 +237,13 @@ gap: 10px; } +/* Every group header takes the preset switcher's 36px height, so each subtitle + sits the same distance below its title. */ .groupTitleRow { display: flex; align-items: center; gap: 8px; - min-height: 32px; + min-height: 36px; } .group + .group { @@ -266,7 +292,7 @@ .groupSub { display: flex; flex-wrap: wrap; - gap: 4px 8px; + row-gap: 4px; margin: -6px 0 0 20px; color: var(--dsw-alias-label-tertiary); font-size: 12px; @@ -274,6 +300,13 @@ font-variant-numeric: tabular-nums; } +/* A middle dot with equal space on both sides separates the subtitle's parts. */ +.groupSub > * + *::before { + content: '·'; + padding: 0 6px; + color: var(--dsw-alias-label-tertiary); +} + .failedCount { color: var(--dsw-alias-state-error-primary); } @@ -330,7 +363,7 @@ padding: 8px 10px; background: color-mix(in srgb, var(--dsw-alias-state-error-primary) 8%, transparent); color: var(--dsw-alias-state-error-primary); - font-size: 12.5px; + font-size: 12px; line-height: 18px; overflow-wrap: anywhere; white-space: pre-line; @@ -343,7 +376,7 @@ gap: 4px 8px; margin: 0; color: var(--dsw-alias-label-tertiary); - font-size: 12.5px; + font-size: 12px; line-height: 18px; } @@ -353,10 +386,34 @@ background: transparent; color: var(--dsw-alias-state-business-primary); font: inherit; - font-size: 12.5px; + font-size: 12px; cursor: pointer; } +/* Loading placeholder in the cards grid, sized like a card with one description + line; its bars pulse through the shared skeleton token as the input-trigger + menu's pending rows do. */ +.skeletonCard { + display: flex; + flex-direction: column; + gap: 8px; + border: 0.5px solid var(--dsw-alias-settings-card-stroke); + border-radius: var(--dsw-radius-xl); + padding: 15px 14px; + background: var(--dsw-alias-settings-card-fill); +} + +.skeletonBar { + width: 40%; + height: 14px; + border-radius: var(--dsw-radius-xs); + background: var(--dsw-alias-bg-skeleton); +} + +.skeletonBar + .skeletonBar { + width: 80%; + height: 12px; +} .enabledIn { display: flex; @@ -430,9 +487,19 @@ .chevron { transition: transform 140ms var(--ds-ease-in-out); } + + .skeletonBar { + animation: plugin-inventory-skeleton 2s cubic-bezier(0.36, 0, 0.64, 1) infinite; + } } -@media (max-width: 680px) { +@keyframes plugin-inventory-skeleton { + 0% { opacity: 1; } + 40% { opacity: 0.6; } + 80%, 100% { opacity: 1; } +} + +@container plugin-inventory (max-width: 520px) { .cards { grid-template-columns: minmax(0, 1fr); } diff --git a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx index c5064e5441..57810b993a 100644 --- a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx +++ b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx @@ -58,6 +58,9 @@ const PHASE_KEYS = { unloading: 'unloading', } satisfies Record, PluginInventoryLocaleKey> +/** Placeholder cards the loading skeleton lays out in the cards grid. */ +const SKELETON_CARDS = [0, 1, 2, 3] as const + /** Localized accessible label for one root Fiber phase. */ function phaseLabel(phase: PluginFiberPhase, t: Translate): string { return phase === null ? t('unobserved') : t(PHASE_KEYS[phase]) @@ -77,6 +80,16 @@ function entrySubtitle(entryId: string): string { return entryId.replace(/^include:/, '') } +/** Whether a card shows its entry id: the id exists and, without its `include:` marker, differs from the title. */ +function idAddsToTitle(entryId: string | null, title: string): entryId is string { + return entryId !== null && entrySubtitle(entryId) !== title +} + +/** Accessible card name: the title, the complete entry id when the card shows one, then the enablement state. */ +function cardLabel(title: string, entryId: string | null, state: string): string { + return idAddsToTitle(entryId, title) ? `${title}, ${entryId}, ${state}` : `${title}, ${state}` +} + /** Preserve translated titles and shorten literal package or module name fallbacks in Settings. */ function pluginText(row: PluginInventoryEntry | AgentPresetRow, resolveText: PluginInventorySettingsTabInjected['resolveText']) { const title = row.meta?.title @@ -151,8 +164,12 @@ function PluginCard({