dsh-file-activity 0.5.7 → 0.5.10

package/CHANGELOG.md

@@ -2,164 +2,20 @@
 
 本文件记录 dsh-file-activity 的所有版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
-## [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,102 +1,58 @@
 # dsh-file-activity
 
-[![插件生态](https://img.shields.io/badge/插件生态-topic%20dsh--better--sidebar-4d6bfe)](https://github.com/topics/dsh-better-sidebar)
+[![插件生态](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 侧边栏文件活动插件**（基于 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) 扩展）：在 better-sidebar 中新增「文件活动」页签，记录 agent 工具与侧边栏自身的文件读取/新增/修改事件，提供**最近访问**（LRU）与**文件统计**（树形目录）两块视图，点击文件弹出浮窗预览。
+**dsh-file-activity**：DSH 侧边栏文件活动插件（宿主原生侧边栏扩展点，零第三方侧边栏依赖）——在右侧边栏新增「文件活动」页签，记录 agent 工具与插件自身路由的文件读取/新增/修改事件，提供**最近访问**（LRU）与**文件统计**（树形目录）两块视图，点击文件弹出浮窗预览。
 
 ## 功能
 
-在 better-sidebar 中新增「文件活动」页签：
-
-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. **默认启用**：页签注册后默认开启（无需在设置页勾选），且每个会话首次打开时**自动打开**本页（可在侧边栏设置中关闭自动打开）。
-
-## 工作原理
-
-- **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`（防抖 + 原子写入）。
-  - `write` 通过每会话的已知文件表自动区分**新增**（首次接触）与**修改**（再次写入）。
-- **Client 端**（`lib/client.js`）：通过 `ctx.betterSidebar.registerTab` 注册页签；fetch 拦截捕获侧边栏自身操作（`/sidebar/api/fs.read`、`/sidebar/api/fs.write`、`/sidebar/file` 媒体预览）并上报 server；数据按会话（session）**分桶隔离**（`bySession`），每个会话只渲染自己的记录——新建/切换会话立即显示该会话的数据，**不会残留上一个会话的记录**；点击文件通过 `ctx.betterSidebar.matchFileViewer(path)` 匹配内置 viewer 并挂载其组件，打开浮窗预览。
+- **最近访问**：按 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-better-sidebar`（宿主，提供侧边栏扩展点）与 `dsh-shared`（server 端共享工具包）均声明为 dependencies，安装时自动安装并加入 profile bundles，无需手动单独处理。
+> 💡 **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`。
 
 ## 使用
 
-- 侧边栏 `+` 菜单 → 文件活动（或会话开始自动打开）。
-- 点击任意文件行 → 弹出**浮窗预览**：浮窗内**复用侧边栏内置的 file viewer** 渲染（代码语法高亮 / Markdown 富文本 / 图片 / PDF / HTML），不打开侧边栏编辑器标签，也不自建预览实现；**点击浮窗外任意处或按 `Esc` 即可关闭**，大文件可在浮窗内滚动。
+- 入口：侧边栏「新标签页」（guide）菜单 → 文件活动，或会话开始自动打开。
+- 点击任意文件行 → 浮窗预览，不打开侧边栏编辑器标签。
 - 顶部「刷新」手动重载，「清空」删除当前会话全部记录。
-
-### 浮窗预览（复用内置渲染）
-
-点击文件（最近访问 / 文件统计中的任意文件行）会打开一个**悬浮预览窗**，窗口内容由侧边栏**内置的文件查看器**（file viewer）渲染 —— 通过 `ctx.betterSidebar.matchFileViewer(path)` 拿到匹配的 viewer，取其 `component` 挂载，并按 viewer 的 `fetchStrategy` 取内容（`fsRead` 文本 / `mediaUrl` 媒体 / `custom` 自定义）。浮窗为轻量交互：**点击浮窗外任意处、按 `Esc` 或点标题栏右上 `×` 都能关闭**；浮窗主体是可滚动区域，长文件或大图在窗内滚动查看。
-
-- **代码**（后台为侧边栏内置 CodeMirror 编辑器）：语法高亮 + 行号；支持 预览/编辑 切换与保存。
-- **Markdown**（`.md` / `.markdown`）：渲染后的富文本预览，可切换 预览/编辑 模式。
-- **图片**（png / jpg / jpeg / gif / webp / svg / bmp / ico / avif）：通过媒体路由渲染。
-- **PDF**：浏览器原生 PDF 查看器（浮窗内嵌，工具栏提供下载）。
-- **HTML**：沙箱化渲染预览，内容**撑满整个浮窗主体**（iframe 随浮窗尺寸自适应、内部滚动，与代码/Markdown/图片预览体验一致，issue #111）。
-- 其余文件按内置 viewer 的 `matchFileViewer` 回退匹配（如 `binary-download` 下载未知二进制）。
-
-> 💡 **工作区外文件也能预览**：文件活动记录的是 agent 实际触碰过的文件，路径可能在会话工作区之外（如 `/tmp` 临时文件）。侧边栏自带的媒体路由只允许工作区内文件，因此图片/PDF 的字节由插件自身的 `/file-activity/file` 路由提供——它按会话记录授权（只放行本会话记录过的路径，未记录的路径一律 403），fence 与侧边栏一致。Markdown/代码/HTML 文本则仍走侧边栏 `fs.read`（不被工作区限制）。
+- 资源上限：每会话路径 ≤ 300 / 全局 ≤ 20000 / 会话数 ≤ 64，超限按 LRU 淘汰最久未活动条目（非静默丢弃，写 warn 日志）；审计与写盘按增量追加 + 原子 compact，磁盘用量有界。
 
 ## 配置
 
-「设置 → 侧边卡片 → 文件活动」卡片齿轮：`会话开始时自动打开`（默认开）。
-
-## 数据说明
-
-- 按会话（session）隔离存储（服务端 `$DSH_HOME/file-activity.json` 按 sessionId 分桶 + 前端 `bySession` 分桶展示）；**DSH 重启后历史数据自动恢复**（持久化加载）；新建/切换会话不残留其他会话的记录。
-- 最近访问列表每会话最多保留 5 条（LRU：同一文件仅一条，重复访问移到最前），文件统计不受条数限制。
-- agent 的 `bash`/`git` 等命令内部的文件触碰不在此跟踪范围（只跟踪 DSH 原生文件工具与侧边栏操作）。
-
-## 依赖
+无 profile 配置项（不读 `cordis.patch.yml` 的 `config`）；唯一开关是设置页 UI 偏好：
 
-| 依赖                 | 用途                              | 可选                           |
-| -------------------- | --------------------------------- | ------------------------------ |
-| `dsh-better-sidebar` | 侧边栏页签注册 + 浮窗 file viewer | 否（前置，v0.12+，推荐 v0.14） |
-| `cordis`             | 插件运行时                        | 是（宿主提供）                 |
+| 配置项                                           | 默认 | 作用                                                                       |
+| ------------------------------------------------ | ---- | -------------------------------------------------------------------------- |
+| 会话开始时自动打开（**设置 → 插件 → 文件活动**） | 开   | 每个会话首次打开时自动显示本页；关闭后仍可从侧边栏「新标签页」菜单手动打开 |
 
 ## 相关文档
 
-→ [文件活动追踪模块文档](../../docs/文件活动追踪/概述.md) · [需求清单](../../docs/文件活动追踪/需求清单.md) · [CHANGELOG](CHANGELOG.md)
+→ [文件活动追踪模块文档](../../docs/文件活动追踪/概述.md) · [CHANGELOG](CHANGELOG.md)

package/lib/api-route.js

@@ -3,93 +3,89 @@
  * Every request passes the trust fence first; responses are JSON with
  * cache-control: no-cache.
  */
-import { readJsonBody, writeError, writeJson } from 'dsh-shared'
-import { sessionCwdOf } from './cwd.js'
-import { mapOp } from './state.js'
-
-export function createApiHandler({ ctx, store, fence }) {
-  return async (request, response) => {
-    if (!fence(request)) {
-      writeJson(response, 403, { ok: false, error: { code: 'forbidden', message: 'forbidden' } })
-      return
-    }
-    const url = new URL(request.url ?? '/', 'http://dsh.internal')
-    const method = apiMethodOf(url)
-    try {
-      if (method === 'record' && request.method === 'POST') {
-        await handleRecord(store, request, response)
-        return
-      }
-      if (method === 'stats' && request.method === 'GET') {
-        handleStats(ctx, store, url, response)
-        return
-      }
-      if (method === 'clear' && request.method === 'POST') {
-        await handleClear(store, request, response)
-        return
-      }
-      writeJson(response, 404, {
-        ok: false,
-        error: { message: 'unknown file-activity API method' },
-      })
-    } catch (error) {
-      writeError(response, error)
-    }
-  }
+import { readJsonBody, writeError, writeJson } from 'dsh-shared';
+import { sessionCwdOf } from './cwd.js';
+import { mapOp } from './state.js';
+export function createApiHandler({ ctx, store, fence, }) {
+    return async (request, response) => {
+        if (!fence(request)) {
+            writeJson(response, 403, { ok: false, error: { code: 'forbidden', message: 'forbidden' } });
+            return;
+        }
+        const url = new URL(request.url ?? '/', 'http://dsh.internal');
+        const method = apiMethodOf(url);
+        try {
+            if (method === 'record' && request.method === 'POST') {
+                await handleRecord(store, request, response);
+                return;
+            }
+            if (method === 'stats' && request.method === 'GET') {
+                handleStats(ctx, store, url, response);
+                return;
+            }
+            if (method === 'clear' && request.method === 'POST') {
+                await handleClear(store, request, response);
+                return;
+            }
+            writeJson(response, 404, {
+                ok: false,
+                error: { message: 'unknown file-activity API method' },
+            });
+        }
+        catch (error) {
+            writeError(response, error);
+        }
+    };
 }
-
 /** Strip the /file-activity/api/ prefix; undefined for anything else. */
 function apiMethodOf(url) {
-  const pathname = url.pathname
-  return pathname.startsWith('/file-activity/api/') ? pathname.slice('/file-activity/api/'.length) : undefined
+    const pathname = url.pathname;
+    return pathname.startsWith('/file-activity/api/') ? pathname.slice('/file-activity/api/'.length) : undefined;
 }
-
 /** POST /file-activity/api/record — client-reported sidebar operation. */
 async function handleRecord(store, request, response) {
-  const payload = await readJsonBody(request)
-  const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : ''
-  const path = typeof payload.path === 'string' ? payload.path : ''
-  const op = typeof payload.op === 'string' ? payload.op : 'read'
-  store.record(sessionId, path, mapOp(op), Date.now())
-  writeJson(response, 200, { ok: true })
+    const payload = await readJsonBody(request);
+    const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : '';
+    const path = typeof payload.path === 'string' ? payload.path : '';
+    const op = typeof payload.op === 'string' ? payload.op : 'read';
+    store.record(sessionId, path, mapOp(op), Date.now());
+    writeJson(response, 200, { ok: true });
 }
-
 /** GET /file-activity/api/stats — recent + counts + session cwd. */
 function handleStats(ctx, store, url, response) {
-  const sessionId = url.searchParams.get('sessionId') ?? ''
-  // Session working directory, for client-side relative-path display.
-  const cwd = sessionCwdOf(ctx, sessionId)
-  const session = store.state.sessions[sessionId]
-  if (session === undefined) {
-    writeJson(response, 200, { ok: true, value: { recent: [], counts: {}, cwd } })
-    return
-  }
-  // Snapshot the leaf fields only — no live objects cross the wire.
-  const recent = session.recent.map((entry) => ({
-    path: entry.path,
-    op: entry.op,
-    time: entry.time,
-  }))
-  const counts = {}
-  for (const [path, counter] of Object.entries(session.counts)) {
-    counts[path] = {
-      read: counter.read,
-      create: counter.create,
-      modify: counter.modify,
-      firstSeen: counter.firstSeen,
-      lastSeen: counter.lastSeen,
+    const sessionId = url.searchParams.get('sessionId') ?? '';
+    // Session working directory, for client-side relative-path display.
+    const cwd = sessionCwdOf(ctx, sessionId);
+    const session = store.state.sessions[sessionId];
+    if (session === undefined) {
+        writeJson(response, 200, { ok: true, value: { recent: [], counts: {}, cwd } });
+        return;
     }
-  }
-  writeJson(response, 200, { ok: true, value: { recent, counts, cwd } })
+    // Snapshot the leaf fields only — no live objects cross the wire.
+    const recent = session.recent.map((entry) => ({
+        path: entry.path,
+        op: entry.op,
+        time: entry.time,
+    }));
+    const counts = {};
+    for (const [path, counter] of Object.entries(session.counts)) {
+        counts[path] = {
+            read: counter.read,
+            create: counter.create,
+            modify: counter.modify,
+            firstSeen: counter.firstSeen,
+            lastSeen: counter.lastSeen,
+        };
+    }
+    writeJson(response, 200, { ok: true, value: { recent, counts, cwd } });
 }
-
 /** POST /file-activity/api/clear — wipe one session's records (persisted). */
 async function handleClear(store, request, response) {
-  const payload = await readJsonBody(request)
-  const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : ''
-  if (sessionId !== '' && store.state.sessions[sessionId] !== undefined) {
-    delete store.state.sessions[sessionId]
-    store.schedulePersist()
-  }
-  writeJson(response, 200, { ok: true })
+    const payload = await readJsonBody(request);
+    const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : '';
+    if (sessionId !== '' && store.state.sessions[sessionId] !== undefined) {
+        delete store.state.sessions[sessionId];
+        store.schedulePersist();
+    }
+    writeJson(response, 200, { ok: true });
 }