diff --git a/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.i18n.yaml new file mode 100644 index 0000000000..9d8ccb1790 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.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-07-22-collapsed-sidebar-control-rail.md: e959eef37a9e9c0fea79b82ff970daddd9257609 +2026-07-22-collapsed-sidebar-control-rail.zh.md: 7f6d6529a8aa4a655a1d3292e7f41bfb822f05a3 diff --git a/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.md b/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.md new file mode 100644 index 0000000000..e959eef37a --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.md @@ -0,0 +1,29 @@ +# Agent Note: A collapsed sidebar retains its control rail + +Status: implemented + +English | [中文](2026-07-22-collapsed-sidebar-control-rail.zh.md) + +## Problem + +The sidebar close action persisted a zero width preference, and the layout mapped that preference to a zero-width grid track. The only sidebar toggle and the settings entry both lived inside that clipped track, so closing the sidebar removed every visible recovery control. Reloading preserved the closed preference and reproduced the lockout. + +## Decision + +The layout maps a closed sidebar (persisted width `0`) to the fixed `SIDEBAR_COLLAPSED` width of 56px: a 24px icon column between the sidebar's 16px horizontal paddings. The compact rail participates in the concession solver and retains its right border, while the stored expanded width remains untouched. + +`AppFrame` marks the sidebar collapsed from the persisted width preference rather than from the resolved track width, removes the resize handle while collapsed, and passes `collapsed` to the sidebar slot as owner props from the render site. Collapse and expand animate: the frame transitions `grid-template-columns` (and the remaining handle its `left`) on the deepsuite sider curve — `--ds-ease-in-out` over `--ds-transition-duration-slow`, both supplied by ui-theme's base sheet; transitions pause during drags and under `prefers-reduced-motion`. + +`SidebarRoot` reads the owner `collapsed` prop and morphs in place rather than swapping renders: the four control rows persist into the rail — expand toggle, new session, new workspace, search, in the same top-down order as their expanded rows — animating their geometry (heights, paddings, margins, capsule borders) on the same curve, each aligned with its expanded counterpart's behavior (the search icon expands the sidebar and focuses the search box). Wide-only content (brand, labels, input, session tree) cross-fades out over 200ms, stays mounted while the collapse animates, and unmounts once the 300ms settle passes — dropping the sessions subscription and leaving the rendered and accessibility trees. The search query lives with the root and survives the round trip. + +## Alternatives considered + +- **Render an expand button over the center column** — rejected because it recovers only the toggle, not the persistent settings area, and splits sidebar chrome across two package owners. +- **Keep a zero-width grid track and let the rail overflow it** — rejected because the rail would overlap the center column and leave hit testing and responsive geometry disconnected from the grid. +- **Keep the complete sidebar tree mounted and hide it with clipping** — rejected because hidden controls remain in the semantic tree and continue subscribing and rendering even though only two controls belong in the collapsed state. + +## Consequences + +- A collapsed sidebar reserves 56px instead of yielding the entire width to the center column. Expanding restores the persisted width and drag behavior. +- The settings entry remains visible but retains its existing placeholder behavior; this change does not introduce an account or settings screen. +- Layout solver tests pin the compact width, sidebar component tests pin the visible controls, and the keyless real-bundle web smoke test pins collapse and recovery through the assembled client. diff --git a/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.zh.md b/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.zh.md new file mode 100644 index 0000000000..7f6d6529a8 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-22-collapsed-sidebar-control-rail.zh.md @@ -0,0 +1,29 @@ +# Agent Note: 侧边栏折叠后保留控制栏 + +Status: implemented + +[English](2026-07-22-collapsed-sidebar-control-rail.md) | 中文 + +## 问题 + +侧边栏关闭操作会持久化宽度偏好 `0`，布局再将该偏好映射为宽度为零的网格轨道。侧边栏唯一的开关与设置入口都位于这个被裁切的轨道内，因此关闭侧边栏会移除所有可见的恢复控件。页面重新加载时仍会读取关闭偏好，从而再次陷入无法恢复的状态。 + +## 决策 + +布局将关闭的侧边栏（持久化宽度为 `0`）映射为固定的 `SIDEBAR_COLLAPSED` 宽度 56px：在侧边栏两侧各 16px 的水平内边距之间放置一列 24px 的图标控件。紧凑控制栏参与空间收缩求解，并保留右侧边框；已存储的展开宽度保持不变。 + +`AppFrame` 根据持久化的宽度偏好标记侧边栏是否折叠，而不是根据求解后的轨道宽度来判断；折叠时移除尺寸调整手柄，并在渲染点把 `collapsed` 作为 owner props 传给侧边栏插槽。折叠与展开带动画：frame 对 `grid-template-columns`（以及余下手柄的 `left`）应用 deepsuite 侧栏曲线过渡——`--ds-ease-in-out` 配 `--ds-transition-duration-slow`，两个变量由 ui-theme 的 base 表提供；拖拽期间和 `prefers-reduced-motion` 下过渡暂停。 + +`SidebarRoot` 读取 owner 的 `collapsed` 属性，原地 morph 而非切换渲染：四个控件行持续存在并演变为控制栏——展开开关、新建会话、新建工作区、搜索，自上而下与展开态各行顺序一致——几何（行高、内边距、外边距、胶囊边框）走同一条曲线动画，行为与展开态对应控件对齐（搜索图标会展开侧边栏并聚焦搜索框）。宽态专属内容（品牌标识、文字标签、输入框、会话树）以 200ms 交叉淡出，折叠动画期间保持挂载，300ms settle 后卸载——随之退订会话列表并离开渲染树与可访问性树。搜索关键词由根组件持有，折叠往返后保留。 + +## 曾考虑的替代方案 + +- **在中心列上方渲染展开按钮**：不予采纳，因为这只能恢复开关，无法保留常驻设置区域，同时还会让侧边栏 UI 由两个包（package）分别持有。 +- **保留宽度为零的网格轨道，让控制栏溢出显示**：不予采纳，因为控制栏会与中心列重叠，还会使命中测试和响应式几何关系脱离网格布局。 +- **保持完整侧边栏树挂载，并通过裁切将其隐藏**：不予采纳，因为隐藏控件仍留在语义树中，而且会继续订阅和渲染，尽管折叠状态下只需要两个控件。 + +## 后果 + +- 折叠的侧边栏占用 56px，而不是把全部宽度让给中心列。展开时恢复持久化宽度与拖动行为。 +- 设置入口持续可见，但保留既有占位行为；本次改动不提供账户或设置页面。 +- 布局求解器测试固定紧凑宽度，侧边栏组件测试固定可见控件，基于真实构建产物的无密钥 Web 冒烟测试则通过组装后的客户端固定折叠与恢复行为。 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 9922018569..aa0516648b 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 @@ -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 -2026-07-21-serial-cross-platform-ci-reference.md: ffc1fd5b37bc6c9e3427ee55a55300f93a1292f3 -2026-07-21-serial-cross-platform-ci-reference.zh.md: d7f87916865b83973abe6b0708203618cf536c8e +2026-07-21-serial-cross-platform-ci-reference.md: b795a0aff62c20967d2c85429c0c6115c1b9585d +2026-07-21-serial-cross-platform-ci-reference.zh.md: 223fd9cf20a1d8228cb0c6b1b2f3f95644becae6 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 ffc1fd5b37..b795a0aff6 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 @@ -6,7 +6,7 @@ English | [中文](2026-07-21-serial-cross-platform-ci-reference.zh.md) ## Problem -The pull-request workflow reaches its latency targets by scheduling the complete primary Node inventory concurrently inside one larger runner. The optimized scheduler still should not be its own only completeness oracle: a defect in its gate inventory or dependency graph could omit work while the optimized job stays green. +The pull-request workflow consolidates required checks into dedicated Linux and Windows jobs. Those jobs still should not be the only completeness oracle: a defect in their gate inventory or dependency graph could omit work while the required aggregate stays green. Encoding the one-minute non-Windows target and three-minute Windows target as job timeouts creates a separate failure mode. Hosted-runner startup and performance vary, so a correct gate can be cancelled at the target boundary before it emits useful diagnostics. The performance objective needs measurement against GitHub timestamps, while correctness needs enough time to finish. @@ -14,21 +14,21 @@ Reviewers also need a direct answer to a simpler question: what happens when the ## Decision -[CI](../../../../.github/workflows/ci.yml) gives pull-request and master-push events complementary responsibilities. Pull requests run only the optimized larger-runner and compatibility jobs. A push to `master` skips those jobs and runs three explicit references named `serial / linux`, `serial / macos`, and `serial / windows`. They intentionally duplicate their short checkout, runtime setup, and immutable install sequences instead of hiding the operating systems behind a matrix or reusable workflow. `workflow_dispatch` is reserved for runner benchmarks. +[CI](../../../../.github/workflows/ci.yml) gives pull-request and master-push events complementary responsibilities. Pull requests run consolidated Linux and Windows jobs plus the Node compatibility and Python contracts on standard GitHub-hosted capacity. A push to `master` skips those jobs and runs three explicit references named `serial / linux`, `serial / macos`, and `serial / windows`. They intentionally duplicate their short checkout, runtime setup, and immutable install sequences instead of hiding the operating systems behind a matrix or reusable workflow. `workflow_dispatch` is reserved for runner benchmarks. Each reference job runs `pnpm run check:ci` without any shard selector. `DSH_GATE_CONCURRENCY=1` makes the top-level aggregate execute one ready gate at a time; coverage, snapshot replay, built-bin smoke, and publication validation also receive worker counts of one. The three operating-system jobs may run beside one another, but each host's repository gates are serial and complete. Linux installs bubblewrap before replaying snapshots, and Windows enables Developer Mode before installing the symlinked workspace. -Master reference jobs are diagnostic and do not participate in the pull request's required `all checks passed` result. A pull request runs only the optimized jobs; a master push runs only the three serial references. The one-minute non-Windows and three-minute Windows objectives are evaluated from completed hosted-job timestamps and reported as measurements; they are not `timeout-minutes` values. +Master reference jobs are diagnostic and do not participate in the pull request's required `all checks passed` result. A pull request runs only its required jobs; a master push runs only the three serial references. Performance is evaluated from completed hosted-job timestamps and reported as a measurement; it is not encoded as a `timeout-minutes` value. -The portable reference uses GitHub's standard `ubuntu-latest`, `macos-latest`, and `windows-2025` labels. A higher-core hosted runner remains a possible future benchmark, but it is not the default: larger runners require organization-owned labels and provisioning, while a reference oracle should remain runnable without repository-external runner configuration. Provisioning one later can change the performance experiment without changing this correctness baseline. +The portable reference uses GitHub's standard `ubuntu-latest`, `macos-latest`, and `windows-2025` labels. Required pull-request jobs use the same portable Linux and Windows capacity under the [required-CI decision](2026-07-23-portable-required-pull-request-ci.md). Higher-core hosted runners remain manual benchmarks because a correctness path must remain runnable without repository-external runner configuration. ## Alternatives considered - **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 deliberately trade wall time and runner consumption for simplicity and are not needed in the fast feedback loop. +- **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 Windows contracts. - **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 the reference is the portable fallback for the organization-specific pull-request topology. The fast pull-request path uses provisioned larger runners; the serial master path keeps standard labels. +- **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. ## Consequences 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 d7f8791686..223fd9cf20 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 @@ -6,7 +6,7 @@ Status: implemented ## 问题 -拉取请求工作流通过在一台更大型运行器内并发调度完整的主 Node 门禁清单来达到延迟目标。优化调度器仍不应成为自身唯一的完整性判定基准：如果其门禁清单或依赖图存在缺陷，即使优化作业保持绿灯，也可能漏掉部分工作。 +拉取请求工作流将必需检查合并到专用的 Linux 和 Windows 作业中。这些作业仍不应成为唯一的完整性判定基准：如果其门禁清单或依赖图存在缺陷，即使必需聚合结果保持绿灯，也可能漏掉部分工作。 将非 Windows 作业的 1 分钟目标和 Windows 作业的 3 分钟目标写成作业超时，会引入另一种失败模式。托管运行器的启动时间和性能会波动，因此即使门禁本身正确，也可能在到达目标时间边界时被取消，来不及输出有用的诊断信息。性能目标需要根据 GitHub 时间戳衡量，而正确性验证需要给门禁留足完成时间。 @@ -14,21 +14,21 @@ Status: implemented ## 决策 -[CI](../../../../.github/workflows/ci.yml) 为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求只运行使用更大型运行器的优化作业和兼容性作业。向 `master` 推送时会跳过这些作业，改为运行三个显式参考作业，名称分别为 `serial / linux`、`serial / macos` 和 `serial / windows`。这些作业有意分别重复简短的代码检出、运行时设置和依赖锁定的安装步骤，不用矩阵或可复用工作流把操作系统差异隐藏起来。`workflow_dispatch` 仅用于运行器基准测试。 +[CI](../../../../.github/workflows/ci.yml) 为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求在 GitHub 标准托管容量上运行合并后的 Linux 和 Windows 作业，以及 Node 兼容性与 Python 契约。向 `master` 推送时会跳过这些作业，改为运行三个显式参考作业，名称分别为 `serial / linux`、`serial / macos` 和 `serial / windows`。这些作业有意分别重复简短的代码检出、运行时设置和依赖锁定的安装步骤，不用矩阵或可复用工作流把操作系统差异隐藏起来。`workflow_dispatch` 仅用于运行器基准测试。 每个参考作业均在不设置任何分片选择器的情况下运行 `pnpm run check:ci`。`DSH_GATE_CONCURRENCY=1` 使顶层聚合每次只执行一个已经就绪的门禁；覆盖率、快照回放、built-bin 冒烟测试和发布验证的并发数也设为 1。三种操作系统的作业可以彼此并行，但每台主机上的仓库门禁都串行运行且完整执行。Linux 在回放快照前安装 bubblewrap，Windows 则在安装采用符号链接的工作区前启用开发人员模式。 -master 分支的参考作业仅用于诊断，不参与拉取请求所要求的 `all checks passed` 结果。拉取请求只运行优化作业；向 master 推送时只运行三个串行参考作业。系统根据已完成托管作业的时间戳评估非 Windows 作业的 1 分钟目标和 Windows 作业的 3 分钟目标，并将其报告为测量结果，而不是写成 `timeout-minutes` 值。 +master 分支的参考作业仅用于诊断，不参与拉取请求所要求的 `all checks passed` 结果。拉取请求只运行其必需作业；向 master 推送时只运行三个串行参考作业。系统根据已完成托管作业的时间戳评估性能，并将其报告为测量结果，而不是写成 `timeout-minutes` 值。 -可移植的参考流程使用 GitHub 标准的 `ubuntu-latest`、`macos-latest` 和 `windows-2025` 标签。仍可将更高核心数的托管运行器作为未来的基准测试，但不将其设为默认选择：更大型运行器需要组织自有的标签和预配，而参考判定基准应无需仓库外部的运行器配置即可运行。日后完成这类预配，可以改变性能实验而无需改变该正确性基线。 +可移植的参考流程使用 GitHub 标准的 `ubuntu-latest`、`macos-latest` 和 `windows-2025` 标签。依据[必需 CI 决策](2026-07-23-portable-required-pull-request-ci.md)，拉取请求必需作业使用相同的可移植 Linux 和 Windows 容量。更高核心数的托管运行器仍仅用于手动基准测试，因为正确性路径必须无需仓库外部的运行器配置即可运行。 ## 曾考虑的替代方案 - **将每个超时值设为相应延迟目标**：不予采纳，因为调度波动会中止原本正确的执行，并使诊断回归所需的证据无法产生。 - **仅信任并发执行的主门禁清单**：不予采纳，因为调度逻辑与校验逻辑共享实现假设；串行聚合流程是一项独立的完整性检查。 -- **在每个拉取请求上运行串行参考作业**：不予采纳，因为这些作业有意以更长的总耗时和更多运行器用量换取简单性，快速反馈循环不需要它们。 +- **在每个拉取请求上运行串行参考作业**：不予采纳，因为这些作业会重复完整的跨平台聚合流程，并为每项改动增加 macOS 工作；必需作业已经执行阻塞性的 Linux 和 Windows 契约。 - **使用一个操作系统矩阵**：不予采纳，因为三个具名作业无需另一套选择机制，就能让参考流程的构成清晰可见。 -- **在更大型运行器上运行串行参考流程**：不予采纳，因为该参考流程是特定组织拉取请求拓扑的可移植后备方案。快速拉取请求路径使用已预配的更大型运行器；串行 master 路径保留标准标签。 +- **在大型运行器上运行串行参考流程**：不予采纳，因为当组织自有运行器池无法分配作业时，必需 CI 及其独立参考流程都必须仍可运行。 ## 后果 diff --git a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml index 6277617a73..6dcafc39dd 100644 --- a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml +++ b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.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 -2026-07-22-evidence-based-larger-hosted-runners.md: c0fae2841f21c431d6416cd5d421929d70197abb -2026-07-22-evidence-based-larger-hosted-runners.zh.md: 51c73a8a631af4f1254c795d09585770fc4e68bb +2026-07-22-evidence-based-larger-hosted-runners.md: c292a4ea49320d684c35d2b9986549d693efb914 +2026-07-22-evidence-based-larger-hosted-runners.zh.md: 5e59c787a85bd2093f0c3ceaa8290e7cd42528fa diff --git a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md index c0fae2841f..c292a4ea49 100644 --- a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md +++ b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md @@ -14,11 +14,7 @@ Larger runners make it possible to pay setup once and parallelize inside the rep The organization keeps twelve x64 larger-runner pools in the repo-restricted `dsh-larger-ci` group: Ubuntu 24.04 and Windows 2025 at 4, 8, 16, 32, 64, and 96 cores. Public IPs are disabled. Each pool has an autoscaling ceiling of 256; the ceiling does not allocate idle machines or remove the need to bound workflow demand. -Production CI uses five larger-runner executions and one standard-runner aggregator. The primary Node inventory is not sharded: - -- `node 24 / complete` uses one 96-core Linux runner. One checkout, direct selection of the image's preinstalled Node 24 toolcache, pnpm- and ESLint-cache restore, and install feeds all 42 primary gates. `run-gates` starts up to 10 independent gates; ESLint and coverage use at most 16 workers, and snapshot replay uses at most 8. Build starts as soon as the first short gates release scheduler slots, while snapshot replay and publication consumers retain explicit dependencies on emitted `lib/` output. Pull requests restore both caches without saving them, so cache compression and upload do not extend the required job; the master serial reference refreshes those caches outside the pull-request critical path. An uncached exact-head trace put ESLint at 38.11 seconds and coverage at 37.10 seconds, so the small ESLint restore remains useful on the critical path. The read-only job does not persist checkout credentials. -- Node 22.19 and Node 26 use the 4- and 32-core Linux pools for their runtime compatibility smokes. Python 3.10 uses the 8-core Linux pool for the complete keyless SDK suite. These are environment contracts, not slices of the primary Node gate inventory. -- `windows node 24 / complete` uses one 32-core Windows runner. One preparation wave feeds the required package build, required production site build, and complete observational portability inventory. Required failures fail the job; observational failures are reported as non-blocking. ESLint stays single-threaded because 16 ESLint workers took 174.54 seconds, coverage uses at most 12 workers, and the outer scheduler retains 16 slots. The job restores only the small master-refreshed ESLint cache and performs a clean pnpm install instead of restoring or saving the many-file package store. All six Windows larger-runner sizes completed install and the production-site benchmark without mutating the machine-wide Developer Mode registry key, so the pull-request critical path omits that redundant step. +The pools are measurement infrastructure, not a dependency of ordinary pull requests. The [portable required-CI decision](2026-07-23-portable-required-pull-request-ci.md) runs branch-protection jobs on standard GitHub-hosted capacity; `suite=larger-runner-benchmark` compares isolated critical lanes across every provisioned size, and `suite=consolidated-runner-benchmark` compares whole aggregates. Each benchmark reports its observed processor and memory capacity before running repository work. The former gate-level and coarse primary shard jobs are absent from the workflow. Their static, lint, coverage, snapshot, and scenario shard selectors are also absent from the repository, so an unused diagnostic path cannot preserve a second CI architecture. @@ -38,15 +34,15 @@ The same benchmark measured the required Windows build surfaces across every pro Repository work gains little above 16 Windows cores, but the 32-core pool can start the complete outer inventory together. A [retargeted production validation](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29907581119/attempts/2) completed the full one-box Windows inventory in 173 seconds, including coverage and snapshot replay, so Windows remains consolidated. -The larger client package graph makes cache mechanics and scheduler pressure part of the measured workload. In [one exact-head production run](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29912577681), Linux spent 39 seconds in repository gates but 69 seconds in the complete job, while Windows spent 117 seconds in repository gates and 228 seconds in the complete job. The Windows pnpm cache downloaded its 154 MB archive in about two seconds but spent 27 seconds extracting it, followed by a 23-second install and a 14-second post-job save. A [cacheless all-size trace](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29913033155) completed the same 32-core Windows install in 27 seconds. Production therefore avoids the Windows package-store cache, uses restore-only caches on latency-critical pull-request jobs, and bounds outer concurrency so typecheck, lint, coverage, and build do not oversubscribe one host. +The larger client package graph makes cache mechanics and scheduler pressure part of the measured workload. In [one exact-head candidate run](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29912577681), Linux spent 39 seconds in repository gates but 69 seconds in the complete job, while Windows spent 117 seconds in repository gates and 228 seconds in the complete job. The Windows pnpm cache downloaded its 154 MB archive in about two seconds but spent 27 seconds extracting it, followed by a 23-second install and a 14-second post-job save. A [cacheless all-size trace](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29913033155) completed the same 32-core Windows install in 27 seconds. A future larger-runner rollout therefore needs complete-job measurements rather than gate-only timing. -Three host effects remain part of the decision. A standard Node 26 job once spent 36 of its 67 seconds in `Set up job`, which is why environment contracts use distinct larger-runner pools instead of standard capacity. The setup-node action later spent 3.68 seconds printing cached Linux environment details and 46.56 seconds doing the same on Windows after both had already found Node 24.18.0 in the hosted toolcache. The two latency-critical jobs select the newest preinstalled 24.x directory directly, verify its major, and fail loud if the image no longer carries it; compatibility jobs retain setup-node because selecting a non-default runtime is their contract. A Linux candidate also spent 18 seconds registering a 50 KB Bubblewrap package because the hosted image scanned 202,507 package-database files. [`scripts/prepare-ci-bubblewrap.sh`](../../../../scripts/prepare-ci-bubblewrap.sh) instead verifies and extracts the pinned payload into the ephemeral runner directory, runs a functional confinement probe, and overlaps that preparation with dependency installation. +Host setup remains part of any comparison. A standard Node 26 job once spent 36 of its 67 seconds in `Set up job`, while `actions/setup-node` spent 46.56 seconds printing cached Windows environment details after finding Node in the hosted toolcache. A Linux candidate also spent 18 seconds registering a 50 KB Bubblewrap package because the hosted image scanned 202,507 package-database files. [`scripts/prepare-ci-bubblewrap.sh`](../../../../scripts/prepare-ci-bubblewrap.sh) instead verifies and extracts the pinned payload into the ephemeral runner directory, runs a functional confinement probe, and overlaps that preparation with dependency installation. -Inner and outer worker limits are separate controls. An [exact-head 32-worker ESLint experiment](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29918329463) slowed lint to 52.28 seconds and coverage to 42.71 seconds, where an adapter idle-timeout test failed. A later 8-gate trace reduced coverage to 35.17 seconds but delayed the production-site build until the aggregate reached 41.06 seconds. Production therefore retains 16 ESLint workers and admits 10 independent repository gates at once, leaving capacity for the worker pools owned by those gates without starving later independent work. +Inner and outer worker limits are separate controls. An [exact-head 32-worker ESLint experiment](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29918329463) slowed lint to 52.28 seconds and coverage to 42.71 seconds, where an adapter idle-timeout test failed. A later 8-gate trace reduced coverage to 35.17 seconds but delayed the production-site build until the aggregate reached 41.06 seconds. Core count therefore does not justify copying an equally large worker limit. -Linux coverage caps each project at 16 workers, while Windows keeps the 12-worker cap. The process-bound project contains exactly five suite files, so its fork count cannot reach either cap. Thirty-two forks crashed Node 24's CJS lexer twice, and a later 16-fork run reproduced the worker loss and invalid coverage result. The single Vitest invocation therefore uses threads for the broad inventory and reserves forks for suites that exercise process-global state, `process` APIs, or timing-sensitive process I/O. That narrow fork inventory includes the local bash process-plumbing suite: under aggregate gate contention its thread worker completed every test but intermittently missed the stdin-error callback needed for per-file function coverage. It also includes the pi-ai adapter suite after two hosted aggregate runs delayed an idle-watchdog socket-close observation past its 100-millisecond test deadline. A 32-worker all-gate run on the 96-core host slowed coverage to 44.6 seconds and made a compute-budget regression cross its one-second threshold, so production stops at 16. This preserves the suites' isolation contracts and deterministic coverage while avoiding forked execution for ordinary test files. +The process-bound coverage project contains exactly five suite files. Thirty-two forks crashed Node 24's CJS lexer twice, and a later 16-fork run reproduced the worker loss and invalid coverage result. The single Vitest invocation therefore uses threads for the broad inventory and reserves forks for suites that exercise process-global state, `process` APIs, or timing-sensitive process I/O. That narrow fork inventory includes the local bash process-plumbing suite and the pi-ai adapter suite because aggregate contention changed timing observations in both. These failures make deterministic coverage, not advertised cores, the upper bound on worker selection. -The workflow retains two manual measurement suites. `suite=larger-runner-benchmark` compares isolated critical lanes across every size, and `suite=consolidated-runner-benchmark` compares whole aggregates. Complete serial Linux, macOS, and Windows references run only when `master` moves; pull requests run only the optimized jobs. +Complete serial Linux, macOS, and Windows references run only when `master` moves. Pull requests use the portable required path, while larger-runner suites run only by manual dispatch. ## Alternatives considered @@ -54,11 +50,11 @@ The workflow retains two manual measurement suites. `suite=larger-runner-benchma **Keep the former gate-level shard topology as a manual reference.** A dormant second topology kept hundreds of workflow lines, selector modules, and scenario-partition behavior alive. The all-size and serial suites provide timing and completeness controls without preserving production code that no required job exercises. -**Use the 64-core pool for the complete primary aggregate.** Its sampled active time was three seconds lower than the 96-core result because hosted setup was nine seconds faster, but its repository gates were 5.72 seconds slower. Production uses 96 cores for the shorter controllable critical path; the benchmark suite retains both pools so a sustained image or pricing change can reverse that choice with evidence. +**Use the 64-core pool for the complete primary aggregate.** Its sampled active time was three seconds lower than the 96-core result because hosted setup was nine seconds faster, but its repository gates were 5.72 seconds slower. The benchmark suite retains both pools because a sustained image or pricing change can reverse the comparison. **Keep build behind typecheck.** This orders independent compiler invocations and turns snapshot replay into a three-stage critical chain. Build output has its own success dependency, so only snapshot and publication consumers wait for it. -**Keep compatibility and Python on standard runners.** Warm standard runs can fit, but runner setup alone has crossed the non-Windows target. Distinct larger pools isolate these environment contracts from that allocation lottery. +**Make larger-runner pools the required default.** This offers lower measured latency when allocation works, but a missing entitlement or delayed organization transfer leaves required jobs queued without repository diagnostics. The portable path accepts longer runtime, and manual suites preserve the performance experiment. **Keep required and observational Windows checks in separate jobs.** The split preserves status semantics at the workflow level but pays setup twice. `run-gates` preserves the same required versus non-blocking distinction inside one process. @@ -66,10 +62,10 @@ The workflow retains two manual measurement suites. `suite=larger-runner-benchma ## Consequences -Primary Node CI has one job, one setup wave, one complete gate inventory, and no shard selectors. Together with two Node compatibility executions, Python, and Windows, production has five paid larger-runner executions instead of seven coarse-lane executions or 49 gate-level executions. +The benchmark topology pays one setup wave per measured aggregate and retains no shard selectors. It runs paid larger-runner executions only when manually dispatched instead of charging every pull request. -GitHub rounds each larger-runner execution up to a whole minute, so eliminating setup waves reduces billed time as well as workflow complexity. The final aggregator remains on a standard runner because it begins only after the paid jobs release capacity. +GitHub rounds each larger-runner execution up to a whole minute, so whole-aggregate measurement exposes both billed time and workflow complexity without making that cost part of branch protection. -The current targets are observed performance contracts, not cancellation deadlines. Exact-head production runs must show every non-Windows job below one minute and the consolidated Windows job below three minutes; manual all-size and serial suites remain available when image, dependency, scheduler, or pricing changes need remeasurement. +Performance targets are observations, not cancellation deadlines or correctness requirements. Manual all-size and serial suites remain available when image, dependency, scheduler, or pricing changes need remeasurement. -Production CI depends on the organization-owned runner labels in [`.github/workflows/ci.yml`](../../../../.github/workflows/ci.yml). Missing or renamed pools leave jobs queued instead of falling back to standard capacity. All twelve pools remain provisioned so the manual benchmarks can re-evaluate the production size without an administrative setup cycle. +Missing or renamed organization-owned labels leave only manual benchmark jobs queued. All twelve pools remain defined so the benchmark can compare sizes after allocation recovers, while required CI follows the standard-runner fallback. diff --git a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md index 51c73a8a63..5e59c787a8 100644 --- a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md +++ b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md @@ -14,11 +14,7 @@ Status: implemented 组织在仅限本仓库使用的 `dsh-larger-ci` 运行器组中保留 12 个 x64 大型运行器池：Ubuntu 24.04 和 Windows 2025 各设 4、8、16、32、64、96 核规格。公网 IP 已禁用。每个池的自动扩缩容上限为 256；该上限既不会分配闲置机器，也不能免除限制工作流需求的必要性。 -生产 CI 包含 5 次大型运行器执行和 1 个标准运行器聚合作业。主 Node 门禁清单不再分片： - -- `node 24 / complete` 使用一台 96 核 Linux 运行器。只需执行一次代码检出、直接选择托管映像中预装的 Node 24 toolcache、恢复 pnpm 和 ESLint 缓存以及安装，即可供全部 42 项主门禁使用。`run-gates` 最多同时启动 10 项相互独立的门禁；ESLint 和覆盖率最多使用 16 个工作线程，快照回放最多使用 8 个。第一批短门禁释放调度器槽位后，构建会立即启动，而快照回放和发布消费方仍显式依赖生成的 `lib/` 输出。拉取请求会恢复这两项缓存但不保存，因此缓存压缩和上传不会延长必需作业；master 上的串行参考会在拉取请求关键路径之外刷新这两项缓存。一次未使用缓存的分支头精确运行轨迹显示，ESLint 耗时 38.11 秒，覆盖率耗时 37.10 秒，因此在关键路径上恢复这个较小的 ESLint 缓存仍有价值。该只读作业不会持久化代码检出凭据。 -- Node 22.19 和 Node 26 分别使用 4 核和 32 核 Linux 池运行各自的运行时兼容性冒烟测试。Python 3.10 使用 8 核 Linux 池运行完整的无密钥 SDK 套件。这些作业属于环境契约，并非主 Node 门禁清单的分片。 -- `windows node 24 / complete` 使用一台 32 核 Windows 运行器。一轮准备工作供必需的包构建、必需的生产网站构建以及完整的观测性可移植性清单共用。任何必需项失败都会使作业失败；观测项失败则报告为非阻塞。ESLint 保持单线程，因为 16 个 ESLint 工作线程耗时 174.54 秒；覆盖率最多使用 12 个工作线程，外层调度器则保留 16 个槽位。该作业仅恢复由 master 刷新的较小 ESLint 缓存，并在干净环境中执行 pnpm 安装，而不恢复或保存包含大量文件的包存储。全部 6 种 Windows 大型运行器规格都在未修改系统级 Developer Mode 注册表项的情况下完成了安装和生产网站基准测试，因此拉取请求关键路径省略了这个多余步骤。 +这些运行器池是测量基础设施，不是普通拉取请求的依赖。依据[可移植必需 CI 决策](2026-07-23-portable-required-pull-request-ci.md)，分支保护作业在 GitHub 标准托管容量上运行；`suite=larger-runner-benchmark` 比较每种已预配规格上相互独立的关键通道，`suite=consolidated-runner-benchmark` 则比较完整聚合流程。每项基准测试都会先报告实测的处理器和内存容量，再运行仓库工作。 原有的门禁级和粗粒度主流程分片作业已从工作流中移除。相应的静态、lint、覆盖率、快照和场景分片选择器也已从仓库中移除，因此未使用的诊断路径无法继续维系第二套 CI 架构。 @@ -38,15 +34,15 @@ Status: implemented Windows 仓库工作在超过 16 核后收益很小，但 32 核池可以让完整的外层清单同时启动。一次[重新定向的生产验证](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29907581119/attempts/2)在 173 秒内完成了单机 Windows 完整清单，其中包括覆盖率和快照回放，因此 Windows 继续采用合并执行方式。 -客户端包依赖图增大后，缓存机制和调度器压力也成为实测工作负载的一部分。在[一次分支头精确的生产运行](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29912577681)中，Linux 的仓库门禁耗时 39 秒，完整作业耗时 69 秒；Windows 的仓库门禁耗时 117 秒，完整作业耗时 228 秒。Windows pnpm 缓存的 154 MB 归档下载耗时约 2 秒，但解压耗时 27 秒，随后安装耗时 23 秒，作业结束后的保存又耗时 14 秒。一次[无缓存的全规格运行轨迹](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29913033155)在 27 秒内完成了同一台 32 核 Windows 运行器上的安装。因此，生产环境不使用 Windows 包存储缓存，在对延迟敏感的拉取请求作业中使用只恢复不保存的缓存，并限制外层并发度，以免类型检查、lint、覆盖率和构建在同一台主机上过度争用资源。 +客户端包依赖图增大后，缓存机制和调度器压力也成为实测工作负载的一部分。在[一次分支头精确的候选运行](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29912577681)中，Linux 的仓库门禁耗时 39 秒，完整作业耗时 69 秒；Windows 的仓库门禁耗时 117 秒，完整作业耗时 228 秒。Windows pnpm 缓存的 154 MB 归档下载耗时约 2 秒，但解压耗时 27 秒，随后安装耗时 23 秒，作业结束后的保存又耗时 14 秒。一次[无缓存的全规格运行轨迹](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29913033155)在 27 秒内完成了同一台 32 核 Windows 运行器上的安装。因此，未来若要启用大型运行器，需要测量完整作业，而不能只测门禁耗时。 -3 项主机效应仍构成这项决策的依据。一个标准 Node 26 作业曾在总共 67 秒的耗时中，把 36 秒用在 `Set up job` 上，因此各项环境契约使用不同的大型运行器池，而非标准容量。setup-node action 在 Linux 和 Windows 均已从托管 toolcache 找到 Node 24.18.0 后，仍分别花费 3.68 秒和 46.56 秒输出缓存的环境详情。两个延迟关键作业会直接选择最新的预装 24.x 目录并验证其主版本号；如果映像不再提供该目录，作业会明确报错并失败。兼容性作业仍使用 setup-node，因为选择非默认运行时正是它们的契约。一个 Linux 候选作业还在注册 50 KB 的 Bubblewrap 包时耗时 18 秒，因为托管映像扫描了 202,507 个包数据库文件。[`scripts/prepare-ci-bubblewrap.sh`](../../../../scripts/prepare-ci-bubblewrap.sh) 改为验证固定包内容并将其解压到临时运行器目录，执行功能性隔离探针，并让这项准备工作与依赖安装重叠执行。 +任何比较都必须计入主机设置。一个标准 Node 26 作业曾在总共 67 秒的耗时中，把 36 秒用在 `Set up job` 上；`actions/setup-node` 从托管 toolcache 找到 Node 后，仍花费 46.56 秒输出缓存的 Windows 环境详情。一个 Linux 候选作业还在注册 50 KB 的 Bubblewrap 包时耗时 18 秒，因为托管映像扫描了 202,507 个包数据库文件。[`scripts/prepare-ci-bubblewrap.sh`](../../../../scripts/prepare-ci-bubblewrap.sh) 改为验证固定包内容并将其解压到临时运行器目录，执行功能性隔离探针，并让这项准备工作与依赖安装重叠执行。 -内层与外层工作线程上限是相互独立的控制机制。一次[分支头精确、使用 32 个工作线程的 ESLint 实验](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29918329463)使 lint 耗时增至 52.28 秒、覆盖率耗时增至 42.71 秒；同一次运行中，一项适配器空闲超时测试失败。后来一次同时运行 8 项门禁的运行轨迹将覆盖率耗时降至 35.17 秒，但生产网站构建被延后，直到聚合流程耗时达到 41.06 秒时才完成。因此，生产环境将 ESLint 工作线程上限维持在 16 个，并且同时最多运行 10 项相互独立的仓库门禁，既为这些门禁自身的工作线程池留出容量，又避免后续独立工作因资源不足而迟迟无法启动。 +内层与外层工作线程上限是相互独立的控制机制。一次[分支头精确、使用 32 个工作线程的 ESLint 实验](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29918329463)使 lint 耗时增至 52.28 秒、覆盖率耗时增至 42.71 秒；同一次运行中，一项适配器空闲超时测试失败。后来一次同时运行 8 项门禁的运行轨迹将覆盖率耗时降至 35.17 秒，但生产网站构建被延后，直到聚合流程耗时达到 41.06 秒时才完成。因此，不能仅凭核心数照搬同等规模的工作线程上限。 -Linux 覆盖率把每个项目的工作线程上限设为 16 个，Windows 则保留 12 个工作线程的上限。进程约束项目恰好包含 5 个套件文件，因此它的 fork 数量不可能达到任一上限。32 个 fork 曾两次导致 Node 24 的 CJS 词法分析器崩溃，后来一次使用 16 个 fork 的运行又复现了工作进程丢失和无效的覆盖率结果。因此，单次 Vitest 调用会对大范围测试清单使用线程，只为涉及进程全局状态、`process` API 或对时间敏感的进程 I/O 的套件保留 fork。这份有限的 fork 清单还包含本地 bash 进程通路套件：在聚合门禁争用资源时，该套件的工作线程虽然完成了所有测试，却会间歇性漏记逐文件函数覆盖率所需的 stdin 错误回调。两次托管聚合运行都将空闲看门狗对套接字关闭的观测延迟到超过其 100 毫秒测试截止时间，因此这份清单还包含 pi-ai 适配器套件。在 96 核主机上使用 32 个工作线程运行全部门禁时，覆盖率耗时变慢至 44.6 秒，还使一项计算预算回归超过其 1 秒阈值，因此生产环境将工作线程数限制在 16 个以内。这样既能保留这些套件的隔离契约和覆盖率结果的确定性，又能避免以 fork 方式执行普通测试文件。 +进程约束的覆盖率项目恰好包含 5 个套件文件。32 个 fork 曾两次导致 Node 24 的 CJS 词法分析器崩溃，后来一次使用 16 个 fork 的运行又复现了工作进程丢失和无效的覆盖率结果。因此，单次 Vitest 调用会对大范围测试清单使用线程，只为涉及进程全局状态、`process` API 或对时间敏感的进程 I/O 的套件保留 fork。这份有限的 fork 清单包括本地 bash 进程通路套件和 pi-ai 适配器套件，因为聚合争用改变了二者的时序观测结果。这些故障表明，选择工作线程数量时，上限取决于能否得到确定的覆盖率结果，而非标称核心数。 -工作流保留 2 项手动测量套件。`suite=larger-runner-benchmark` 比较所有规格下相互独立的关键通道，`suite=consolidated-runner-benchmark` 比较完整聚合流程。只有在 `master` 移动时，才运行完整的 Linux、macOS 和 Windows 串行参考；拉取请求只运行优化后的作业。 +只有在 `master` 移动时，才运行完整的 Linux、macOS 和 Windows 串行参考。拉取请求使用可移植的必需路径，大型运行器套件仅通过手动触发运行。 ## 曾考虑的替代方案 @@ -54,11 +50,11 @@ Linux 覆盖率把每个项目的工作线程上限设为 16 个，Windows 则 **将原有的门禁级分片拓扑保留为手动参考。** 一套闲置的第二拓扑会让数百行工作流、选择器模块和场景分区行为继续存活。全规格和串行套件无需保留任何必需作业都不执行的生产代码，也能提供计时与完整性对照。 -**使用 64 核池运行完整主聚合流程。** 由于托管设置快了 9 秒，其采样活动耗时比 96 核结果少 3 秒，但仓库门禁慢了 5.72 秒。生产环境使用 96 核来缩短可控的关键路径；基准测试套件保留两种规格，因此如果映像或定价发生持续性变化，仍可根据证据反转这项选择。 +**使用 64 核池运行完整主聚合流程。** 由于托管设置快了 9 秒，其采样活动耗时比 96 核结果少 3 秒，但仓库门禁慢了 5.72 秒。基准测试套件保留两种规格，因为映像或定价的持续变化可能反转比较结果。 **让构建继续等待类型检查。** 此方案会给相互独立的编译器调用排定先后顺序，并把快照回放变成 3 阶段关键链。构建输出本身有独立的成功依赖关系，因此只有快照和发布消费方需要等待它。 -**让兼容性和 Python 继续使用标准运行器。** 标准运行器热运行可以达到目标，但仅运行器设置一项就曾超过非 Windows 目标。不同的大型运行器池可以让这些环境契约免受这种分配波动影响。 +**将大型运行器池设为必需的默认选择。** 分配成功时，该方案能缩短实测延迟，但缺少使用资格或组织转移延迟都会使必需作业持续排队，且不会产生仓库诊断信息。可移植路径接受更长的运行时间，手动套件则保留性能实验。 **将必需的 Windows 检查和观测性 Windows 检查保留在不同作业中。** 这种拆分在工作流层保留状态语义，却需要支付两次设置开销。`run-gates` 在一个进程内保留了相同的必需与非阻塞区别。 @@ -66,10 +62,10 @@ Linux 覆盖率把每个项目的工作线程上限设为 16 个，Windows 则 ## 后果 -主 Node CI 只有 1 个作业、1 轮设置、1 份完整门禁清单，而且没有分片选择器。加上 2 次 Node 兼容性执行、Python 和 Windows，生产环境共有 5 次付费大型运行器执行，而非 7 次粗粒度通道执行或 49 次门禁级执行。 +基准测试拓扑对每个实测聚合流程只承担 1 轮设置开销，且不保留分片选择器。付费大型运行器仅在手动触发时执行，而不会向每个拉取请求收取这项费用。 -GitHub 会把每次大型运行器执行向上取整到整分钟计费，因此消除设置轮次既能减少计费时长，也能降低工作流复杂度。最终聚合作业仍使用标准运行器，因为它只会在付费作业释放容量后启动。 +GitHub 会把每次大型运行器执行向上取整到整分钟计费，因此完整聚合测量能同时呈现计费时长与工作流复杂度，而不会让这项成本进入分支保护路径。 -当前目标是基于观测得到的性能契约，而非取消截止时间。分支头精确的生产运行必须表明每个非 Windows 作业都低于 1 分钟，合并后的 Windows 作业低于 3 分钟；当映像、依赖、调度器或定价发生变化而需要重新测量时，仍可使用手动全规格和串行套件。 +性能目标是观测结果，而非取消截止时间或正确性要求。当映像、依赖、调度器或定价发生变化而需要重新测量时，仍可使用手动全规格和串行套件。 -生产 CI 依赖 [`.github/workflows/ci.yml`](../../../../.github/workflows/ci.yml) 中由组织持有的运行器标签。池缺失或改名会让作业一直排队，不会回退到标准容量。全部 12 个池均保持已预配状态，因此手动基准测试无需再次经过管理配置周期，就能重新评估生产规格。 +组织自有标签缺失或改名时，只有手动基准作业会排队。全部 12 个池均保持已定义状态，因此分配恢复后，基准测试仍可比较各规格，而必需 CI 则使用标准运行器后备路径。 diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml new file mode 100644 index 0000000000..463777eacf --- /dev/null +++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.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-07-23-portable-required-pull-request-ci.md: a430d43f7cb3dd4df987d35f3a49d130c397f8e3 +2026-07-23-portable-required-pull-request-ci.zh.md: cbd5d150056f77e52105f56c70a1ead74f052f59 diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md new file mode 100644 index 0000000000..a430d43f7c --- /dev/null +++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md @@ -0,0 +1,35 @@ +# Agent Note: Portable required pull-request CI + +Status: implemented + +English | [中文](2026-07-23-portable-required-pull-request-ci.zh.md) + +## Problem + +Required pull-request jobs assigned to organization-owned runner labels remain queued when GitHub cannot allocate those pools. The workflow is valid and standard GitHub-hosted jobs can still pass, but `all checks passed` never starts and an otherwise healthy pull request cannot satisfy branch protection. + +Billing health, a runner definition's `Ready` state, and a large autoscaling ceiling do not prove that a named pool can receive a job. Required correctness checks need a portable execution path that does not depend on repository-external runner provisioning. + +## Decision + +[CI](../../../../.github/workflows/ci.yml) runs every required pull-request job on GitHub's standard `ubuntu-latest` or `windows-2025` capacity. The primary Node and Windows jobs keep their complete consolidated inventories, while top-level gates, coverage, ESLint, publint, and snapshot replay use one worker on the smaller hosts. Node versions are selected through `actions/setup-node`, and the Windows job enables Developer Mode before installing the symlinked workspace. + +The `node 24 / complete`, Node compatibility, Python SDK, and `windows node 24 / complete` jobs remain dependencies of `all checks passed`; no gate is removed or made observational to recover availability. Branch protection continues to require `e2e` and `all checks passed`. + +The two manual larger-runner suites and all twelve organization-owned labels remain available for measurement. They do not participate in ordinary pull requests. The [larger-runner measurements](2026-07-22-evidence-based-larger-hosted-runners.md) remain evidence for future performance work, while the [serial cross-platform reference](2026-07-21-serial-cross-platform-ci-reference.md) remains the independent master-push completeness check. + +## Alternatives considered + +**Wait for organization-runner allocation to recover.** A queue with no assigned runner emits no repository diagnostic and can block every pull request indefinitely, so an external recovery is not a correctness path. + +**Use only the smallest organization-owned pools.** Every named pool crosses the same organization allocation boundary; reducing core count does not remove the dependency that caused the queue. + +**Skip or demote checks while capacity is unavailable.** This would make the status green by dropping evidence rather than by running the repository's required contracts. + +**Keep larger-host worker limits on standard runners.** Concurrent full-repository gates and their inner worker pools can oversubscribe the smaller memory and CPU allocation, turning an availability repair into contention failures. + +## Consequences + +Ordinary pull requests can acquire runners without organization-specific configuration, and a live exact-head run proves the same commands that branch protection consumes. The trade-off is longer elapsed time and more rounded standard-runner minutes than the measured larger-runner topology. + +Manual larger-runner benchmarks can remain queued without blocking pull requests. Restoring larger runners to the required path needs a separate evidence-based decision after exact-head jobs receive nonzero runner IDs and complete reliably; changing a definition's status alone is insufficient. diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md new file mode 100644 index 0000000000..cbd5d15005 --- /dev/null +++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md @@ -0,0 +1,35 @@ +# Agent Note: 可移植的拉取请求必需 CI + +Status: implemented + +[English](2026-07-23-portable-required-pull-request-ci.md) | 中文 + +## 问题 + +分配到组织自有运行器标签的拉取请求必需作业，在 GitHub 无法为这些池分配运行器时会持续排队。工作流本身有效，GitHub 标准托管作业仍能通过，但 `all checks passed` 始终无法启动，原本健康的拉取请求因此无法满足分支保护要求。 + +账单状态正常、运行器定义处于 `Ready` 状态以及较高的自动扩缩容上限，都不能证明指定的运行器池可以接收作业。必需的正确性检查需要一条可移植的执行路径，且该路径不能依赖仓库外部的运行器预配。 + +## 决策 + +[CI](../../../../.github/workflows/ci.yml) 在 GitHub 标准的 `ubuntu-latest` 或 `windows-2025` 容量上运行每项拉取请求必需作业。主 Node 作业和 Windows 作业保留各自完整的合并清单，而顶层门禁、覆盖率、ESLint、publint 和快照回放在这些较小的主机上均使用 1 个工作线程。Node 版本通过 `actions/setup-node` 选择；Windows 作业会在安装采用符号链接的工作区前启用开发人员模式。 + +`node 24 / complete`、Node 兼容性、Python SDK 和 `windows node 24 / complete` 作业继续作为 `all checks passed` 的依赖项；为恢复可用性，不会移除任何门禁，也不会将其降为观测性检查。分支保护继续要求 `e2e` 和 `all checks passed`。 + +两项手动大型运行器套件和全部 12 个组织自有标签继续用于测量，但不参与普通拉取请求。[大型运行器测量结果](2026-07-22-evidence-based-larger-hosted-runners.md)继续作为后续性能工作的证据，[跨平台串行参考流程](2026-07-21-serial-cross-platform-ci-reference.md)则继续作为 master 推送时独立的完整性检查。 + +## 曾考虑的替代方案 + +**等待组织运行器恢复分配。** 未分配运行器的队列不会产生仓库诊断信息，而且可能无限期阻塞每个拉取请求，因此依赖外部恢复不能构成正确性路径。 + +**仅使用最小的组织自有运行器池。** 每个指定的运行器池都需要经过相同的组织分配边界；减少核心数不能消除导致作业排队的依赖。 + +**在容量不可用时跳过检查或降低其级别。** 这种方式通过丢弃证据而非执行仓库的必需契约来使状态变绿。 + +**在标准运行器上保留大型主机的工作线程上限。** 完整仓库门禁及其内层工作线程池并发运行时，可能超出较小主机的内存和 CPU 配额，使可用性修复变成资源争用故障。 + +## 后果 + +普通拉取请求无需组织专有配置即可获得运行器，一次实际的分支头精确运行能够证明分支保护使用的同一组命令。代价是，与实测的大型运行器拓扑相比，总耗时更长，而且按整分钟计费的标准运行器用量更多。 + +手动大型运行器基准测试可以继续排队，而不会阻塞拉取请求。要将大型运行器恢复为必需路径，需要在分支头精确作业获得非零运行器 ID 并可靠完成后，另行作出基于证据的决策；仅改变运行器定义的状态还不够。 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2c6036968f..2eb8071a84 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -27,20 +27,19 @@ env: jobs: - # One large runner pays hosted setup once, then the repository scheduler - # overlaps the complete unsharded primary Node inventory. Build starts eagerly; - # only consumers of emitted output wait for it. + # One portable hosted runner pays setup once, then executes the complete + # unsharded primary Node inventory without organization-owned capacity. node-24: if: github.event_name == 'pull_request' - runs-on: dsh-ubuntu-24-04-96core + runs-on: ubuntu-latest name: node 24 / complete env: - DSH_COVERAGE_MAX_WORKERS: '16' + DSH_COVERAGE_MAX_WORKERS: '1' DSH_ESLINT_CACHE: '1' - DSH_ESLINT_CONCURRENCY: '16' - DSH_GATE_CONCURRENCY: '10' - DSH_PUBLINT_CONCURRENCY: '16' - DSH_SNAPSHOT_MAX_CONCURRENCY: '8' + DSH_ESLINT_CONCURRENCY: '1' + DSH_GATE_CONCURRENCY: '1' + DSH_PUBLINT_CONCURRENCY: '1' + DSH_SNAPSHOT_MAX_CONCURRENCY: '1' steps: - uses: actions/checkout@v6 with: @@ -62,16 +61,12 @@ jobs: restore-keys: | ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-full- - - name: Select preinstalled Node, install dependencies, and prepare bubblewrap + - uses: actions/setup-node@v6 + with: + node-version: ${{ env.PRIMARY_NODE_VERSION }} + + - name: Enable corepack, install dependencies, and prepare bubblewrap run: | - node_root="$(printf '%s\n' "$RUNNER_TOOL_CACHE"/node/"${PRIMARY_NODE_VERSION}".*/x64 | sort -V | tail -n 1)" - if [[ ! -d "$node_root" ]]; then - echo "preinstalled Node ${PRIMARY_NODE_VERSION}.x not found in $RUNNER_TOOL_CACHE" >&2 - exit 1 - fi - echo "$node_root/bin" >> "$GITHUB_PATH" - export PATH="$node_root/bin:$PATH" - [[ "$(node --version)" == "v${PRIMARY_NODE_VERSION}."* ]] corepack enable pnpm install --frozen-lockfile & install_pid=$! @@ -90,8 +85,7 @@ jobs: node-compat: if: github.event_name == 'pull_request' - # Distinct larger-runner pools avoid both standard-runner setup outliers and - # delayed allocation when independent environment contracts share one pool. + # Each compatibility contract receives an independent standard hosted job. runs-on: ${{ matrix.runner }} name: ${{ matrix.name }} env: @@ -103,12 +97,12 @@ jobs: include: - node: '22.19' name: node 22.19 - runner: dsh-ubuntu-24-04-4core - gate_concurrency: '2' + runner: ubuntu-latest + gate_concurrency: '1' - node: 26 name: node 26 - runner: dsh-ubuntu-24-04-32core - gate_concurrency: '2' + runner: ubuntu-latest + gate_concurrency: '1' steps: - uses: actions/checkout@v6 @@ -137,7 +131,7 @@ jobs: python-sdk: if: github.event_name == 'pull_request' - runs-on: dsh-ubuntu-24-04-8core + runs-on: ubuntu-latest name: python 3.10 / keyless SDK steps: - uses: actions/checkout@v6 @@ -158,15 +152,13 @@ jobs: # from observational gates without allowing them to fail the required job. windows: if: github.event_name == 'pull_request' - runs-on: dsh-windows-2025-32core + runs-on: windows-2025 name: windows node 24 / complete env: - # Keep ESLint itself single-threaded: 16 ESLint workers took 174 seconds on - # this image. The outer scheduler still overlaps lint with the other gates. - DSH_COVERAGE_MAX_WORKERS: '12' + DSH_COVERAGE_MAX_WORKERS: '1' DSH_ESLINT_CACHE: '1' - DSH_GATE_CONCURRENCY: '16' - DSH_PUBLINT_CONCURRENCY: '16' + DSH_GATE_CONCURRENCY: '1' + DSH_PUBLINT_CONCURRENCY: '1' steps: - uses: actions/checkout@v6 @@ -177,27 +169,21 @@ jobs: restore-keys: | ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-full- - # Extracting the many-file pnpm store cache is slower on this image than - # a clean parallel install, and saving it adds more latency after gates. - - name: Select preinstalled Node and install (immutable) + - name: Enable Developer Mode (symlink support) + shell: pwsh + run: >- + reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" + /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1" + + - uses: actions/setup-node@v6 + with: + node-version: ${{ env.PRIMARY_NODE_VERSION }} + + # Extracting the many-file pnpm store cache is slower than a clean install, + # and saving it adds more latency after gates. + - name: Enable corepack and install (immutable) shell: pwsh run: | - $nodeRoot = Get-ChildItem -Path "$env:RUNNER_TOOL_CACHE\node" -Directory | - Where-Object { $_.Name -like "$env:PRIMARY_NODE_VERSION.*" } | - Sort-Object { [version]$_.Name } | - Select-Object -Last 1 - if ($null -eq $nodeRoot) { - throw "preinstalled Node $env:PRIMARY_NODE_VERSION.x not found in $env:RUNNER_TOOL_CACHE" - } - $nodeBin = Join-Path $nodeRoot.FullName 'x64' - if (-not (Test-Path $nodeBin -PathType Container)) { - throw "preinstalled Node x64 directory not found at $nodeBin" - } - Add-Content -Path $env:GITHUB_PATH -Value $nodeBin - $env:PATH = "$nodeBin;$env:PATH" - if ((node --version) -notlike "v$env:PRIMARY_NODE_VERSION.*") { - throw "selected unexpected Node version $(node --version)" - } corepack enable pnpm install --frozen-lockfile diff --git a/README.i18n.yaml b/README.i18n.yaml index 020593bf20..41a7a06404 100644 --- a/README.i18n.yaml +++ b/README.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 -README.md: 8b34d6177834e1c410b2c3ecaf32154de42520b4 -README.zh.md: cf029cc0bb8c5aa527d14753803eac4c28ab9de7 +README.md: 27774fd3e0ffc821e7287f6153906a5d21530dc2 +README.zh.md: b7d08f2bc948d0a6d388dd672c5a702bc7da6f6f diff --git a/README.md b/README.md index 8b34d61778..27774fd3e0 100644 --- a/README.md +++ b/README.md @@ -2,32 +2,76 @@ English | [中文](README.zh.md) -The **DeepSeek Harness SDK** is a plugin-based SDK for building agent harnesses. +DeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK. + +It uses an architecture where **everything is a plugin**. ## Install -Install the `dsh` coding agent with one line — it needs `git` and Node `^22.19 || >=24`, and offers to install `pnpm` if it is missing: +Install `dsh` with one command: ```sh curl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh ``` -It clones the harness to `~/.dsh/source`, runs `pnpm install`, symlinks `dsh` into `~/.local/bin` (offering to add it to your PATH), prompts once for your `DEEPSEEK_API_KEY`, and launches `dsh`; re-running it updates an existing checkout. Run from inside a checkout (`sh scripts/install.sh`) it reuses that checkout and skips the clone. The overridable `DSH_*` variables are documented in [`scripts/install.sh`](scripts/install.sh). +The installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, and prompts for a DeepSeek API key. + +The installer clones DeepSeek Harness to `~/.dsh/source`, links `dsh` into `~/.local/bin`, and launches it. Re-running the command updates the checkout. See [`scripts/install.sh`](scripts/install.sh) for alternate install locations and other options. + +## Use DeepSeek Harness + +### Web UI + +For the recommended local interface, build the frontend after installation and after each update, then start the Web UI: + +```sh +pnpm --dir ~/.dsh/source run build:web +dsh web +``` + +The Web UI is served at `http://127.0.0.1:3080` by default. + +### TUI + +Start the full-screen terminal interface: + +```sh +dsh +``` + +### Headless + +Run one task, print the final answer, and exit: + +```sh +dsh -p "summarize this workspace" +``` + +## Why DeepSeek Harness + +Built-in capabilities cover file reading, editing, and search; shell execution; reusable skills; task tracking; subagents and workflows; persistent sessions; and context compaction. The TUI also includes Plan Mode. + +- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design. +- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode). +- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/cordis/tool-cordis/README.md). + +## Community + +Follow DeepSeek Harness on Twitter for project updates. ## Development -This monorepo is built on the [Cordis](https://github.com/cordiverse/cordis) framework (vendored as source under `vendor/`), microkernel-style: everything is a plugin. - ```sh pnpm install -pnpm run test # vitest -# Agent demos require DEEPSEEK_API_KEY. -pnpm run demo:tui # full-screen TUI coding agent -pnpm run demo:headless "task" # one-shot coding agent -pnpm run demo:cordis # self-referential agent demo -pnpm run demo:acp # ACP server agent demo +pnpm run test:coverage ``` -For humans, start with the [development guide](docs/development.md) for local setup, hooks, environment variables, and quality gates, then read the [architecture design](docs/architecture.md) and [documentation graph index](docs/graph-atlas.md) before package work. Local context lives in [packages/](packages/) and [vendor/](vendor/). +Start with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages. For agents, follow [AGENTS.md](AGENTS.md). + +DeepSeek Harness is currently pre-release. + +## License + +[BSD 3-Clause](LICENSE) diff --git a/README.zh.md b/README.zh.md index cf029cc0bb..b7d08f2bc9 100644 --- a/README.zh.md +++ b/README.zh.md @@ -2,32 +2,80 @@ [English](README.md) | 中文 -**DeepSeek Harness SDK** 是用于构建 agent harness（智能体框架）的 SDK，采取基于插件的设计。 +DeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。 + +它采用了**一切皆插件**的架构。 ## 安装 -一行命令即可安装 `dsh` 编码智能体——需要 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时会询问是否代为安装： +使用一条命令安装 `dsh`： ```sh curl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh ``` -脚本会把 harness 克隆到 `~/.dsh/source`，运行 `pnpm install`，把 `dsh` 软链接到 `~/.local/bin`（并询问是否加入 PATH），提示输入一次 `DEEPSEEK_API_KEY`，随后启动 `dsh`；再次运行会更新已有的检出。若在检出目录内运行（`sh scripts/install.sh`），脚本会复用当前检出并跳过克隆。可覆盖的 `DSH_*` 变量见 [`scripts/install.sh`](scripts/install.sh)。 +安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥。 + +安装器会将 DeepSeek Harness 克隆到 `~/.dsh/source`，把 `dsh` 链接到 `~/.local/bin`，然后启动它。再次运行该命令会更新源码目录。其他安装位置和选项见 [`scripts/install.sh`](scripts/install.sh)。 + +## 使用 DeepSeek Harness + +### Web UI + +推荐在本地使用 Web UI。安装完成后以及每次更新后，请先构建前端，再启动 Web UI： + +```sh +pnpm --dir ~/.dsh/source run build:web +dsh web +``` + +Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。 + +### TUI + +启动全屏终端界面： + +```sh +dsh +``` + +### Headless + +运行一项任务，打印最终答案后退出： + +```sh +dsh -p "summarize this workspace" +``` + +## 为什么选择 DeepSeek Harness + +内置功能涵盖文件读取、编辑与搜索、shell 执行、可复用 skill（技能）、任务跟踪、subagent 与工作流、持久化会话，以及上下文压缩（context compaction）。TUI 还包含 Plan Mode。 + +- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。 +- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。 +- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/cordis/tool-cordis/README.md)。 + +## 社区 + +扫描二维码，或打开 DeepSeek Harness 微信社区申请页面 申请加入。 + +

+ DeepSeek Harness 微信社区二维码 +

## 开发 -本 monorepo 基于 [Cordis](https://github.com/cordiverse/cordis) 框架构建（以源码形式收录在 `vendor/` 下），采用微内核风格：所有功能都以插件形式提供。 - ```sh pnpm install -pnpm run test # vitest -# Agent demos require DEEPSEEK_API_KEY. -pnpm run demo:tui # full-screen TUI coding agent -pnpm run demo:headless "task" # one-shot coding agent -pnpm run demo:cordis # self-referential agent demo -pnpm run demo:acp # ACP server agent demo +pnpm run test:coverage ``` -面向开发者：先读[开发指南](docs/development.md)，了解本地环境搭建、钩子、环境变量与质量门禁，动手改 package 之前再读[架构设计](docs/architecture.md)和[文档关系图索引](docs/graph-atlas.md)。局部上下文见 [packages/](packages/) 与 [vendor/](vendor/)。 +请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。 面向 agent：遵循 [AGENTS.md](AGENTS.md)。 + +DeepSeek Harness 目前处于预发布阶段。 + +## 许可证 + +[BSD 3-Clause](LICENSE) diff --git a/apps/web/tests/smoke-fixture.e2e.ts b/apps/web/tests/smoke-fixture.e2e.ts index 0770037a70..3fccde9a79 100644 --- a/apps/web/tests/smoke-fixture.e2e.ts +++ b/apps/web/tests/smoke-fixture.e2e.ts @@ -1,6 +1,6 @@ // Keyless boot-chain smoke over the REAL carrier: startWebServer + web-plugins // registry surface + __DSH_BOOT__ injection + built shell dist in a real -// chromium. First describe: manifest injection + fail-loud half. Second +// chromium. First describe: manifest injection + static serving. Second // describe: the settled success pass — seven REAL tsdown bundles (the // infrastructure four + layout/sidebar/conversation) load through the DI // chain in ?fixture mode and the three-column frame appears in one flip. The @@ -17,7 +17,7 @@ import { DIST_INDEX, probeFreePort, requireDist, saveFailureShot } from './suppo const bundlePath = (dir: string): string => fileURLToPath(new URL(`../../../packages/client/${dir}/lib/client.js`, import.meta.url)) -/** id ↔ bundle table for the success pass (immediately four + layout). */ +/** id ↔ bundle table for the success pass (immediately four + layout/sidebar). */ const REAL_PLUGINS: { id: string; dir: string; inject: string[]; immediately?: boolean }[] = [ { id: '@deepseek-ai/dsh-client-connection', dir: 'connection', inject: [], immediately: true }, { id: '@deepseek-ai/dsh-client-runtime', dir: 'runtime', inject: ['@deepseek-ai/dsh-client-connection'], immediately: true }, @@ -78,15 +78,6 @@ describe('web boot chain (keyless, real carrier)', () => { expect(await res.text()).toContain('window.DSHClientProxy.loadPlugin') }) - it('boots to the loading page and fail-louds the absent plugin', async () => { - onTestFailed(() => saveFailureShot(page, 'smoke-boot-fail-loud')) - await page.waitForSelector('text=HARNESS', { timeout: 10_000 }) - await page.waitForSelector('text=Failed to load plugins', { timeout: 10_000 }) - await page.waitForSelector('text=@probe/absent', { timeout: 2000 }) - // The real UI must not have flipped in: the gate opens only on settled(). - expect(await page.locator('[class*="frame"]').count()).toBe(0) - }) - it('applies the token sheets before any plugin CSS', async () => { const family = await page.evaluate(() => getComputedStyle(document.body).getPropertyValue('--dsw-font-family')) expect(family.trim().length).toBeGreaterThan(0) @@ -143,6 +134,38 @@ describe('web boot chain success pass (keyless, seven real bundles, ?fixture)', const owners = await page.evaluate(() => [...document.querySelectorAll('style[data-plugin]')].map(s => (s as HTMLElement).dataset['plugin'])) expect(owners).toContain('@deepseek-ai/dsh-client-ui-layout') + expect(owners).toContain('@deepseek-ai/dsh-client-ui-sidebar') + }) + + it('collapsed sidebar animates to a 56px rail with the four controls', async () => { + onTestFailed(() => saveFailureShot(page, 'smoke-boot-collapsed-rail')) + const frame = page.locator('[class*="frame"]') + const firstTrack = async (): Promise => (await frame.evaluate( + el => getComputedStyle(el).gridTemplateColumns)).split(' ')[0]! + // The tracks transition on the deepsuite curve; assert the animated + // settle rather than an instant jump. + const settledTrack = async (px: string): Promise => { + await expect.poll(firstTrack, { timeout: 2000 }).toBe(px) + } + await page.getByRole('button', { name: 'Collapse sidebar' }).click() + // Mid-collapse the wide chrome is still mounted, fading — not swapped out. + expect(await page.locator('text=HARNESS').count()).toBe(1) + await settledTrack('56px') + await expect.poll(() => page.locator('text=HARNESS').count(), { timeout: 2000 }).toBe(0) + for (const name of ['Expand sidebar', 'New session', 'New workspace', 'Search sessions', 'Settings']) { + await expect(page.getByRole('button', { name }).isVisible(), name).resolves.toBe(true) + } + await page.getByRole('button', { name: 'Expand sidebar' }).click() + await settledTrack('300px') + await expect(page.getByRole('button', { name: 'Collapse sidebar' }).isVisible()).resolves.toBe(true) + // Rail search: collapse again, the search control expands and lands in the box. + await page.getByRole('button', { name: 'Collapse sidebar' }).click() + await settledTrack('56px') + await page.getByRole('button', { name: 'Search sessions' }).click() + await settledTrack('300px') + const focused = await page.evaluate(() => + (document.activeElement as HTMLInputElement | null)?.placeholder ?? '') + expect(focused).toContain('Search') }) it('renders file tool rows and expands fixture reasoning from either click target', async () => { diff --git a/assets/community-wecom-survey.png b/assets/community-wecom-survey.png new file mode 100644 index 0000000000..d6f6040ba7 Binary files /dev/null and b/assets/community-wecom-survey.png differ diff --git a/packages/client/ui-layout/README.md b/packages/client/ui-layout/README.md index cadffd03e1..6cb5fa29a4 100644 --- a/packages/client/ui-layout/README.md +++ b/packages/client/ui-layout/README.md @@ -1,6 +1,6 @@ # @deepseek-ai/dsh-client-ui-layout -Shell plugin: three-column AppFrame (drag handles, concession chain) + ctx.layout viewing-state service (nav, panel widths, persist); defines the sidebar/conversation/details/conversation.empty slots. Contract: api-contracts v3 §5. +Shell plugin: three-column AppFrame (drag handles, concession chain) + ctx.layout viewing-state service (nav, panel widths, persist); defines the sidebar/conversation/details/conversation.empty slots. A closed sidebar retains a 56px control rail while details closes to zero width; collapse/expand animates the grid tracks on the deepsuite sider curve. Contract: api-contracts v3 §5. Slot declarations use the composed-props entry form (`owner` share, no full `props`): the exported OwnerShare contracts are `SidebarOwnerProps` / `ConvOwnerProps` / `DetailsOwnerProps` / `EmptyOwnerProps` — registrants reference them via `OwnerOf<'sidebar' | ...>` and compose their own injected share locally. No entry declares `children` (declaring it requires the registered component to carry the slots face — reserved for future business slots): delegation authority is the component-side whitelist, i.e. AppFrame's `ScopedSlots` face over sidebar/conversation/details/conversation.empty. Since the root-slot rework the frame itself registers into 'root' and renders those child slots at its own render sites; the shell only renders 'root'. diff --git a/packages/client/ui-layout/src/client/AppFrame.module.css b/packages/client/ui-layout/src/client/AppFrame.module.css index b7a03c7f2f..631bb929db 100644 --- a/packages/client/ui-layout/src/client/AppFrame.module.css +++ b/packages/client/ui-layout/src/client/AppFrame.module.css @@ -5,6 +5,21 @@ height: 100%; overflow: hidden; background: var(--dsw-alias-bg-base); + /* Collapse/expand animates the tracks on the deepsuite sider curve + (--ds-ease-in-out / --ds-transition-duration-slow, ui-theme base.css). */ + transition: grid-template-columns var(--ds-transition-duration-slow) var(--ds-ease-in-out); +} + +/* Dragging writes widths at pointer cadence; easing them would detach the + column from the handle. */ +.frame[data-dragging] { + transition: none; +} + +@media (prefers-reduced-motion: reduce) { + .frame { + transition: none; + } } .sidebarCol { @@ -27,13 +42,8 @@ border-left: 1px solid var(--dsw-alias-border-l2); } -/* Collapsed columns keep children mounted; the border must not paint a 1px seam. - Flags live on the frame — DetailsColumn renders inside the provider body and - does not know its own width. */ -.frame[data-sidebar-collapsed] .sidebarCol { - border-right: none; -} - +/* The details subtree stays mounted at zero width, so its border must not paint + a 1px seam. The collapsed sidebar instead retains a bordered compact rail. */ .frame[data-details-collapsed] .detailsCol { border-left: none; } @@ -51,6 +61,19 @@ cursor: col-resize; z-index: 2; touch-action: none; + /* Rides the same curve as the tracks so the pill stays on the moving + border during collapse/expand; paused while dragging (frame rule). */ + transition: left var(--ds-transition-duration-slow) var(--ds-ease-in-out); +} + +.frame[data-dragging] .handle { + transition: none; +} + +@media (prefers-reduced-motion: reduce) { + .handle { + transition: none; + } } .handle::after { diff --git a/packages/client/ui-layout/src/client/AppFrame.tsx b/packages/client/ui-layout/src/client/AppFrame.tsx index 5c5e989957..e40c94454d 100644 --- a/packages/client/ui-layout/src/client/AppFrame.tsx +++ b/packages/client/ui-layout/src/client/AppFrame.tsx @@ -35,13 +35,13 @@ function DetailsColumn(props: { children?: ReactNode }) { } /** One drag handle: pointer capture, rAF-throttled dx reports against the drag-start origin. */ -function DragHandle(props: { left: number; onStart: () => void; onDrag: (dx: number) => void }) { +function DragHandle(props: { left: number; onStart: () => void; onDrag: (dx: number) => void; onEnd: () => void }) { const [dragging, setDragging] = useState(false) const origin = useRef(0) const latest = useRef(0) const frame = useRef(null) - const callbacks = useRef({ onStart: props.onStart, onDrag: props.onDrag }) - callbacks.current = { onStart: props.onStart, onDrag: props.onDrag } + const callbacks = useRef({ onStart: props.onStart, onDrag: props.onDrag, onEnd: props.onEnd }) + callbacks.current = { onStart: props.onStart, onDrag: props.onDrag, onEnd: props.onEnd } const onPointerDown = useCallback((e: React.PointerEvent) => { e.preventDefault() @@ -65,6 +65,7 @@ function DragHandle(props: { left: number; onStart: () => void; onDrag: (dx: num if (frame.current !== null) { cancelAnimationFrame(frame.current); frame.current = null } callbacks.current.onDrag(latest.current - origin.current) setDragging(false) + callbacks.current.onEnd() }, []) return ( @@ -114,8 +115,12 @@ export function AppFrame({ useStore, actions, renderSlot, SessionProvider }: App // it stays frozen for the whole gesture so dx deltas do not compound. const sidebarBase = useRef(0) const detailsBase = useRef(0) - const onSidebarStart = useCallback(() => { sidebarBase.current = colsRef.current.sidebar }, []) - const onDetailsStart = useCallback(() => { detailsBase.current = colsRef.current.details }, []) + // Track-level transitions pause for the whole gesture: eased tracks would + // detach the column edge from the pointer (AppFrame.module.css). + const [dragging, setDragging] = useState(false) + const onDragEnd = useCallback(() => { setDragging(false) }, []) + const onSidebarStart = useCallback(() => { sidebarBase.current = colsRef.current.sidebar; setDragging(true) }, []) + const onDetailsStart = useCallback(() => { detailsBase.current = colsRef.current.details; setDragging(true) }, []) const onSidebarDrag = useCallback((dx: number) => { actions.setSidebar(sidebarBase.current + dx) }, [actions]) @@ -128,14 +133,16 @@ export function AppFrame({ useStore, actions, renderSlot, SessionProvider }: App ref={frameRef} className={css.frame} style={{ gridTemplateColumns: `${cols.sidebar}px minmax(0, 1fr) ${cols.details}px` }} - data-sidebar-collapsed={cols.sidebar === 0 || undefined} + data-sidebar-collapsed={panels.sidebar === 0 || undefined} data-details-collapsed={cols.details === 0 || undefined} + data-dragging={dragging || undefined} >
- {/* Render-site slot call with live concession output: the sidebar - stays mounted at zero width (CSS hides it), and sees its rendered - state as owner params decided here, not precomputed upstream. */} - {renderSlot('sidebar', { collapsed: cols.sidebar === 0, width: cols.sidebar })} + {/* Render-site slot call with live concession output: a closed + sidebar keeps the mounted slot at the compact-rail width, and the + component sees its rendered state as owner params decided here + (collapsed follows the preference, not the resolved width). */} + {renderSlot('sidebar', { collapsed: panels.sidebar === 0, width: cols.sidebar })}
( @@ -153,8 +160,9 @@ export function AppFrame({ useStore, actions, renderSlot, SessionProvider }: App )} - {cols.sidebar > 0 && } - {cols.details > 0 && } + {/* The collapsed rail is fixed-width: no resize handle while closed. */} + {panels.sidebar > 0 && } + {cols.details > 0 && } ) } diff --git a/packages/client/ui-layout/src/client/columns.ts b/packages/client/ui-layout/src/client/columns.ts index 5d4d611707..d7a63aafa2 100644 --- a/packages/client/ui-layout/src/client/columns.ts +++ b/packages/client/ui-layout/src/client/columns.ts @@ -4,7 +4,9 @@ * details first, then sidebar, then auto-closing details (derived zero width — * persisted width preferences are never rewritten, so widening the window * restores them). Center absorbs any remaining deficit as the last resort. - * Inputs are the layout store's plain width preferences (0 = closed). + * Inputs are the layout store's plain width preferences (0 = closed); a + * closed sidebar resolves to the fixed SIDEBAR_COLLAPSED control rail while + * closed details resolve to zero width. */ /** Resolved widths for one frame; center may drop below CENTER_MIN only at the final fallback. */ @@ -19,6 +21,8 @@ export const SIDEBAR_MIN = 240 export const SIDEBAR_MAX = 420 /** Sidebar width before any user drag. */ export const SIDEBAR_DEFAULT = 300 +/** Closed-sidebar rail: a 24px icon column between 16px horizontal paddings. */ +export const SIDEBAR_COLLAPSED = 56 /** Details drag clamp floor. */ export const DETAILS_MIN = 300 /** Details drag clamp ceiling. */ @@ -47,10 +51,10 @@ export function clampWidth(px: number, min: number, max: number): number { * @param viewport - available frame width in px. * @param sidebar - sidebar width preference in px (0 = closed). * @param details - details width preference in px (0 = closed). - * @returns resolved widths; details 0 means visually closed (never unmounted). + * @returns resolved widths; details 0 means visually closed (never unmounted), while a closed sidebar keeps its compact rail. */ export function computeColumns(viewport: number, sidebar: number, details: number): Columns { - const s0 = sidebar === 0 ? 0 : clampWidth(sidebar, SIDEBAR_MIN, SIDEBAR_MAX) + const s0 = sidebar === 0 ? SIDEBAR_COLLAPSED : clampWidth(sidebar, SIDEBAR_MIN, SIDEBAR_MAX) const d0 = details === 0 ? 0 : clampWidth(details, DETAILS_MIN, DETAILS_MAX) // Step 1: everything fits at preferred widths. @@ -60,15 +64,15 @@ export function computeColumns(viewport: number, sidebar: number, details: numbe const d1 = d0 === 0 ? 0 : Math.max(DETAILS_MIN, viewport - s0 - CENTER_MIN) if (s0 + d1 + CENTER_MIN <= viewport) return { sidebar: s0, center: CENTER_MIN, details: d1 } - // Step 3: shrink sidebar toward its minimum. - const s1 = s0 === 0 ? 0 : Math.max(SIDEBAR_MIN, viewport - d1 - CENTER_MIN) + // Step 3: shrink sidebar toward its minimum (the collapsed rail never shrinks). + const s1 = sidebar === 0 ? SIDEBAR_COLLAPSED : Math.max(SIDEBAR_MIN, viewport - d1 - CENTER_MIN) if (s1 + d1 + CENTER_MIN <= viewport) return { sidebar: s1, center: CENTER_MIN, details: d1 } // Step 4: auto-close details (derived — preferences untouched). With the // details pressure gone the sidebar concession is re-solved from preference. if (d1 > 0) { if (s0 + CENTER_MIN <= viewport) return { sidebar: s0, center: viewport - s0, details: 0 } - const s2 = s0 === 0 ? 0 : Math.max(SIDEBAR_MIN, viewport - CENTER_MIN) + const s2 = sidebar === 0 ? SIDEBAR_COLLAPSED : Math.max(SIDEBAR_MIN, viewport - CENTER_MIN) return { sidebar: s2, center: Math.max(0, viewport - s2), details: 0 } } diff --git a/packages/client/ui-layout/src/client/index.ts b/packages/client/ui-layout/src/client/index.ts index 00555e90dc..1aeb04593b 100644 --- a/packages/client/ui-layout/src/client/index.ts +++ b/packages/client/ui-layout/src/client/index.ts @@ -50,9 +50,9 @@ declare module '@deepseek-ai/dsh-client-ui-slots' { /** Sidebar owner share: live column state from the frame's concession solve. */ export interface SidebarOwnerProps { - /** True when the concession chain rendered the column at zero width. */ + /** True when the sidebar is closed (the column renders the compact control rail). */ collapsed: boolean - /** Rendered column width in px (0 when collapsed). */ + /** Rendered column width in px (SIDEBAR_COLLAPSED when collapsed). */ width: number } diff --git a/packages/client/ui-layout/tests/app-frame.spec.tsx b/packages/client/ui-layout/tests/app-frame.spec.tsx index 7e65445a3a..120197d531 100644 --- a/packages/client/ui-layout/tests/app-frame.spec.tsx +++ b/packages/client/ui-layout/tests/app-frame.spec.tsx @@ -15,6 +15,7 @@ import { act, cleanup, render } from '@testing-library/react' import { useSyncExternalStore } from 'react' import { AppFrame } from '@deepseek-ai/dsh-client-ui-layout/src/client/AppFrame.tsx' import type { AppFrameProps } from '@deepseek-ai/dsh-client-ui-layout/src/client/AppFrame.tsx' +import { SIDEBAR_COLLAPSED } from '@deepseek-ai/dsh-client-ui-layout/src/client/columns.ts' import { createLayoutStore } from '@deepseek-ai/dsh-client-ui-layout/src/client/stores.ts' // Session-mode switch for the SessionProvider stub prop. @@ -175,6 +176,16 @@ describe('AppFrame', () => { expect(frame.hasAttribute('data-details-collapsed')).toBe(true) }) + it('closed sidebar keeps its compact rail with mounted slot content and collapsed owner props', () => { + const { frame, instance, slotCalls, getByTestId } = mountFrame() + act(() => { instance.actions.toggleSidebar() }) + expect(tracks(frame)).toEqual([SIDEBAR_COLLAPSED, 360]) + expect(getByTestId('sidebar-content')).toBeTruthy() + expect(frame.hasAttribute('data-sidebar-collapsed')).toBe(true) + const lastSidebarCall = slotCalls.filter((c) => c.key === 'sidebar').at(-1)! + expect(lastSidebarCall.props).toEqual({ collapsed: true, width: SIDEBAR_COLLAPSED }) + }) + it('viewport shrink triggers the concession chain via ResizeObserver', () => { const { frame } = mountFrame() frameWidth = 1250 diff --git a/packages/client/ui-layout/tests/columns.spec.ts b/packages/client/ui-layout/tests/columns.spec.ts index 8fb355bb19..6358c45076 100644 --- a/packages/client/ui-layout/tests/columns.spec.ts +++ b/packages/client/ui-layout/tests/columns.spec.ts @@ -1,7 +1,7 @@ import { describe, expect, it } from 'vitest' import { CENTER_MIN, clampWidth, computeColumns, - DETAILS_DEFAULT, DETAILS_MIN, SIDEBAR_DEFAULT, SIDEBAR_MIN, + DETAILS_DEFAULT, DETAILS_MIN, SIDEBAR_COLLAPSED, SIDEBAR_DEFAULT, SIDEBAR_MIN, } from '@deepseek-ai/dsh-client-ui-layout/src/client/columns.ts' // Numeric preference form (0 = closed); helpers keep the scenario names readable. @@ -22,8 +22,9 @@ describe('computeColumns', () => { expect(cols).toEqual({ sidebar: 300, center: 1920 - 300 - 360, details: 360 }) }) - it('closed panels contribute zero width', () => { - expect(computeColumns(1920, closed(300), closed(360))).toEqual({ sidebar: 0, center: 1920, details: 0 }) + it('closed sidebar keeps its compact rail while closed details contribute zero width', () => { + expect(computeColumns(1920, closed(300), closed(360))) + .toEqual({ sidebar: SIDEBAR_COLLAPSED, center: 1920 - SIDEBAR_COLLAPSED, details: 0 }) }) it('preferences beyond the clamp range are clamped before solving', () => { @@ -70,10 +71,14 @@ describe('computeColumns', () => { }) it('sidebar-closed narrow window: details concedes then auto-closes', () => { - const fits = computeColumns(DETAILS_MIN + CENTER_MIN, closed(300), open(DETAILS_DEFAULT)) - expect(fits).toEqual({ sidebar: 0, center: CENTER_MIN, details: DETAILS_MIN }) - const starved = computeColumns(DETAILS_MIN + CENTER_MIN - 1, closed(300), open(DETAILS_DEFAULT)) - expect(starved).toEqual({ sidebar: 0, center: DETAILS_MIN + CENTER_MIN - 1, details: 0 }) + const fits = computeColumns(SIDEBAR_COLLAPSED + DETAILS_MIN + CENTER_MIN, closed(300), open(DETAILS_DEFAULT)) + expect(fits).toEqual({ sidebar: SIDEBAR_COLLAPSED, center: CENTER_MIN, details: DETAILS_MIN }) + const starved = computeColumns(SIDEBAR_COLLAPSED + DETAILS_MIN + CENTER_MIN - 1, closed(300), open(DETAILS_DEFAULT)) + expect(starved).toEqual({ + sidebar: SIDEBAR_COLLAPSED, + center: DETAILS_MIN + CENTER_MIN - 1, + details: 0, + }) }) it('tiny viewport: both panels yield everything to center', () => { @@ -93,9 +98,9 @@ describe('computeColumns', () => { }) describe('computeColumns — degenerate viewports', () => { - it('sidebar closed and viewport below CENTER_MIN: details auto-closes, center takes all', () => { - // Reaches step 4's re-solve with s0 = 0 (the closed-sidebar arm). + it('sidebar closed and viewport below CENTER_MIN: details auto-closes, center takes the rest', () => { + // Reaches step 4's re-solve with the compact rail as the sidebar floor. expect(computeColumns(500, closed(300), open(DETAILS_DEFAULT))) - .toEqual({ sidebar: 0, center: 500, details: 0 }) + .toEqual({ sidebar: SIDEBAR_COLLAPSED, center: 500 - SIDEBAR_COLLAPSED, details: 0 }) }) }) diff --git a/packages/client/ui-sidebar/README.md b/packages/client/ui-sidebar/README.md index 52abd0c673..33cdeb756d 100644 --- a/packages/client/ui-sidebar/README.md +++ b/packages/client/ui-sidebar/README.md @@ -1,6 +1,6 @@ # @deepseek-ai/dsh-client-ui-sidebar -Sidebar plugin: session multi-level tree (cwd grouping + parentId nesting), search, by-workspace grouping, state dots, three creation entries. Contract: the [slot system standard](../../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md). +Sidebar plugin: session multi-level tree (cwd grouping + parentId nesting), search, by-workspace grouping, state dots, three creation entries. Collapse morphs the four control rows into the layout-owned 56px rail (expand / new session / new workspace / search — search expands and focuses the search box) plus the settings foot: geometry animates on the deepsuite curve while wide-only content cross-fades and unmounts at settle. Contract: the [slot system standard](../../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md). `src/client/contract/slots.ts` is the single-domain contract file: `SidebarRootInjected` (the registrant's own injected share — plain service callbacks: onOpen/onCreate/onToggleSidebar) and `SidebarRootComponentProps = PropsRuntime<'sidebar'> & SidebarRootInjected` (owner `{collapsed,width}` plus the standard `useSessions` hook, resolved off ui-layout's SlotMap declaration, never re-stated). `apply` registers SidebarRoot cast-free against that composition; the inject factory closes over the plugin's own ctx. diff --git a/packages/client/ui-sidebar/src/client/SidebarRoot.module.css b/packages/client/ui-sidebar/src/client/SidebarRoot.module.css index 5fdcbce74c..c580d47b75 100644 --- a/packages/client/ui-sidebar/src/client/SidebarRoot.module.css +++ b/packages/client/ui-sidebar/src/client/SidebarRoot.module.css @@ -1,39 +1,64 @@ -/* Sidebar column (figma 133:7629): vertical stack, gap 8, padding 16/6, - sidebar fill + 1px right border painted by the layout column. Header block - (logo + New Session) and list area (section header + search + cells) carry - their own inner gaps per the style spec (1.2 / 1.3). */ +/* Sidebar column (figma 133:7629): vertical stack, padding 16/6, sidebar + fill + 1px right border painted by the layout column. Collapse morphs in + place: the four control rows persist into the 56px rail (one icon each, + x-converged by the shrinking column), geometry rides the deepsuite curve + while wide-only content cross-fades 200ms; explicit margins own the + vertical rhythm in both states so every gap can transition. */ .root { display: flex; flex-direction: column; - gap: 8px; height: 100%; padding: 6px 16px; box-sizing: border-box; background: var(--dsw-specific-sidebar-fill); color: var(--dsw-alias-label-primary); font-size: 14px; + transition: padding var(--ds-transition-duration-slow) var(--ds-ease-in-out); } -/* Header block (figma 133:7630): logo row + New Session, gap 16, padBottom 12. */ -.headerBlock { - flex: none; - display: flex; - flex-direction: column; - gap: 16px; - padding-bottom: 12px; +.root.collapsed { + padding-top: 14px; } -/* Logo row: 60px, brand mark left, collapse button right. - figma pad is (l,t,r,b)=(4,8,4,8) — horizontal 4, vertical 8. */ +/* Wide-only content: fades ahead of the geometry (200ms vs 300ms) and + unmounts once the collapse settles; remounts fade back in. */ +.wide { + animation: wide-in 200ms var(--ds-ease-in-out); + transition: opacity 200ms var(--ds-ease-in-out); +} + +.collapsed .wide { + opacity: 0; +} + +@keyframes wide-in { + from { opacity: 0; } +} + +/* Logo row (figma pad (4,8,4,8)): brand left, panel toggle right-anchored — + the toggle is the rail's expand control and slides in with the right edge. */ .logoRow { flex: none; display: flex; align-items: center; + justify-content: flex-end; gap: 8px; height: 60px; padding: 8px 4px; + margin-bottom: 16px; box-sizing: border-box; + overflow: hidden; + transition: + height var(--ds-transition-duration-slow) var(--ds-ease-in-out), + padding var(--ds-transition-duration-slow) var(--ds-ease-in-out), + margin var(--ds-transition-duration-slow) var(--ds-ease-in-out); +} + +.collapsed .logoRow { + height: 24px; + padding: 0; + margin-bottom: 8px; } /* Brand group (figma I133:7632): fish + wordmark ride the text ink @@ -79,13 +104,22 @@ background: transparent; cursor: pointer; color: var(--dsw-alias-label-secondary); + transition: + width var(--ds-transition-duration-slow) var(--ds-ease-in-out), + height var(--ds-transition-duration-slow) var(--ds-ease-in-out); } .iconButton:hover { background: var(--dsw-alias-interactive-bg-hover); } -/* New Session: 38px capsule (figma 133:7634). */ +.collapsed .iconButton { + width: 24px; + height: 24px; +} + +/* New Session: 38px capsule (figma 133:7634) morphing into the rail's plain + icon control — border and fill fade with the label. */ .newSession { flex: none; display: flex; @@ -94,6 +128,7 @@ gap: 6px; height: 38px; padding: 8px 16px; + margin-bottom: 20px; /* former headerBlock padBottom 12 + root gap 8 */ box-sizing: border-box; border: 1px solid var(--dsw-alias-border-l2); border-radius: 24px; @@ -103,65 +138,84 @@ font-weight: 510; line-height: 22px; cursor: pointer; + overflow: hidden; + transition: + height var(--ds-transition-duration-slow) var(--ds-ease-in-out), + padding var(--ds-transition-duration-slow) var(--ds-ease-in-out), + margin var(--ds-transition-duration-slow) var(--ds-ease-in-out), + gap var(--ds-transition-duration-slow) var(--ds-ease-in-out), + border-color var(--ds-transition-duration-slow) var(--ds-ease-in-out), + background-color 200ms var(--ds-ease-in-out); } .newSession:hover { background: var(--dsw-alias-button-floating-hover); } -/* List area (figma 133:7640): section header + search + cells, gap 4. - Relative for the bottom fade overlay. */ -.listArea { - position: relative; - flex: 1; - min-height: 0; - display: flex; - flex-direction: column; - gap: 4px; +.collapsed .newSession { + height: 24px; + padding: 0; + margin-bottom: 8px; + gap: 0; + border-color: transparent; + background: transparent; } -/* Bottom fade (figma 133:7666): 72px overlay pinned to the visible bottom, - transparent -> sidebar fill so it tracks the theme. */ -.fade { - position: absolute; - left: 0; - right: 0; - bottom: 0; - height: 72px; - background: linear-gradient(to bottom, transparent, var(--dsw-specific-sidebar-fill)); - pointer-events: none; +.collapsed .newSession:hover { + background: var(--dsw-alias-interactive-bg-hover); } -/* Batch separator (figma 133:7661): 20px spacer after an expanded project's - session run, before the next project row. */ -.batchGap { - flex: none; - height: 20px; +.newSessionLabel { + max-width: 200px; + overflow: hidden; + white-space: nowrap; + transition: max-width var(--ds-transition-duration-slow) var(--ds-ease-in-out); } -/* Section header: 36px, "WorkSpace" label + group-by / new-workspace buttons. */ +.collapsed .newSessionLabel { + max-width: 0; +} + +/* Section header: 36px, "WorkSpace" label + group-by / new-workspace buttons; + the right-anchored new-workspace button is the row's rail survivor. */ .sectionHeader { flex: none; display: flex; align-items: center; + justify-content: flex-end; gap: 4px; height: 36px; padding-left: 12px; + margin-bottom: 4px; box-sizing: border-box; border-radius: 12px; + overflow: hidden; color: var(--dsw-alias-label-tertiary); + transition: + height var(--ds-transition-duration-slow) var(--ds-ease-in-out), + padding var(--ds-transition-duration-slow) var(--ds-ease-in-out), + margin var(--ds-transition-duration-slow) var(--ds-ease-in-out); +} + +.collapsed .sectionHeader { + height: 24px; + padding-left: 0; + margin-bottom: 8px; } .sectionLabel { flex: 1; min-width: 0; + overflow: hidden; + white-space: nowrap; line-height: 20px; } -/* Search input: 38px capsule (figma 133:7649). Upstream binds a dedicated - design-system variable (light #F1F3F5 / dark #1B1B1C) matching no shipped - alias — a component token pinned to the static scale mirrors it (ruled - compliant: indirect via custom property, upstream-variable equivalent). */ +/* Search input: 38px capsule (figma 133:7649) morphing into the rail's + search control. Upstream binds a dedicated design-system variable (light + #F1F3F5 / dark #1B1B1C) matching no shipped alias — a component token + pinned to the static scale mirrors it (ruled compliant: indirect via + custom property, upstream-variable equivalent). */ .search { --dsh-search-input-fill: var(--dsw-static-neutral-bluish-75); flex: none; @@ -169,19 +223,64 @@ align-items: center; gap: 8px; height: 38px; - margin-bottom: 8px; /* + 4px area gap = 12px to the first cell (spec padB12) */ + margin-bottom: 12px; /* former listArea gap 4 + own 8 (spec padB12 to the first cell) */ padding: 0 14px; box-sizing: border-box; border: 1px solid var(--dsw-alias-border-l2); border-radius: 24px; background: var(--dsh-search-input-fill); color: var(--dsw-alias-label-caption); + overflow: hidden; + transition: + height var(--ds-transition-duration-slow) var(--ds-ease-in-out), + padding var(--ds-transition-duration-slow) var(--ds-ease-in-out), + margin var(--ds-transition-duration-slow) var(--ds-ease-in-out), + gap var(--ds-transition-duration-slow) var(--ds-ease-in-out), + border-color var(--ds-transition-duration-slow) var(--ds-ease-in-out), + background-color 200ms var(--ds-ease-in-out); } :global(body[data-ds-dark-theme]) .search { --dsh-search-input-fill: var(--dsw-static-neutral-bluish-900); } +.collapsed .search { + height: 24px; + padding: 0; + margin-bottom: 8px; + gap: 0; + border-color: transparent; + background: transparent; +} + +/* The capsule's leading icon, upgraded to the rail's search control. While + expanded it is decorative: pointer-events off so clicks reach the label + (native input focus); collapsed it becomes the hit target. */ +.searchButton { + flex: none; + display: inline-flex; + align-items: center; + justify-content: center; + width: 24px; + height: 24px; + border: none; + border-radius: 50%; + padding: 0; + background: transparent; + pointer-events: none; + color: inherit; +} + +.collapsed .searchButton { + pointer-events: auto; + cursor: pointer; + color: var(--dsw-alias-label-secondary); +} + +.collapsed .searchButton:hover { + background: var(--dsw-alias-interactive-bg-hover); +} + .searchInput { flex: 1; min-width: 0; @@ -212,6 +311,44 @@ color: var(--dsw-alias-label-secondary); } +/* Tree seat: always mounted so the foot never moves; the tree content inside + is wide-only and clips while the column squeezes. */ +.listArea { + flex: 1; + min-height: 0; + display: flex; + flex-direction: column; + overflow: hidden; +} + +/* Relative for the bottom fade overlay. */ +.treeBody { + flex: 1; + min-height: 0; + display: flex; + flex-direction: column; + position: relative; +} + +/* Bottom fade (figma 133:7666): 72px overlay pinned to the visible bottom, + transparent -> sidebar fill so it tracks the theme. */ +.fade { + position: absolute; + left: 0; + right: 0; + bottom: 0; + height: 72px; + background: linear-gradient(to bottom, transparent, var(--dsw-specific-sidebar-fill)); + pointer-events: none; +} + +/* Batch separator (figma 133:7661): 20px spacer after an expanded project's + session run, before the next project row. */ +.batchGap { + flex: none; + height: 20px; +} + /* Tree list: the only scrolling region. */ .list { flex: 1; @@ -229,20 +366,57 @@ font-size: 13px; } -/* Foot: settings entry (figma 133:7668). */ +/* Foot: settings entry (figma 133:7668). Left padding lands the 14px glyph + on the rail's icon axis when collapsed. */ .foot { flex: none; display: flex; align-items: center; gap: 8px; height: 29px; - margin: 10px 0; + margin: 18px 0 10px; /* former root gap 8 + own 10 above; root padBottom 6 below */ padding: 0 2px 0 6px; border-radius: 12px; cursor: pointer; + overflow: hidden; color: var(--dsw-alias-label-primary); + transition: + padding var(--ds-transition-duration-slow) var(--ds-ease-in-out), + gap var(--ds-transition-duration-slow) var(--ds-ease-in-out); } .foot:hover { background: var(--dsw-alias-interactive-bg-hover); } + +.collapsed .foot { + gap: 0; + padding: 0 0 0 5px; +} + +.footLabel { + max-width: 120px; + overflow: hidden; + white-space: nowrap; + transition: max-width var(--ds-transition-duration-slow) var(--ds-ease-in-out); +} + +.collapsed .footLabel { + max-width: 0; +} + +@media (prefers-reduced-motion: reduce) { + .root, + .wide, + .logoRow, + .iconButton, + .newSession, + .newSessionLabel, + .sectionHeader, + .search, + .foot, + .footLabel { + transition: none; + animation: none; + } +} diff --git a/packages/client/ui-sidebar/src/client/SidebarRoot.tsx b/packages/client/ui-sidebar/src/client/SidebarRoot.tsx index 9badca1b82..a2f730b2d4 100644 --- a/packages/client/ui-sidebar/src/client/SidebarRoot.tsx +++ b/packages/client/ui-sidebar/src/client/SidebarRoot.tsx @@ -1,12 +1,19 @@ /** - * SidebarRoot (figma 133:7629): logo row + collapse, New Session, search, - * WorkSpace section header with the group-by menu, session tree list, - * Settings foot. Pure presentational — the session list arrives through the - * standard useSessions hook, viewing state (expansion, search) is local - * component state, and rows are derived in render via useMemo (slot design - * section 6: derived data is a pure function, no materializing store). + * SidebarRoot (figma 133:7629): logo row + collapse, New Session, WorkSpace + * section header with the group-by menu, search, session tree list, Settings + * foot. Pure presentational — the session list arrives through the standard + * useSessions hook, viewing state (expansion, search) is local component + * state, and rows are derived in render via useMemo (slot design section 6: + * derived data is a pure function, no materializing store). + * + * Collapse is a morph, not a swap: the four control rows persist into the + * 56px rail (collapse/new session/new workspace/search, one icon each, same + * top-down order as their expanded rows) and animate their geometry on the + * deepsuite curve, while wide-only content (brand, labels, input, tree) + * cross-fades out and unmounts once the collapse settles — dropping the + * sessions subscription. Rail search expands and focuses the search box. */ -import { Fragment, useMemo, useState } from 'react' +import { Fragment, useEffect, useMemo, useRef, useState } from 'react' import clsx from 'clsx' import { FishLogo, @@ -19,6 +26,9 @@ import { deriveRows } from './tree.ts' import { ProjectRowItem, SessionRowItem } from './Rows.tsx' import css from './SidebarRoot.module.css' +/** Wide-content unmount delay; matches --ds-transition-duration-slow (0.3s). */ +const COLLAPSE_SETTLE_MS = 300 + const GROUP_BY_ITEMS = [ { id: 'workspace', label: 'WorkSpace' }, // Update/Status grouping has no design yet (figma §3) — visible, disabled. @@ -31,24 +41,48 @@ function toggled(list: readonly string[], key: string): string[] { return list.includes(key) ? list.filter((k) => k !== key) : [...list, key] } -/** - * Render the sidebar column. - * @param props - composed slot props (runtime share + injected callbacks, contract/slots.ts). - * @returns the sidebar element tree. - */ -export function SidebarRoot({ useSessions, onOpen, onCreate, onToggleSidebar }: SidebarRootComponentProps) { +/** Group-by strategy menu; own open state so it resets with the wide chrome. */ +function GroupByMenu() { + const [open, setOpen] = useState(false) + return ( + { setOpen(false) }} + items={GROUP_BY_ITEMS} + selectedId="workspace" + onSelect={() => { setOpen(false) }} + align="end" + anchor={( + + )} + /> + ) +} + +type SessionTreeProps = Pick & { + /** Live search filter owned by the root (the query outlives the tree). */ + query: string +} + +/** The scrolling session tree; unmounting at collapse settle drops the sessions subscription and expansion state. */ +function SessionTree({ useSessions, onOpen, onCreate, query }: SessionTreeProps) { const list = useSessions((s) => s) // Wave-2 seam: row highlight expects `current` on the sessions list // snapshot (sessions.current lives with the runtime sessions service). const current = useSessions((s) => s.current) const [expandedProjects, setExpandedProjects] = useState([]) const [expandedSessions, setExpandedSessions] = useState([]) - const [query, setQuery] = useState('') const rows = useMemo( () => deriveRows(list, { expandedProjects, expandedSessions, query }), [list, expandedProjects, expandedSessions, query], ) - const [menuOpen, setMenuOpen] = useState(false) const now = Date.now() // Presentational lookup (not tree derivation): the group holding the @@ -61,83 +95,7 @@ export function SidebarRoot({ useSessions, onOpen, onCreate, onToggleSidebar }: } return ( -
-
-
- - {/* Wordmark svg not extracted yet (figma 88:8932) — text stands in at the same ink. */} - - deepseek - HARNESS - - -
- - -
- -
-
- WorkSpace - { setMenuOpen(false) }} - items={GROUP_BY_ITEMS} - selectedId="workspace" - onSelect={() => { setMenuOpen(false) }} - align="end" - anchor={( - - )} - /> - -
- - - +
{rows.length === 0 && (
{query === '' ? 'No sessions yet' : 'No matches'}
@@ -167,11 +125,128 @@ export function SidebarRoot({ useSessions, onOpen, onCreate, onToggleSidebar }: ))}
+
+ ) +} + +/** + * Render the sidebar column. + * @param props - composed slot props (runtime share + injected callbacks, contract/slots.ts). + * @returns the sidebar element tree. + */ +export function SidebarRoot({ collapsed, useSessions, onOpen, onCreate, onToggleSidebar }: SidebarRootComponentProps) { + // The query outlives the tree and the input (both wide-only) so collapsing + // does not silently drop an in-progress filter. + const [query, setQuery] = useState('') + const searchInput = useRef(null) + + // Wide content stays mounted while the collapse animates (fading via + // .collapsed .wide), unmounts at settle, and remounts right away on expand. + const [settled, setSettled] = useState(collapsed) + useEffect(() => { + if (!collapsed) { setSettled(false); return } + const timer = window.setTimeout(() => { setSettled(true) }, COLLAPSE_SETTLE_MS) + return () => { window.clearTimeout(timer) } + }, [collapsed]) + const wide = !collapsed || !settled + + // Rail search = expand + land in the search box: the flag arms before the + // expand toggle; once expanded the input is mounted and takes focus. + const [searchOnExpand, setSearchOnExpand] = useState(false) + useEffect(() => { + if (!collapsed && searchOnExpand) { + searchInput.current?.focus() + setSearchOnExpand(false) + } + }, [collapsed, searchOnExpand]) + + return ( +
+
+ {wide && ( + + {/* Wordmark svg not extracted yet (figma 88:8932) — text stands in at the same ink. */} + + deepseek + HARNESS + + )} +
-
+ + +
+ {wide && WorkSpace} + {wide && } + +
+ + {/* Expanded: the row is a click-to-focus field (the leading icon is + decorative). Collapsed: the icon is the rail's search control. */} +
{ if (!collapsed) searchInput.current?.focus() }}> + + {wide && ( + { setQuery(e.target.value) }} + /> + )} + {wide && query !== '' && ( + + )} +
+ + {/* Always-mounted seat: its flex slot pins the foot to the bottom in + both states while the tree itself is wide-only. */} +
+ {wide && } +
+ +
- Settings + {wide && Settings}
) diff --git a/packages/client/ui-sidebar/tests/sidebar-root.spec.tsx b/packages/client/ui-sidebar/tests/sidebar-root.spec.tsx index 6beb07bdc4..08a2769049 100644 --- a/packages/client/ui-sidebar/tests/sidebar-root.spec.tsx +++ b/packages/client/ui-sidebar/tests/sidebar-root.spec.tsx @@ -60,17 +60,24 @@ function mount(...summaries: SessionSummary[]) { const sessions = createSnapshotStore(listStateOf(...summaries)) const onOpen = vi.fn((id: SessionId) => { sessions.update((d) => { d.current = id }) }) const onCreate = vi.fn() - const onToggleSidebar = vi.fn() - const utils = render( + // The owner decides collapsed in production (AppFrame maps the preference); + // the harness mirrors that loop so the toggle drives a re-render. + let collapsed = false + const view = (width: number) => ( , + /> ) + const onToggleSidebar = vi.fn(() => { + collapsed = !collapsed + utils.rerender(view(collapsed ? 56 : 300)) + }) + const utils = render(view(300)) return { sessions, onOpen, onCreate, onToggleSidebar, ...utils } } @@ -151,10 +158,81 @@ describe('SidebarRoot', () => { expect(onCreate).toHaveBeenLastCalledWith('/proj') }) - it('collapse button and group-by menu behave', () => { + it('collapse fades the wide content out, then the rail keeps the four controls', () => { + vi.useFakeTimers() + try { + const { onToggleSidebar, onCreate } = mount(...projectData()) + act(() => { fireEvent.click(screen.getByLabelText('Collapse sidebar')) }) + expect(onToggleSidebar).toHaveBeenCalledOnce() + // Fade window: the wide chrome is still mounted while it fades. + expect(screen.getByText('HARNESS')).toBeTruthy() + expect(screen.getByRole('tree')).toBeTruthy() + // Settle: wide content unmounts, the rail controls remain. + act(() => { vi.advanceTimersByTime(300) }) + expect(screen.queryByText('HARNESS')).toBeNull() + expect(screen.queryByText('New Session')).toBeNull() + expect(screen.queryByRole('tree')).toBeNull() + // Rail order mirrors the expanded rows: expand, new session, new workspace, search. + const rail = ['Expand sidebar', 'New session', 'New workspace', 'Search sessions', 'Settings'] + .map((label) => screen.getByLabelText(label)) + for (let i = 1; i < rail.length; i++) { + expect(rail[i - 1]!.compareDocumentPosition(rail[i]!) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy() + } + // Rail creation entries route like their expanded counterparts. + act(() => { fireEvent.click(screen.getByLabelText('New session')) }) + expect(onCreate).toHaveBeenLastCalledWith() + act(() => { fireEvent.click(screen.getByLabelText('Expand sidebar')) }) + expect(onToggleSidebar).toHaveBeenCalledTimes(2) + expect(screen.getByLabelText('Collapse sidebar')).toBeTruthy() + expect(screen.getByText('New Session')).toBeTruthy() + } finally { + vi.useRealTimers() + } + }) + + it('rail search expands the sidebar and focuses the search box', () => { + vi.useFakeTimers() + try { + const { onToggleSidebar } = mount(...projectData()) + act(() => { fireEvent.click(screen.getByLabelText('Collapse sidebar')) }) + act(() => { vi.advanceTimersByTime(300) }) + act(() => { fireEvent.click(screen.getByLabelText('Search sessions')) }) + expect(onToggleSidebar).toHaveBeenCalledTimes(2) + const input = screen.getByPlaceholderText('Search name, keywords...') + expect(document.activeElement).toBe(input) + } finally { + vi.useRealTimers() + } + }) + + it('expanded search focuses without toggling the sidebar', () => { const { onToggleSidebar } = mount(...projectData()) - act(() => { fireEvent.click(screen.getByLabelText('Collapse sidebar')) }) - expect(onToggleSidebar).toHaveBeenCalledOnce() + const input = screen.getByPlaceholderText('Search name, keywords...') + act(() => { fireEvent.click(screen.getByLabelText('Search sessions')) }) + expect(document.activeElement).toBe(input) + expect(onToggleSidebar).not.toHaveBeenCalled() + }) + + it('the search query survives a collapse/expand round trip', () => { + vi.useFakeTimers() + try { + mount(...projectData()) + const input = screen.getByPlaceholderText('Search name, keywords...') + act(() => { fireEvent.change(input, { target: { value: 'forked' } }) }) + act(() => { fireEvent.click(screen.getByLabelText('Collapse sidebar')) }) + act(() => { vi.advanceTimersByTime(300) }) + act(() => { fireEvent.click(screen.getByLabelText('Expand sidebar')) }) + const restored = screen.getByPlaceholderText('Search name, keywords...') as HTMLInputElement + expect(restored.value).toBe('forked') + expect(screen.getByText('forked child')).toBeTruthy() + expect(screen.queryByText('elsewhere')).toBeNull() + } finally { + vi.useRealTimers() + } + }) + + it('group-by menu behaves', () => { + mount(...projectData()) expect(screen.queryByText('Update')).toBeNull() act(() => { fireEvent.click(screen.getByLabelText('Group by')) }) expect(screen.getByText('Update')).toBeTruthy() diff --git a/packages/client/ui-theme/src/styles/base.css b/packages/client/ui-theme/src/styles/base.css index 7fa58107d2..2d1acde71d 100644 --- a/packages/client/ui-theme/src/styles/base.css +++ b/packages/client/ui-theme/src/styles/base.css @@ -1,10 +1,13 @@ -/* Base font-family variables referenced by the token sheets but defined +/* Base variables referenced by the token sheets and component CSS but defined * upstream (deepsuite theme/global.css) — supplied here so the composite - * --dsw-font-* variables resolve. Code stack deliberately omits a bare - * `monospace` tail (Windows CJK falls back to SimSun otherwise). */ + * --dsw-font-* variables resolve and motion rides the upstream curve. Code + * font stack deliberately omits a bare `monospace` tail (Windows CJK falls + * back to SimSun otherwise). */ :root { --dsw-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif; --ds-font-family-code: 'SF Mono', 'JetBrains Mono', 'Fira Code', Consolas, 'Liberation Mono', Menlo, Courier, 'PingFang SC', 'Microsoft YaHei'; + --ds-ease-in-out: cubic-bezier(0.4, 0, 0.2, 1); + --ds-transition-duration-slow: 0.3s; }