dsh-file-activity 0.5.9 → 0.5.10

package/CHANGELOG.md

@@ -2,214 +2,20 @@
 
 本文件记录 dsh-file-activity 的所有版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
-## [0.5.9] - 2026-09-13
-
-### 变更
-
-- chore: 项目全面优化和完善
-- fix(dsh-file-activity): #266 侧边栏席位按宿主空 props 契约加载，面板打开即刷新 + 补 guide 菜单入口 (#268)
-- chore(release): #198 dsh-shared 0.1.4 + 消费方 peerDeps 同步 + 文档收口 (#254)
-- refactor(file-activity): #187 批 2 迁移到宿主原生侧边栏 API（移除 better-sidebar，含实测证据） (#249)
-- #184 依赖升级：矩阵脚本 + A 档落地 + jscpd 解锁 + dependabot 覆盖插件目录 (#235)
-- perf(scripts): #188 优化 pre-push 校验耗时（并发 6 + 收窄退化 + 补 D + file-activity 测试提速） (#234)
-- fix(dsh-file-activity): #197 写放大 3665× 与状态无界 (#207)
-- fix(release): 批量提交信息 header 控制在 commitlint 限制内
-- feat(ts): 第四轮 JS→TS 迁移（5 个插件，server + client 全量）
-
-## [Unreleased]
-
-### 修复
-
-- fix(dsh-file-activity): #266 侧边栏「文件活动」面板打开后永远显示「暂无文件活动记录」（P0）——
-  宿主渲染 `sidebar.right.pane.tab` 席位时 owner props 是**空对象**
-  （`renderSlot(seat, {}, {hookContext})`），可见性只在注入的 `useTabInfo()` 里；
-  旧守卫只读 `props.visible`（恒为 `undefined`）→ 守卫恒真 → 面板打开后既不首载也不轮询
-  （`POLL_MS` 失效），只有手点「刷新」才有数据。现按宿主真实契约取
-  `useTabInfo().tab.visible`（取不到时退回可见：宁可多轮询一个面板，也不能空白），
-  切回页签/展开侧边栏立即重新加载并重启轮询，宿主判定不可见时不轮询（省资源）。
-  同一 issue 的关联项：
-  - B：「新标签页」菜单补 guide 入口（`sidebarRightTabs.register({guide:[…]})`）——此前页签关闭后
-    无法从 UI 重新打开（auto-open 每浏览器标签只跑一次）；
-  - C：HTML 预览按 README 承诺落地为**沙箱 iframe**（此前 `viewerOf()` 无 html 分支，
-    `.html` 落到文本渲染器、显示为代码块 `.dfa-fp-code`）：iframe
-    `sandbox="allow-scripts allow-forms"` + 媒体路由响应头
-    `Content-Security-Policy: sandbox allow-scripts allow-forms`（两层都不含
-    `allow-same-origin`，直接打开该 URL 同样受限）；
-  - D：删除客户端挂载探针（此前每次页面加载都往状态文件写一条
-    `sessionId="__probe__", path="mounted"` 的幽灵记录，累计 9 行、重启后仍在），
-    并在加载时剔除历史残留（#197「状态有界」）。
-- fix(dsh-file-activity): #197 写放大 3,665× 与状态无界（P0）——
-  落盘改为 JSON Lines 增量 append（落盘字节 ≈ 事件本体字节）+ 按状态体积自适应的原子 compact；
-  新增三维入口上限（会话/每会话路径/全局路径）与 LRU 淘汰（淘汰计数 + warn 可见，非静默丢弃）；
-  compact 快照显式传 `minIntervalMs`/`maxBytes` 护栏；旧全量 JSON 快照自动兼容并改写。
-  实测：单条新事件落盘 789,780 B → 68 B（11,614×↓）；稳态每事件 2,104 B → 63 B（33×↓）；
-  密集流投影 44.18 MB/小时 → 1.94 MB/小时（22.8×↓）；内存条目与状态文件均有界。
-  本插件并入 `scripts/resource-smoke.mjs` 写放大门禁（此前仅覆盖 observability）。
-
-## [0.5.8] - 2026-09-10
-
-### 变更
-
-- feat(ts): 第四轮 JS→TS 迁移（5 个插件，server + client 全量）
-
-## [0.5.7] - 2026-09-07
-
-### 变更
-
-- fix(deps): update package-lock.json to fix CI/CD failures
-- feat(observability): #155 插件状态查询聚合——统一 status-query 事件 + /plugin-status API (#170)
-- chore(plugins): #165 清理失效的 dsh.client.inject 声明（13 插件） (#167)
-
-## [0.5.6] - 2026-09-04
-
-### 变更
-
-- chore(release): dsh-file-activity v0.5.6（#111 浮窗预览 + 验证清单）
-- fix(file-activity): #111 HTML 预览内容撑满浮窗 (#116)
-- docs: #106 安装命令统一加 --trust-lockfile (#113)
-
-## [0.5.5] - 2026-09-02
-
-### 变更
-
-- fix(scripts): #72 插件依赖未随安装自动安装（dsh-shared 未发布 npm） (#96)
-- fix(file-activity): 浮窗预览失焦自动关闭（issue #76） (#95)
-- fix(file-activity): #72 补充 dsh-better-sidebar 级联安装——dependencies 声明 + 缺失提示
-- style: prettier 全量格式修复（CI 格式门禁）
-
-## [Unreleased]
-
-### 变更
-
-- fix(ui): 浮窗预览失焦自动关闭——点击外部任意处/切换页签即关，预览失败 2.5s 自动关闭或点击任意处关闭，头部「点击外部关闭」提示（issue #76）
-
-## [0.5.4] - 2026-09-01
-
-### 变更
-
-- fix(file-activity): 浮窗预览优雅降级与工作区外文本读取（issue #68）
-
-## [0.5.3] - 2026-09-01
-
-### 变更
-
-- fix(ui): 9 个插件未定义 token danger-primary 改用 error-primary（DSH 主题仅定义 business/error/success/warn）
-
-## [0.5.2] - 2026-08-31
-
-### 变更
-
-- fix(ui): dsh-file-activity 移除页签选中态品牌蓝覆盖，回归宿主默认样式（issue #60）
-- feat(ui): dsh-mermaid-render 卡片翻新——图标/前缀/状态（issue #54）
-- feat(ui): dsh-my-guard 安全护栏面板翻新——图标/前缀/状态/交互（issue #54）
-- feat(ui): 共享图标系统 + UI 规范文档（issue #54 阶段0）
-- refactor(shared): 抽取 dsh-shared 共享工具包，10 个插件迁移消除重复实现（issue #45）
-- chore(deps): 升级 react 19 兼容性——13 个插件 peer 声明 ^18.2.0 || ^19.2.0（issue #49）
-- style(format): 全仓 prettier 格式化（issue #44）
-
-## [0.5.1] - 2026-08-27
-
-### 变更
-
-- feat(file-activity): 侧边栏页签选中态改用品牌蓝，三态一眼可分（issue #25）
-- feat(file-activity): 文件活动列表按文件类型显示专属彩色图标（issue #24）
-
-## [0.5.0] - 2026-08-26
-
-### 变更
-
-- feat(file-activity): bash 命令文件操作识别（rm/touch/mv/cp/tee/重定向）+ 0 值计数徽标过滤
-- docs+test: 全面审查修复——文档同步补全 + mermaid 测试增强
-
-## [0.4.7] - 2026-08-25
-
-### 变更
-
-- **npm 页面元数据优化**：description 改为中英双语（中文在前）；README 效果截图引用改为绝对 URL（unpkg），npm 包页面可直接显示图片。
-
-## [0.4.6] - 2026-08-25
-
-### 变更
-
-- **Server 端按 P2 模块拆分**：`lib/index.js`（434 行）按职责拆分为 fence/state/store/observer/api-route/media-route 子模块（入口 50 行），覆盖率/变异统计范围同步扩展至全部 server 文件（Stryker 变异 90.91% ≥ 70%）。
-- **Client 端方案 B 拆分**：`client.src.js` 模板 + 13 个片段（`lib/parts/`）经 `scripts/build.mjs` 拼接生成 `client.js`；eslint 尺寸规则覆盖 src/parts 源码、构建产物排除。
-- **client-render 测试零依赖化**：不再硬编码本机 react 绝对路径，改为自写 createElement stub（CI 跨平台可跑）。
-- 行为不变（纯重构）。
-
-## [0.4.5] - 2026-08-24
-
-### 修复
-
-- **状态文件 `sessions` 为 `null` 时崩溃**：`loadState` 只检查 `typeof sessions !== 'object'`，而 `typeof null === 'object'`——手改/损坏的状态文件若把 `sessions` 写成 `null`，加载后 `Object.values(null)` 抛 TypeError（unhandled rejection）。现在显式把 `null` 一并重置为空对象，降级为全新状态不崩溃（复现测试 `host-mutation.mjs` 已永久保留）。
-
-### 变更
-
-- **质量门禁测试体系接入**：测试框架迁移至 Vitest（node:test → vitest，API 兼容）；覆盖率门禁 `lines≥85 / branches≥75 / functions≥80`（当前实测 99.1/91.8/97.5）；新增边界测试 `host-edge.mjs`（12 用例）与变异定向测试 `host-mutation.mjs`（49 用例）；Stryker 变异测试达标（71.76% ≥ 70%）；Gherkin 验收测试 11 场景/56 步骤（`test/features/`）随 `npm test` 运行。
-
-## [0.4.4] - 2026-08-24
-
-### 修复
-
-- **工作区外文件的图片/PDF 预览不再破图**：浮动预览的媒体字节此前走侧边栏的 `/sidebar/file` 路由，而该路由只允许会话工作区（cwd）内的文件——agent 实际触碰过的 `/tmp` 临时文件等工作区外路径点击预览时一律 403，图片显示为破图、PDF 加载失败。现在媒体字节改由插件自身的 `/file-activity/file` 路由提供（**只放行该会话记录过的路径**：未记录 403、文件不存在 404、超 64MB 拒绝；fence 信任校验与侧边栏一致），图片在浮窗内正常渲染；PDF 因侧边栏内置查看器写死媒体路由，浮窗改用浏览器原生 PDF 帧 + 下载兜底。
-- Markdown / 代码 / HTML 文本预览不受影响（侧边栏 `fs.read` 本身不限制工作区，`client-render.mjs` + 真实浏览器实测回归通过）。
-
-## [0.4.3] - 2026-08-23
-
-### 变更
-
-- **README 补充现场效果图**：顶部新增真实现场效果图（侧边栏「文件活动」页签 最近访问/文件统计树 + 点击文件的浮窗预览），便于其他用户下载前了解功能。
-- **发布包包含效果图**：`package.json` 的 `files` 加入 `assets/`，使 GitHub Release 的 tarball 一并包含效果图资源。
-
-## [0.4.2] - 2026-08-23
-
-### 修复
-
-- **修复页签偶发"纯文字无样式"**：样式注入曾放在 `betterSidebar` 服务判空早退之后，HMR 重建/服务重载瞬间新实例可能跳过注入，导致已渲染的页签失去全部 CSS（纯白文本列表）。样式注入改为 `apply` 无条件最先执行（纯静态 CSS，不依赖任何服务），每个 fiber 持有自己的 `<style>` 元素，重建后至少保留一份。
-
-## [0.4.1] - 2026-08-23
-
-### 修复
-
-- **会话切换不再残留上个会话的文件活动**：前端数据 store 改为按 `sessionId` 分桶（`bySession`），每个会话只渲染自己的数据桶——新建/切换会话瞬间立即显示该会话自己的记录（新会话直接为空），不再在 fetch 完成前显示上一个会话的残留数据；fetch 失败时也不再保留旧数据。切换会话时同时关闭上一个会话遗留的浮窗预览。
-
-## [0.4.0] - 2026-08-22
-
-### 变更
-
-- **预览改为浮窗预览（复用侧边栏内置渲染）**：点击任意文件（最近访问 / 文件统计）弹出**悬浮预览窗**，窗口内容通过 `ctx.betterSidebar.matchFileViewer(path)` 复用侧边栏**内置的 file viewer** 渲染（代码语法高亮 / Markdown 富文本 / 图片 / PDF / HTML），并按 viewer 的 `fetchStrategy` 取内容（`fsRead` / `mediaUrl` / `custom`）；不再打开侧边栏编辑器标签，也不自建预览组件。浮窗为轻量交互：**点击浮窗外任意处 / `Esc` 键关闭**，标题栏右上保留一个 `×` 关闭按钮；主体为可滚动区域，长文件或大图在窗内滚动查看。
-- **UI 全面改版**（遵循 better-sidebar 设计语言）：全部改用 DSH 语义 token（`--dsw-alias-*` 颜色、`--dsw-font-*` 字形、`--ds-*` 动效），flat 无阴影、hairline 细边、8px 圆角行 + hover 底色；样式表随 activation 注入、fiber teardown 卸载（HMR/禁用无残留）。
-- **间距收紧 + 去冗余标题**：整体走 better-sidebar explorer 的紧凑规范（`2px 6px 8px` 容器、30px 行、box-sizing 缩进），移除内容区顶部的「文件活动」标题（tab 条已命名本页），刷新/清空改为右上角细颗粒图标按钮，内容紧贴 tab 条（更沉浸）。
-- **文件夹 / 文件图标可区分**：目录行用**品牌强调色**的文件夹图标 + 折叠箭头 + **加粗**名字，文件行用**中性淡色**的文件图标 + 常规名字，彩色文件夹 vs 素色文档，一眼可辨。
-- **最近访问只显示文件名**：不再展示完整绝对路径，只显示最后的文件名（悬停仍可见完整路径），减少视觉噪音。
-- 操作类型用状态色徽标（新增 = success / 修改 = warn / 读取 = 品牌强调色），文件统计目录树与文件行改为彩色计数胶囊；文件/文件夹行加入图标与折叠箭头。
-- 时间显示从 `HH:MM:SS` 改为**相对时间**（刚刚 / N 分钟前 / N 小时前 / N 天前 / MM/DD），悬停仍可查看完整时钟时间。
-
-## [0.3.0] - 2026-08-22
-
-### 变更
-
-- 最近访问列表改为 **LRU**：同一文件只保留一条（重复访问移到列表最前、不重复显示），每会话最多保留 **5 条**（原 10 条）；历史数据在加载时自动去重。
-- 时间显示改为 **`HH:MM:SS` 时钟格式**（最近访问列表、文件统计行内时间、悬停提示的创建/最近访问时间），不再显示相对时间（"刚刚 / x 分钟前"）。
-- **最近访问区块可折叠**：点击区块标题展开/收起列表。
-- **文件统计目录树可收纳**：每个文件夹行可点击展开/收起（箭头指示状态），收起后隐藏其子目录与文件。
-
-## [0.2.0] - 2026-08-22
-
-### 变更
-
-- 最近访问列表最多保留 **10 条**（原 300 条），避免列表过长。
-- 文件统计新增时间信息：每个文件行内显示**最近访问时间**（相对时间），悬停可查看**创建时间**（首次接触时间）。
-- 文件统计改为**树形目录**展示：按文件**绝对路径**组织成完整目录树（逐层嵌套，目录节点显示子树汇总计数），连续单子目录的路径链自动**压缩为点号标签**（`a/b/c` → `a.b.c`），不再使用扁平的「根目录」分组与点号拼接标签。
-- 点击文件改为打开**浮窗预览**（不再在侧边栏 tab 栏打开）：图片走媒体路由渲染、PDF 内嵌 iframe、文本/代码经 `fs.read` 滚动展示；浮窗内提供「在侧边栏打开」与「关闭」按钮。
-- 浮窗样式改用 DSH 主题变量（`--dsw-alias-*`），深浅主题下均正确显示；文本加载失败时展示具体错误原因（如文件不存在），并支持相对路径按会话 cwd 解析。
-- 浮窗**自动关闭**：鼠标移出浮窗约 0.5 秒后自动消失（移回则取消），无需手动点击关闭。
-
-## [0.1.0] - 2026-08-22
-
-### 新增
-
-- 首个版本：基于 dsh-better-sidebar 的「文件活动」侧边栏页签。
-- **最近访问**：按时间倒序记录文件读取 / 新增 / 修改事件，点击文件用侧边栏原生预览打开。
-- **文件统计**：按文件统计读取 / 新增 / 修改次数，按文件夹平铺展示（多层文件夹以 `.` 拼接）。
-- **默认启用 + 自动打开**：页签默认开启，会话首次打开自动展开（可在设置中关闭）。
-- 状态按会话持久化到 `$DSH_HOME/file-activity.json`（防抖 + 原子写入）。
+## [0.5.10] - 2026-09-16
+
+### 变更
+
+- test: 存量固定 sleep 收敛（whenReady / drained / 渲染态可观测）
+- docs(清理): 文档瘦身 23765 → 8309 行并固化精简规范
+- chore(artifacts): 同步 8 处共享件产物漂移 + 新增产物一致性门禁（fail-closed）
+- chore(cleanup): 清理 unused-local-variable/useless-expression（含共享件假阳性判定）
+- fix(security): 修复代码扫描 error/warning 告警（5 类规则）
+- fix(test): cucumber-js --import glob 改用双引号，兼容 Windows
+- fix(security): 批量修复 'Insecure temporary file' 安全漏洞
+- fix: 移除未使用的导入，修复告警
+- fix: 修复日志注入，修复告警
+- fix: 移除未使用的stat导入，修复文件系统竞争条件
+- fix: 修复 GitHub Code Scanning 安全漏洞 (43 个)
+- fix(security): fix file system race conditions and missing regex anchor
+- fix(security): use tmp library for secure temporary file creation

package/README.md

@@ -1,113 +1,58 @@
 # dsh-file-activity
 
+[![插件生态](https://img.shields.io/badge/插件生态-topic%20dsh-4d6bfe)](https://github.com/topics/dsh)
+
 <div align="center">
   <img alt="文件活动插件截图（最近访问 / 文件统计）" src="https://unpkg.com/dsh-file-activity/assets/screenshot.png" width="340" />
   <br />
   <img alt="浮窗预览：点击文件复用侧边栏内置 Markdown 渲染" src="https://unpkg.com/dsh-file-activity/assets/preview-float.png" width="340" />
   <br />
-  <img alt="浮窗 HTML 预览：内容撑满整个浮窗主体（issue #111）" src="https://unpkg.com/dsh-file-activity/assets/preview-float-0.5.6.png" width="340" />
+  <img alt="浮窗 HTML 预览：内容撑满整个浮窗主体" src="https://unpkg.com/dsh-file-activity/assets/preview-float-0.5.6.png" width="340" />
 </div>
 
-**DSH 侧边栏文件活动插件**（基于宿主 0.1.5-rc.1 的原生侧边栏扩展点，零第三方侧边栏依赖）：在右侧边栏新增「文件活动」页签，记录 agent 工具与插件自身路由的文件读取/新增/修改事件，提供**最近访问**（LRU）与**文件统计**（树形目录）两块视图，点击文件弹出浮窗预览。
+**dsh-file-activity**：DSH 侧边栏文件活动插件（宿主原生侧边栏扩展点，零第三方侧边栏依赖）——在右侧边栏新增「文件活动」页签，记录 agent 工具与插件自身路由的文件读取/新增/修改事件，提供**最近访问**（LRU）与**文件统计**（树形目录）两块视图，点击文件弹出浮窗预览。
 
 ## 功能
 
-在右侧边栏新增「文件活动」页签：
-
-1. **最近访问**：按 LRU 记录文件读取 / 新增 / 修改事件（agent 工具读写 + 侧边栏打开/编辑保存都会记录），**每会话最多保留 5 条，同一文件只出现一次**（再次访问会移到列表最前）；区块标题可**点击折叠/展开**；点击任意文件即弹出**浮窗预览**（浮窗内渲染：代码高亮 / Markdown 富文本 / 图片 / PDF / 沙箱 HTML，见下方「浮窗预览」）。
-2. **文件统计**：每个文件的「读取 / 新增 / 修改」次数，按文件**绝对路径**组织成**树形目录**；连续单子目录的路径链自动**压缩为点号标签**（如 `a/b/c` → `a.b.c`），文件直接列在下方；**每个文件夹行可点击展开/收起**（箭头指示状态）；每个文件行内显示**相对时间**（刚刚 / N 分钟前 / N 小时前 / N 天前），悬停可查看**创建 / 最近访问**的完整时钟时间：
-
-   ```
-   Users/                    ← 树根 = 绝对路径根（/）
-     bsfeng.IdeaProjects.my-dsh-plugins   ← 连续单子目录压缩为一行
-       README.md
-       lib/
-         index.js
-         client.js
-   ```
-
-3. **默认启用**：页签注册后默认开启（无需在设置页勾选），且每个会话首次打开时**自动打开**本页——开关在 **设置 → 插件 → 文件活动**（`settings.plugins.tab`，存储在浏览器 `localStorage`，插件自身持久化）。
-
-## 工作原理
-
-- **Server 端**（`lib/index.js`）：监听 DSH `fs/observed` 事件捕获 agent 的 `read` / `write` / `edit` / `str_replace_editor` / `read_image` 等文件操作；提供 `/file-activity/api` 路由（`stats` / `record` / `clear`）；状态按会话持久化到 `$DSH_HOME/file-activity.json`（**JSON Lines 增量 append + 阈值原子 compact**，见下「资源治理」）。
-  - `write` 通过每会话的已知文件表自动区分**新增**（首次接触）与**修改**（再次写入）。
-- **Client 端**（`lib/client.js`）：通过宿主原生扩展点注册——`ctx.sidebarRightTabs.register({id,kind,title})`（页签类型）+ `ctx.slots.register({name:'sidebar.right.pane.tab',key:id}, Body)`（正文席位）；`ctx.documentPreviews.register(...)` 声明本插件认领的文件后缀（元数据 only，字节由宿主 document owner 读取）；自动打开走 `ctx.sidebarRight.openTab(kind)`（会话表面未挂载时按 1s 重试，彻底失败会写入 `data-dfa-degraded` 标记并在页签内显示提示，绝不静默失效）；浮窗自实现并挂在宿主推荐落点 `shell.overlay` 列表席位（不替换宿主 UI）；fetch 拦截只记录插件自身路由 `/file-activity/file` 的预览读取。数据按会话（session）**分桶隔离**（`bySession`），每个会话只渲染自己的记录——新建/切换会话立即显示该会话的数据，**不会残留上一个会话的记录**。预览按后缀分流：图片 / PDF / HTML 走插件媒体路由（`<img>` / 原生 PDF frame / **沙箱 iframe**），其余文本走插件文本路由并由官方 `MarkdownText` / `CodeBlock` 渲染（不可用时退回 `<pre>`）。
+- **最近访问**：按 LRU 记录文件读取/新增/修改事件（agent 工具读写 + 侧边栏打开/编辑保存），每会话最多 5 条、同一文件只出现一次（再次访问移到最前）；区块标题可折叠，点击文件弹出浮窗预览。
+- **文件统计**：按文件**绝对路径**组织成树形目录，每个文件显示「读取/新增/修改」次数与相对时间（悬停看完整时钟时间）；连续单子目录压缩为点号标签（`a/b/c` → `a.b.c`），文件夹行可展开/收起。
+- **默认启用**：页签注册后默认开启，且每个会话首次打开时自动打开本页（开关见「配置」）。
+- **浮窗预览**：按后缀渲染——代码（宿主 CodeBlock 组件，取不到时退回纯文本 `<pre>`）/ Markdown（宿主官方渲染器）/ 图片 / PDF（浏览器原生查看器）/ 沙箱 HTML；点击窗外、按 `Esc` 或点 `×` 关闭，长内容窗内滚动。
+- **工作区外文件也能预览**：字节（图片 / PDF / HTML）与文本（Markdown / 代码）都先走插件自身媒体路由，按 `(sessionId, path)` 授权（只放行本会话记录过的路径，未记录一律 403）；插件拒绝该路径时才回退宿主 `fs.read`。
+- **会话隔离**：按会话分桶存储与展示，新建/切换会话立即显示该会话数据，DSH 重启后历史自动恢复。
+- **bash 命令文件触碰**：解析 bash 工具调用里可静态确定的写 / 删操作（rm / touch / tee / mv / cp / install / sed -i）并计入；解析不确定的（`-t` 重定位、未知命令）不记录，git 等未映射命令不跟踪。
 
 ## 安装
 
-> 💡 **npm 安装（普通用户推荐）**：`dsh plugin --profile web add dsh-file-activity --trust-lockfile`——无需克隆本仓库；依赖自动级联安装：`dsh-shared`（server 端共享工具包）是唯一 dependencies，侧边栏能力全部来自宿主原生扩展点（**不需安装任何第三方侧边栏插件**）。
+> 💡 **npm 安装（普通用户推荐）**：`dsh plugin --profile web add dsh-file-activity --trust-lockfile`——无需克隆本仓库；依赖自动级联安装（`dsh-shared` 是唯一 dependencies，侧边栏能力全部来自宿主原生扩展点）。
 
 ```sh
 # 方式一：dsh plugin（推荐）
-# 1) 克隆本仓库（任意目录）
 git clone https://github.com/baosfeng/my-dsh-plugins.git
-# 2) 以本地 link 方式安装（将 <仓库路径> 替换为上面的克隆目录）
 dsh plugin --profile web add link:<仓库路径>/plugins/dsh-file-activity
 
-# 方式二：手动
-# 1) 克隆本仓库后，在 ~/.dsh/profiles/web/package.json 的 dependencies 增加：
-#    "dsh-file-activity": "link:<仓库路径>/plugins/dsh-file-activity"
-# 2) 在 ~/.dsh/profiles/web 下执行 pnpm install
-# 3) 在 ~/.dsh/profiles/web/cordis.patch.yml 增加：
-#    - insert:
-#        - id: file-activity
-#          name: 'dsh-file-activity'
+# 方式二：手动 —— 在 profile package.json dependencies 加
+#   "dsh-file-activity": "link:<仓库路径>/plugins/dsh-file-activity"
+# 再 pnpm install，并在 cordis.patch.yml 加 id: file-activity / name: 'dsh-file-activity'
 ```
 
-装完后**硬刷新浏览器**（Cmd/Ctrl+Shift+R）。
-
-> 编辑 profile 的 `cordis.patch.yml` 会在运行中通过 Cordis HMR 热挂载 server 端，无需重启 `dsh web`；client 端在页面刷新后生效。
+装完**硬刷新浏览器**（Cmd/Ctrl+Shift+R）。编辑 profile 的 `cordis.patch.yml` 会经 Cordis HMR 热挂载 server 端，无需重启 `dsh web`。
 
 ## 使用
 
-- 侧边栏「新标签页」（guide）菜单 → 文件活动（本插件向宿主 `sidebarRightTabs.register` 的 `guide` 提供入口，issue #266 B），或会话开始自动打开。
-- 点击任意文件行 → 弹出**浮窗预览**：按后缀渲染（代码语法高亮 / Markdown 富文本 / 图片 / PDF / 沙箱 HTML），不打开侧边栏编辑器标签；**点击浮窗外任意处或按 `Esc` 即可关闭**，大文件可在浮窗内滚动。
+- 入口：侧边栏「新标签页」（guide）菜单 → 文件活动，或会话开始自动打开。
+- 点击任意文件行 → 浮窗预览，不打开侧边栏编辑器标签。
 - 顶部「刷新」手动重载，「清空」删除当前会话全部记录。
-
-### 浮窗预览（复用内置渲染）
-
-点击文件（最近访问 / 文件统计中的任意文件行）会打开一个**悬浮预览窗**，窗口由本插件渲染（挂在宿主 `shell.overlay` 浮层席位上，不替换宿主 UI）—— 按后缀分流：图片（svg/png/jpg/gif/webp/avif/bmp/ico）用 `<img>`、PDF 用原生 `<iframe>`、HTML（html/htm/xhtml）用**沙箱 `<iframe>`**，三者都取插件自己的媒体路由 `/file-activity/file`（按 `(sessionId, path)` 授权，因此工作区外的记录路径也能预览）；其余文本走插件文本路由 `/file-activity/file?as=text`，由官方 `MarkdownText` / `CodeBlock` 渲染（组件库不可用时退回 `<pre>`）。浮窗为轻量交互：**点击浮窗外任意处、按 `Esc` 或点标题栏右上 `×` 都能关闭**；浮窗主体是可滚动区域，长文件或大图在窗内滚动查看。
-
-- **代码**（后台为侧边栏内置 CodeMirror 编辑器）：语法高亮 + 行号；支持 预览/编辑 切换与保存。
-- **Markdown**（`.md` / `.markdown`）：渲染后的富文本预览，可切换 预览/编辑 模式。
-- **图片**（png / jpg / jpeg / gif / webp / svg / bmp / ico / avif）：通过媒体路由渲染。
-- **PDF**：浏览器原生 PDF 查看器（浮窗内嵌，工具栏提供下载）。
-- **HTML**（`.html` / `.htm` / `.xhtml`）：**沙箱化 iframe 渲染**，内容**撑满整个浮窗主体**（iframe 随浮窗尺寸自适应、内部滚动，与代码/Markdown/图片预览体验一致，issue #111）。沙箱有两层且都不含 `allow-same-origin`：iframe 的 `sandbox="allow-scripts allow-forms"` 与媒体路由响应头的 `Content-Security-Policy: sandbox allow-scripts allow-forms`（响应头让**直接打开该 URL 也仍是沙箱文档**）。文档因此拿到 opaque origin：脚本/表单可跑（交互式页面可用），但读不到宿主页面的 Cookie、存储与同源 API，也不能导航父窗口。页内相对路径资源按站点根解析（不重写为文件目录，与浏览器直开行为一致）。
-- 其余文件按内置 viewer 的 `matchFileViewer` 回退匹配（如 `binary-download` 下载未知二进制）。
-
-> 💡 **工作区外文件也能预览**：文件活动记录的是 agent 实际触碰过的文件，路径可能在会话工作区之外（如 `/tmp` 临时文件）。侧边栏自带的媒体路由只允许工作区内文件，因此图片/PDF 的字节由插件自身的 `/file-activity/file` 路由提供——它按会话记录授权（只放行本会话记录过的路径，未记录的路径一律 403），fence 与侧边栏一致。Markdown/代码文本则仍走侧边栏 `fs.read`（不被工作区限制）；HTML 走插件媒体路由的沙箱文档（见上）。
+- 资源上限：每会话路径 ≤ 300 / 全局 ≤ 20000 / 会话数 ≤ 64，超限按 LRU 淘汰最久未活动条目（非静默丢弃，写 warn 日志）；审计与写盘按增量追加 + 原子 compact，磁盘用量有界。
 
 ## 配置
 
-「设置 → 侧边卡片 → 文件活动」卡片齿轮：`会话开始时自动打开`（默认开）。
-
-## 数据说明
-
-- 按会话（session）隔离存储（服务端 `$DSH_HOME/file-activity.json` 按 sessionId 分桶 + 前端 `bySession` 分桶展示）；**DSH 重启后历史数据自动恢复**（持久化加载）；新建/切换会话不残留其他会话的记录。
-
-## 资源治理（issue #197）
-
-写放大与无界增长防护（9/2 事故同构模式整改）：
-
-- **增量落盘**：每次记录只追加一行 JSON（`{"s","p","o","t"}`，落盘字节 ≈ 事件本体字节 ×1.0），
-  累计行数达到按状态体积自适应的阈值时做一次原子 compact（tmp+rename 重写快照行），
-  文件大小与写入量双向有界（实测写放大 1.0×，旧实现 2,073×）；
-- **三维入口上限（LRU 淘汰，非静默丢弃）**：每会话路径 ≤ 300、全局路径 ≤ 20000、会话数 ≤ 64；
-  超限淘汰最久未活动条目/会话，淘汰计数暴露在 `store.stats()` 且写 warn 日志（首次 + 每 10 次）；
-- **显式护栏**：compact 快照受 `minIntervalMs`（体积分级节流）与 `maxBytes`（8MB 硬上限，超限拒绝写 + 告警）约束；
-- **升级兼容**：旧的全量 JSON 快照（单行/多行）仍可读取，首次启动一次性改写为 JSON Lines；
-  文件里只有事件行（未 compact）时也能按行序完整重放（不丢数据）。
-- 最近访问列表每会话最多保留 5 条（LRU：同一文件仅一条，重复访问移到最前），文件统计不受条数限制。
-- agent 的 `bash`/`git` 等命令内部的文件触碰不在此跟踪范围（只跟踪 DSH 原生文件工具与侧边栏操作）。
-
-## 依赖
+无 profile 配置项（不读 `cordis.patch.yml` 的 `config`）；唯一开关是设置页 UI 偏好：
 
-| 依赖         | 用途                                 | 可选                 |
-| ------------ | ------------------------------------ | -------------------- |
-| `dsh-shared` | server 端共享工具包（路由/JSONL 等） | 否（随插件自动安装） |
-| `cordis`     | 插件运行时                           | 是（宿主提供）       |
+| 配置项                                           | 默认 | 作用                                                                       |
+| ------------------------------------------------ | ---- | -------------------------------------------------------------------------- |
+| 会话开始时自动打开（**设置 → 插件 → 文件活动**） | 开   | 每个会话首次打开时自动显示本页；关闭后仍可从侧边栏「新标签页」菜单手动打开 |
 
 ## 相关文档
 
-→ [文件活动追踪模块文档](../../docs/文件活动追踪/概述.md) · [需求清单](../../docs/文件活动追踪/需求清单.md) · [CHANGELOG](CHANGELOG.md)
+→ [文件活动追踪模块文档](../../docs/文件活动追踪/概述.md) · [CHANGELOG](CHANGELOG.md)

package/lib/client.js

@@ -685,6 +685,33 @@ const icon = {
       ],
       size,
     ),
+  // 箭头向上（更新图标）：向上的箭头，表示更新操作
+  arrowUp: (size = 16) =>
+    iconSvg(
+      [
+        createElement('line', { x1: 12, y1: 19, x2: 12, y2: 5 }),
+        createElement('polyline', { points: '5 12 12 5 19 12' }),
+      ],
+      size,
+    ),
+  // 电源关（禁用图标）：圆形电源按钮，表示禁用操作
+  powerOff: (size = 16) =>
+    iconSvg(
+      [
+        createElement('path', { d: 'M18.36 6.64a9 9 0 1 1-12.73 0' }),
+        createElement('line', { x1: 12, y1: 2, x2: 12, y2: 12 }),
+      ],
+      size,
+    ),
+  // 电源开（启用图标）：圆形电源按钮，表示启用操作
+  powerOn: (size = 16) =>
+    iconSvg(
+      [
+        createElement('path', { d: 'M18.36 6.64a9 9 0 1 1-12.73 0' }),
+        createElement('line', { x1: 12, y1: 2, x2: 12, y2: 12 }),
+      ],
+      size,
+    ),
 }
 
 // Common-language / file-type badges (issue #24): brand fill + contrast
@@ -1317,7 +1344,7 @@ function FileActivityView({
   dataStore,
 }) {
   const data = useSyncExternalStore(dataStore.subscribe, dataStore.getSnapshot)
-  const [cwd, setCwd] = useState(scope?.cwd || '')
+  const [, setCwd] = useState(scope?.cwd || '')
   const [error, setError] = useState(false)
   const [recentOpen, setRecentOpen] = useState(true)
   const [collapsedDirs, setCollapsedDirs] = useState(() => new Set())

package/lib/index.js

@@ -54,6 +54,13 @@ function bashBaseDirOf(exec, ctx, sessionId) {
     const workdir = exec.arguments?.workdir;
     return typeof workdir === 'string' && workdir !== '' ? workdir : sessionCwdOf(ctx, sessionId);
 }
+/**
+ * 装配插件并返回本实例的 store。
+ *
+ * 返回 store 是为了让宿主/测试拿到**确定性就绪信号**（`await store.whenReady()`，
+ * issue #343）：此前该插件没有就绪信号，测试只能固定等 50–100ms 赌异步状态加载完成。
+ * 返回值是新增能力，调用方忽略它时行为与此前完全一致。
+ */
 export function apply(ctx) {
     const store = createStore(ctx);
     // ── agent-side file operations ──────────────────────────────────────────
@@ -98,4 +105,5 @@ export function apply(ctx) {
     });
     // Tear down on unload: flush pending persistence.
     ctx.effect(() => store.dispose, 'dsh-file-activity: persistence teardown');
+    return store;
 }

package/lib/media-route.js

@@ -13,7 +13,7 @@
  * fence), the client falls back to this route and receives an fs.read-shaped
  * JSON payload ({ ok, value: { content } }) so the viewer mounts unchanged.
  */
-import { readFile, stat } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { basename, isAbsolute, join } from 'node:path';
 import { writeJson } from 'dsh-shared';
 import { sessionCwdOf } from './cwd.js';
@@ -113,20 +113,41 @@ function assertMediaParams(sessionId, raw) {
     if (sessionId === null || raw === null || raw === '')
         throw mediaError(400, 'sessionId and path are required');
 }
+/**
+ * 把 fs 读取失败按 errno 分类成 HTTP 状态（#318：commit 76f52ac 引入的 `catch {}` 把
+ * 所有错误都吞成 404，丢掉了旧实现的诊断信息——EISDIR 与 EACCES 都被误报为
+ * "file not found"，而目录明明存在、权限被拒也不是"没找到"）。
+ *
+ * 分类（与同文件既有契约对齐）：
+ *   · EISDIR       → 400 'not a file'     —— 与加固前 `if (!info.isFile())` 的行为一致
+ *   · EACCES/EPERM → 403 'permission denied' —— 与信任围栏的 403 语义一致
+ *   · 其余（含 ENOENT）→ 404 'file not found'
+ *
+ * TOCTOU 加固保留：不再 stat，只在一次 `readFile` 失败后按 errno 归类——check-then-use
+ * 的时间窗不复存在，分类只依赖这次真实失败的原因。
+ */
+function mediaReadError(error, abs) {
+    const code = error?.code;
+    if (code === 'EISDIR' || code === 'ENOTDIR')
+        return mediaError(400, `not a file: ${abs}`);
+    if (code === 'EACCES' || code === 'EPERM')
+        return mediaError(403, `permission denied: ${abs}`);
+    return mediaError(404, 'file not found');
+}
 /** stat + read + respond with the file's bytes (bounded by MEDIA_LIMIT). */
 async function serveMedia(response, abs, url) {
-    let info;
+    let body;
     try {
-        info = await stat(abs);
+        // 单次 read：不再 stat，避免 check-then-use（#318 前的 TOCTOU 加固）
+        body = await readFile(abs);
     }
-    catch {
-        throw mediaError(404, 'file not found');
+    catch (error) {
+        // 按 errno 分类（目录 → 400；权限 → 403；其余 → 404），不丢诊断信息
+        throw mediaReadError(error, abs);
     }
-    if (!info.isFile())
-        throw mediaError(400, 'not a file');
-    if (info.size > MEDIA_LIMIT)
+    // Check file size after reading to avoid race condition
+    if (body.length > MEDIA_LIMIT)
         throw mediaError(413, 'file too large');
-    const body = await readFile(abs);
     const headers = {
         'content-type': mediaTypeForPath(abs),
         'cache-control': 'no-cache',
@@ -151,17 +172,16 @@ async function serveMedia(response, abs, url) {
  * recorded paths only.
  */
 async function serveText(response, abs) {
-    let info;
+    let content;
     try {
-        info = await stat(abs);
+        // Use try-catch instead of stat + readFile to avoid TOCTOU race condition
+        content = await readFile(abs, 'utf8');
     }
-    catch {
-        throw mediaError(404, 'file not found');
+    catch (error) {
+        throw mediaReadError(error, abs);
     }
-    if (!info.isFile())
-        throw mediaError(400, 'not a file');
-    if (info.size > TEXT_LIMIT)
+    // Check content length after reading to avoid race condition
+    if (content.length > TEXT_LIMIT)
         throw mediaError(413, 'file too large');
-    const content = await readFile(abs, 'utf8');
     writeJson(response, 200, { ok: true, value: { content } });
 }

package/lib/parts/view.part.js

@@ -176,7 +176,7 @@ function FileActivityView({
   dataStore,
 }) {
   const data = useSyncExternalStore(dataStore.subscribe, dataStore.getSnapshot)
-  const [cwd, setCwd] = useState(scope?.cwd || '')
+  const [, setCwd] = useState(scope?.cwd || '')
   const [error, setError] = useState(false)
   const [recentOpen, setRecentOpen] = useState(true)
   const [collapsedDirs, setCollapsedDirs] = useState(() => new Set())

package/lib/state.js

@@ -14,9 +14,6 @@ import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { createSession, defaultLimits, emptyEvicted } from './quota.js';
 import { trimToQuota } from './quota-trim.js';
-/** 快照元信息行标记 / 快照结束行标记（非会话数据行）。 */
-const META = '~';
-const END = '=';
 /** NUL 字符（路径合法性判定）。 */
 const NUL = String.fromCharCode(0);
 /**

package/lib/store.js

@@ -7,7 +7,7 @@
  */
 import { createState, foldRecord, loadState, mapOp, stateFile } from './state.js';
 import { createPersist, readAppenderStats } from './persist.js';
-import { emptyEvicted, enforceQuota, normalizeLimits, } from './quota.js';
+import { emptyEvicted, enforceQuota, normalizeLimits } from './quota.js';
 import { statSync } from 'node:fs';
 /** compact 触发下限：快照成本必须远小于触发区间的事件流字节（写放大 ≤ 1.6 的关键）。 */
 const MIN_COMPACT_LINES = 20000;
@@ -23,7 +23,7 @@ function compactLinesFor(stateBytes) {
     const scaled = Math.ceil((stateBytes * 12) / AVG_EVENT_BYTES);
     return Math.min(MAX_COMPACT_LINES, Math.max(MIN_COMPACT_LINES, scaled));
 }
-/** Build the per-apply store: { state, record, schedulePersist, stats, dispose }. */
+/** Build the per-apply store: { state, record, schedulePersist, stats, whenReady, dispose }. */
 export function createStore(ctx, deps = {}) {
     const limits = normalizeLimits(deps.limits);
     const store = {
@@ -32,6 +32,7 @@ export function createStore(ctx, deps = {}) {
         schedulePersist: () => { },
         stats: () => zeroStats(limits),
         dispose: () => { },
+        whenReady: () => Promise.resolve(),
     };
     const handle = {
         ctx,
@@ -39,6 +40,7 @@ export function createStore(ctx, deps = {}) {
         store,
         pending: [],
         ready: false,
+        readyPromise: Promise.resolve(),
         limits,
         evicted: emptyEvicted(),
         facts: [],
@@ -49,6 +51,13 @@ export function createStore(ctx, deps = {}) {
         compactedEvents: 0,
         compactLinesFixed: deps.compactLines !== undefined,
     };
+    // 加载就绪信号（issue #343）：onLoaded 完成「磁盘状态合并 + pending 回放」后 resolve。
+    // 与 #310/#313/#335 同款能力 —— 该插件此前**没有任何就绪信号**，测试只能固定等 50–100ms 赌加载。
+    let markReady = () => { };
+    handle.readyPromise = new Promise((resolve) => {
+        markReady = resolve;
+    });
+    handle.markReady = markReady;
     handle.persist = createPersist({
         file: handle.file,
         ctx,
@@ -61,6 +70,7 @@ export function createStore(ctx, deps = {}) {
     store.schedulePersist = () => enqueueFlush(handle, true);
     store.stats = () => snapshotStats(handle);
     store.dispose = () => dispose(handle);
+    store.whenReady = () => handle.readyPromise;
     void loadState(handle.file, limits, ctx.logger).then((loaded) => onLoaded(handle, loaded));
     return store;
 }
@@ -133,6 +143,9 @@ function onLoaded(handle, loaded) {
         flushFacts(handle);
         schedulePersist(handle);
     }
+    // **顺序关键**：缓冲记录回放之后才兑现就绪信号 ——
+    // `await store.whenReady()` 之后查询必含加载期间记录的内容（issue #343）。
+    handle.markReady?.();
 }
 /** Apply every record buffered before the state load finished (deferred flush). */
 function drainPending(handle) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-file-activity",
-  "version": "0.5.9",
+  "version": "0.5.10",
   "description": "DSH 侧边栏文件活动插件：按 LRU 记录文件读取/新增/修改事件（最近访问），按绝对路径树形统计（文件统计），点击文件浮窗预览（代码高亮/Markdown/图片/PDF）。DSH web plugin: file activity tracker — LRU recent-access list plus per-file read/create/modify counts in a folder tree, with floating preview.",
   "type": "module",
   "main": "lib/index.js",
@@ -14,7 +14,7 @@
   "scripts": {
     "build": "npx tsc -p tsconfig.json && node scripts/build.mjs",
     "typecheck": "npx tsc --noEmit -p tsconfig.json && npx tsc --noEmit -p tsconfig.client.json",
-    "test": "npx vitest run --coverage && cucumber-js test/features --import 'test/features/steps/*.mjs'"
+    "test": "npx vitest run --coverage && cucumber-js test/features --import \"test/features/steps/*.mjs\""
   },
   "exports": {
     ".": {