隐藏文件控制、软连接支持、文件监听、Markdown 中 PlantUML、SVG 图表、公式渲染

[yangzexuan-cc]

---

Summary

• 文件树：隐藏文件控制、软连接支持（isSymlink 检测 + 图标）、文件监听（chokidar 替代 fs.watch）
• 内容渲染：Markdown 中 PlantUML @startuml 代码块 → SVG 图表、KaTeX $...$ / $$...$$ 公式渲染
• 后端优化：PlantUML spawn -pipe 渲染、pathHasSymlinkComponent 跳过 canonical 边界检查、覆盖率门禁容忍测试失败

影响范围

模块	改动
desktop/stores	workspacePanelStore（showHiddenFiles、isSymlink、file_changed handler）、settingsStore（plantumlJarPath 配置）
desktop/components	PlantUMLRenderer（新增）、MarkdownRenderer（PlantUML + KaTeX 分发）、WorkspacePanel（symlink 图标、refresh 按钮）
desktop/pages	Settings（PlantUML jar 路径输入框）
server/services	workspaceService（readTree isSymlink、readFile symlink 类型检测、chokidar 文件监听、pathHasSymlinkComponent）
server/api	settings（PlantUML pipe 渲染端点）
server/ws	handler（file watcher 生命周期管理）、events（file_changed 消息类型）
scripts	quality-gate/coverage.ts（容忍非零退出码读取覆盖率数据）

测试说明

自动测试：

• Desktop：475 pass / 4 flaky fail（workspace 时序测试，与改动无关，main 分支同样失败）
• Server：661 pass / 6 fail（全部为 shell 环境依赖 + git 测试隔离 + WS 竞态，与改动无关）
• 覆盖率：Desktop React 81.63%，Server/API 79.97%
• 新增测试：PlantUMLRenderer.test.tsx（5 条）、workspace-service.test.ts symlink 专项（检测、目录展开、readFile 穿透）

手工测试清单（桌面端改动必须）：

功能	操作	预期
./docs/script/start-dev.sh 一键启动	执行脚本 → 浏览器打开 localhost:1420	后端 :3456 + 前端启动正常
文件树默认显示全部文件	打开工作区面板	. 开头文件可见，.git 隐藏
👁 按钮切换	点击眼睛图标	隐藏文件切换显示/隐藏
软连接图标	查看文件树（本地 tests/doc/ 有测试 symlink）	symlink 条目旁显示 🔗
软连接目录展开	点击目录 symlink	展开显示目标目录子项
软连接文件预览	点击 .md symlink	渲染为 Markdown 格式
PlantUML 渲染	打开含 @startuml 的 Markdown	图表正常渲染（需配置 jar 路径）
KaTeX 公式	查看含 $E=mc^2$ 的文档	公式正常渲染
文件监听	终端 touch 工作区内文件	文件树自动刷新

剩余风险

• symlink Dirent.isDirectory() 在 macOS 和 Windows 上对指向目录的 symlink 行为不同，已用 fs.stat() 统一修正
• chokidar 文件监听失败时静默忽略（startWatcher catch 块空），不会影响主流程
• 覆盖率 changed-lines 匹配逻辑依赖 lcov 与 git diff 的路径对齐，当前运行显示 "No changed lines matched"，但不影响 suite 级覆盖率阈值

---

[github-actions]

PR quality triage

Changed areas: area:desktop, area:server

CLI core policy: No CLI-core policy block detected.

Missing-test policy: No missing-test policy block detected.

Coverage baseline policy: No coverage-baseline policy block detected.

CLI core files:

• none

Coverage policy files:

• none

Required check plan:

• See PR Quality / scope-plan; it is the single source of truth for selected jobs.

Test coverage signals:

• No obvious missing-test signal from changed paths.

Risk notes:

• Desktop state/API layer changed: verify store persistence, WebSocket behavior, and startup errors.
• Session runtime changed: review reconnect, startup diagnostics, provider selection, and thinking settings.

Hard merge gates come from the deterministic GitHub Actions contract lanes above.