@veewo/dsh-better-tasks 0.0.0-stage → 0.4.4

package/docs/rollback.md

@@ -0,0 +1,78 @@
+# 卸载 / 回滚 Better Tasks
+
+## rc.3 / Tasks 0.4.4 回滚
+
+[rc.3 候选](<install-rc3.md>)必须整体保留主包与六个 rc.3 fork。安装失败时保持 Desktop 退出，恢复安装前 Profile 配置与同一运行时的完整七包；仅把主包降到 rc.2 的 0.4.1 不是合法回滚。若要退回 rc.2，须先恢复相应官方运行时，再恢复原 rc.2 / Tasks 0.4.1 七包，不能跨线混用。以下移除插件与六个 fork 的通用步骤同样适用；不删除任何 Session/Pin/排序/设置数据。
+
+## 当前公开组合：DSH 0.2.2-rc.2 / Tasks 0.4.1
+
+所有操作先完成正在运行的任务，**手动完全退出 Desktop（含托盘）**，确认旧进程退出，再修改 Profile。不要热替换正在运行的客户端模块。这里不要求删除会话或用户数据。
+
+### 恢复官方侧栏
+
+使用与该 Desktop 同版本的 DSH CLI，先移除插件，再移除六个 fork 根依赖：
+
+```powershell
+$names = @('@veewo/dsh-better-tasks')
+$names += 'layout','workspace','user-questions','input-trigger','commands','conversation' |
+    ForEach-Object { "@deepseek-ai/dsh-client-ui-$_" }
+foreach ($name in $names) {
+    dsh plugin --profile desktop remove $name
+    if ($LASTEXITCODE -ne 0) { throw "移除失败：$name；先恢复安装前备份，不要继续启动" }
+}
+```
+
+插件 bundle 的可移除 patch 层禁用官方 `ui-layout`、`ui-sidebar`、`ui-workspace`、`ui-user-questions`、`ui-input-trigger`、`ui-commands`、`ui-conversation`，插入六个替换行及 `better-tasks-ui`。移除插件应同时移除该 bundle 层；**六个 fork 依赖也必须移除**，否则原生包名仍可能解析到 fork，而非官方模块。
+
+若以前手工复制过禁用行，只移除属于 Better Tasks 的那部分，保留其他插件配置。核对 Profile 里无残留 Better Tasks bundle/替换行后，再手动启动并验收官方侧栏和主输入框。需要时恢复安装前的 linker 配置；不要为了回滚而覆盖后来无关的插件改动。
+
+本次 conversation 字节与旧版不同；回退需恢复主包及旧 conversation。旧 [0.4.0 七包](<https://github.com/chanyuenpang/dsh-better-tasks/releases/tag/dsh-v0.2.2-rc.2-tasks-v0.4.0>)保持不变。
+
+### 安装失败或切回上一版 Tasks
+
+使用安装前保存在自己机器的配置备份：`package.json`、`pnpm-lock.yaml`、`pnpm-workspace.yaml`、`cordis.yml`、`cordis.patch.yml`，连同当时完整七包恢复原组合。不要保留“新版 manifest + 旧 lock + 混线 fork”的组合；手动核对实际绝对 Profile 路径后，仅清理其中可重建的 `node_modules`，再运行 `dsh plugin --profile desktop install`。若缺旧包或恢复失败，保持 Desktop 停止并报告错误，不用 `--force` 绕过检查。
+
+旧版组合 tag 不移动，便于按原 DSH 版本重新下载安装。回退 Tasks 不等于回退 DSH：旧包仍须与当前 DSH 完整运行时版本匹配。升级/回退步骤见[固定版本安装说明](<https://github.com/chanyuenpang/dsh-better-tasks/blob/dsh-v0.2.2-rc.2-tasks-v0.4.1/docs/install.md>)。
+
+**不要删除** Session、Workspace、原生 Pin、Goal/Todo、ledger、Tasks 排序、`better-tasks-ui` 设置或浏览器展开状态键。Profile 配置备份也可能含敏感信息，只留本机，勿附到 GitHub issue。
+
+---
+
+以下是历史旧版恢复记录，**不是当前安装/卸载步骤**。
+
+## Historical 0.1.5 Web composition (not the 0.3 install recipe)
+
+The real profile patch is `${DSH_HOME:-$HOME/.dsh}\profiles\web\cordis.patch.yml`.
+
+## Restore all shipped UI packages
+
+1. Remove the block between `# BEGIN dsh-better-tasks exact-fork sidebar replacement` and `# END dsh-better-tasks exact-fork sidebar replacement`.
+2. Restart `dsh web`.
+3. Refresh the Web page with the new token URL.
+
+Removing that block re-enables the shipped `ui-layout`, `ui-sidebar`, `ui-workspace`, and `ui-user-questions` rows and removes exactly these local rows:
+
+- `ui-layout-dbt`
+- `better-tasks-sidebar`
+- `ui-workspace-dbt`
+- `ui-user-questions-dbt`
+
+## Backups
+
+- Before the original sidebar replacement: `${DSH_HOME:-$HOME/.dsh}\profiles\web\cordis.patch.yml.before-better-tasks`
+- Before the Workspace fork: `${DSH_HOME:-$HOME/.dsh}\profiles\web\cordis.patch.yml.before-ui-workspace-fork`
+- Before the layout fork: `${DSH_HOME:-$HOME/.dsh}\profiles\web\cordis.patch.yml.before-ui-layout-fork`
+- Before the final three-fork install: `${DSH_HOME:-$HOME/.dsh}\profiles\web\cordis.patch.yml.before-better-tasks-final`
+- Before switching from development paths to packaged plugins: `${DSH_HOME:-$HOME/.dsh}\profiles\web\cordis.patch.yml.before-dbt-package-0.2.0`
+- Before the abandoned live scoped-identity migration: `${DSH_HOME:-$HOME/.dsh}\profiles\web\cordis.patch.yml.before-dbt-0.2.1`
+- Before the Workspace-only pinned-title rollout: `${DSH_HOME:-$HOME/.dsh}\profiles\web\package.json.before-dbt-pin-emoji` and `pnpm-lock.yaml.before-dbt-pin-emoji`
+
+The real `0.2.1` pinned-title rollout intentionally keeps the stable unscoped `dsh-better-tasks@0.2.0` main package and composition row, and updates only the immutable Workspace fork from the `0.2.1` release directory. Roll it back by installing the Workspace tgz from the `0.2.0` release directory, then perform an approved clean restart. Do not live-switch the main Client package identity between `dsh-better-tasks` and `@veewo/dsh-better-tasks`: the old locale fiber can overlap the new package during live reload.
+
+Rollback does not delete Session, Workspace, Goal, Todo, cost-meter, project-appearance, Host pin-queue data, or the `better-tasks-ui` Host settings namespace. The browser-only keys `dsh-better-tasks.projection-expansion.v1`, `dsh-better-tasks.projection-expansion.v2`, `dsh-better-tasks.goal-auto-open-cycle.v1`, `dsh-better-tasks.final-auto-open-cycle.v1`, `dsh-better-tasks.final-message-cache.v1`, and `dsh-better-tasks.layout.sidebar-width.v1` may remain safely; shipped packages do not consume them.
+
+## Roll back a scoped main-package identity switch
+
+Do **not** restore an unscoped patch while a scoped Better Tasks Client is still running (or vice versa). Preserve the complete previous `profiles/web` directory and its immutable unscoped main tgz as the rollback source; Session, Workspace, Goal, Pin, settings and ledger storage stay outside that Profile and must not be removed.
+
+After an explicitly authorized stop, and only once the old Host and its target child processes have exited, restore the previous Profile directory as a unit (package manifest, lock, workspace patch configuration, client patch and installed dependencies). Moving a pnpm hoisted Profile changes its absolute `node_modules/.modules.yaml` virtual-store path: set `$env:CI = "true"` and the correct `$env:DSH_HOME`, then run `pnpm install --offline --frozen-lockfile` with the restored `profiles/web` as the working directory before starting it. Verify the original `dsh.profile.bundles` order, the unscoped main and three unchanged forks, and the absence of the scoped main. Using `dsh plugin --profile web install` here can reorder the bundle list. If this fails, leave DSH stopped and report the exact recovery status; do not trigger a live identity reload or an unapproved second restart.

package/docs/sidebar-layout.md

@@ -0,0 +1,72 @@
+# 侧栏排版与 DSH 适配规范
+
+范围：Better Tasks 的导航外壳；不重设计任务卡、原生 Session Pin、任务排序或插件页面。接点基线为 DSH `0.2.2-rc.2`，Tasks 0.4.2 增补 rc.3 的新会话行 HOC；运行时支持以精确组合的验证证据为准，**不据此宣称未来版本已兼容**。
+
+## 1. 固定层级
+
+从上到下：品牌/收起控制 → 原生样式新会话 → 紧凑全局入口栏 → 会话/任务切换与内容 → 官方页脚/设置。主内容保持 `flex:1; min-height:0`；原生会话容器采用列布局横向撑满。宽度与展开状态仍由 DSH Layout 唯一管理，不另存第二个宽度。
+
+新会话保留原生图标、elevated 填充、边框与圆角、label-mask/content/shortcut 结构、权限和快捷键提示，继续调用 Workspace 的共享动作。不能换回品牌色大按钮、Unicode 加号或另造会话创建流程。
+
+## 2. 三层样式事实
+
+| 层 | 唯一来源 | 维护方式 |
+|---|---|---|
+| 本地数字 | [SIDEBAR_LAYOUT](<../src/client.js>) | JS 参数与局部 CSS 变量从同一对象生成，不在按钮旁各写一套尺寸 |
+| 语义样式 | DSH 的 `--dsw-*` tokens | 背景、文字、边框、圆角、焦点与 macOS glass 沿用原生语义，不复制当前主题颜色值 |
+| 版本合同 | 本页接点表、目标 tag 源码与[升级流程](<upgrading-dsh-version.md>) | 升级只复核发生变化的接口与原生样式，不按版本号复制整页 UI |
+
+当前数字如下；运行时以 SIDEBAR_LAYOUT 为准，调整时先改数字源，再同步本表，不在各组件另写覆盖值：
+
+| 项 | 基线 |
+|---|---:|
+| 原生新会话高度 / 字号 / 行高 | 38 / 14 / 22 px |
+| 展开导航点击盒 / 窄 rail 点击盒 | 34 / 36 px |
+| 常规导航图标 / 取消固定点击盒 | 18 / 18 px |
+| 入口间距 / 展开栏最大行数 | 4 px / 2 行 |
+| Tooltip 延时 | 500 ms |
+
+38/14/22 来自 rc.2 原生新会话；平台标题栏的 28px 控制、14/16px 原生图标等特例服从对应上游合同，不强行套常规入口规格。新功能应优先使用现有角色，不随意增加字号、圆角或硬编码像素例外。
+
+任务卡默认以任务名为主（现有 task 强调模式的主字号/字重/主色），项目名为次；Host 和客户端默认均为 task。缺少该字段的旧配置使用新默认，明确保存过 project 的用户选择不覆盖；设置仍可切换两种强调方式。
+
+## 3. 更多按钮与窄宽度
+
+入口按活动注册表的 order、同序注册顺序显示，不写“插件/自动化任务”的按钮白名单。每个入口使用注册的官方图标、名称 Tooltip、可访问名称与选中态；插件提供新入口时无需编辑侧栏数组。
+
+展开栏横向换行，超过两行后**导航区独立纵向滚动**。窄 rail 最多占侧栏高度的 30%，同样保留滚动。Windows 零宽收起仍沿用原生标题栏展开路径。所有入口和末尾“更多”保留在 DOM/键盘顺序中；不因空间不足删除按钮、自动取消固定或把溢出项假冒成未固定项。Tooltip/Menu 使用 portal，不被导航滚动裁剪。
+
+“更多”保留官方菜单行；原生 rc.2 菜单只列未固定入口，所以固定项旁必须保留 hover/focus 可达的取消固定图标。取消固定前先把焦点交给“更多”，防止被移除的按钮吞掉焦点。Plugins 固定项遵循官方不可取消固定规则。
+
+## 4. 状态边界与失败语义
+
+- 注册表拥有入口 id/order/label/icon；Layout 拥有当前主面板和宽度；Workspace 拥有新会话动作。
+- 唯一替代 sidebar shell 拥有短生命周期的入口 unpinned 集合，行为与上游一致；不新增 Host、Config 或 localStorage 持久化。它与 Session Pin、Host 任务顺序完全独立。
+- 官方 entry-customization 拥有菜单行；shell 只提供 anchor、开关及回调。菜单打开某入口不等于重新固定。
+- actions provider 消失：显示全部注册入口，撤掉“更多”和取消固定；保留内存选择，provider 返回后恢复。不能隐藏后让入口永久不可达。
+- 插件卸载/重挂：旧 id 的选择保留；动作拒绝已经卸载的 id。无快捷键条目时只省略提示，不编造快捷键。
+- 旧 renderer 无 factory 时只能使用已核实的旧图标 slot 合同。`registerFactory` 存在只是结构探测，不是新 DSH named factory/授权/props 兼容证明；未知关键合同须标记适配未通过，不能吞错后宣称成功。
+
+## 5. 每个新 DSH 版本必须复核的接点
+
+| 接点 | 合同 |
+|---|---|
+| `sidebar.panel.icon` factory | `{id,size,active}`；factory 独占 `sidebar.panellist` 子座位，root 不重复声明 |
+| `sidebar.panellist.actions` | root 拥有 list；传 `entries/onOpen/onPinnedChange/onDismiss`；entry 含 `id/label/pinned/active` |
+| 官方菜单 | 核实未固定项过滤、pin/open/dismiss、插件发现/创建动作和图标 factory；不要自绘另一份菜单数据 |
+| 新会话 | `session/create` 权限、`session.new` 快捷键、Workspace `startSession`、原生 DOM/CSS tokens |
+| rc.3 新会话行 HOC | 替代 root 声明 `sidebar.session.action` 为 root/hoc；owner `{wide}`，原生按钮经第三参 `{children}` 透传；无 occupant 保留按钮，拒绝权限不调用 HOC；可选动作是按钮的兄弟，不加导入服务硬依赖 |
+| Primitives | Tooltip、Menu、ShortcutKeys、原生新会话/更多/Pin 图标、焦点转移方法 |
+| Renderer | entry/factory 子座位授权与销毁后的 stale 检查 |
+
+核对目标 tag 的 ui-sidebar、ui-entry-customization、ui-renderer 和 ui-primitives。动态接口改名、owner/props/权限/动作变化属于适配工作；只改外观数字不能掩盖合同漂移。
+
+## 6. 最小验证与交付
+
+[导航回归](<../test/sidebar-navigation.test.mjs>)覆盖动态入口、provider 失去/恢复、取消固定焦点、权限和数字源；[原生离线合同](<../test/sidebar-native-menu-contract.test.mjs>)执行固定版本的真实菜单与 renderer 授权片段；[fixture 来源](<../test/fixtures/sidebar-rc2/provenance.json>)记录目标与摘要。Primitives 在离线测试中是传输替身，**不是完整浏览器或外观验收**。
+
+[升级检查器](<../scripts/check-upstream-contract.mjs>)包含带引号 child key 的回归；其 `attachable` 只覆盖所声明的扫描范围，不能代替上表的 named factory、菜单 props、token 人工复核。适配新线时按目标源码更新/复核 fixture，并记录结果，不能沿用 rc.2 绿色结果冒充新线通过。
+
+全部约定改动完成后统一构建、语法、必要单元/合同回归。安装另须同一精确组合隔离冷启动，仅确认监听与核心激活/启动错误，禁 Cindy，并清理所有沙盒进程。功能与外观由用户验收；不自动做 CSS/几何/像素测量、截图或真机重启。
+
+相邻但独立的任务顺序规则：Host 顺序补充元数据保留任务加入时间，并用原生 listEvents 的首次工作事件元数据补正预先准备的空白会话；不是只看 Header.createdAt，也不是最后活动时间。客户端在已 Pin 空白会话首次变为非空时刷新顺序，即使 Pin 成员没有变化。首次工作时间正值持久化缓存，后续消息不刷新；继承父日志的 fork 继续使用自身 Header 创建时间。手动顺序记录手动应用时间，较晚的显式拖拽优先于迟到的出生元数据；入口排版不读写这些状态。

package/docs/task-session-activity.md

@@ -0,0 +1,13 @@
+# 会话活跃状态与选中标题（Tasks 0.4.4；本地先行候选 0.4.3）
+
+- 任务卡按原生 `useSessionStatus` 的实时 `running`（显式 `false` 优先于旧目录行）及 Session 列表基线计算状态。
+- 使用原生 `projectionsBySession[id].values.subagentCatalog` 的直接子关系向上汇总，已知孙级运行也保持祖先卡片为 running。兼容旧的 summary projectionValues；不把 fork 的 parentSession 当作子 agent 关系。
+- 子 agent 无需成为任务、无需出现在主 Session 列表；只有实时状态和原生目录关系即可计入。停止最后一个运行中的后代后恢复 idle。目录成员存在本身不表示正在工作，历史未闭合 turn 也不是实时运行凭据。
+- 卡片颜色、StateDot、无障碍状态、idle-only Final/输入显示及中断警告共享汇总结果。主会话待交互继续优先于 running；断线仍表示状态未知，不伪装为停止成功。
+- 当前选中的任务会话标题使用官方 `--dsw-alias-brand-primary`，覆盖两种标题强调模式与 hover。非选中标题、项目名及卡片状态色不变。主题变量跟随明暗主题，不固定 RGB。
+
+实现：[状态模型](<../src/task-model.mjs>)、[任务卡](<../src/client.js>)；回归：[会话树状态与标题合同](<../test/task-session-tree-status.test.mjs>)。
+
+这是原生已知状态的只读派生，不引入第二个执行状态所有者，不轮询、保活或唤醒子会话；缺少原生目录能力时保留主 agent 的原生状态回退。未加载/未知的远程后代不作运行推断。原生会话列表本就显示直接子 agent 的运行指示，本次不替换其业务逻辑或重建六个 fork。
+
+构建、包审计和隔离启动记录随本地候选保存；离线测试不是功能或外观验收。用户验收前不声称视觉通过，也不自动重启真实 Desktop。