Prism

一束白光进棱镜，折射出每个项目自己的颜色。

Prism 是 ZCode 桌面端的插件：给左侧边栏里的每个项目一套独立的视觉身份——颜色、图标、显示名——并提供全局外观微调。

⚠️️ 实验性 / 需显式开启（0.6.0 起）：Prism 依靠向 /Applications/ZCode.app 的 app.asar 注入渲染层脚本来重整桌面端 UI，这超出了官方插件 API 的边界。因此自 0.6.0 起默认不做任何修改——安装后保持静默，直到你创建 ~/.zcode/prism-opt-in 标记；删除标记后下次会话自动恢复原始应用包。详见安装与回滚。

功能

• 项目颜色：每个项目的所有会话行染上专属色（背景叠加 + 左侧色条），跨「项目 / 分组 / 时间线」视图一致。默认不自动配色——只有手动指定的项目才染色；想要「未指定时按项目路径哈希自动分配色相」的行为，在全局开关里打开「自动配色」即可。
• 对话颜色：右键任意对话行，在原生菜单里点「调整颜色（此对话）」，可以只给这一条对话换色，覆盖项目色；「取消颜色（此对话）」一键让这条对话无色；色盘里点「透明」是同样的效果，点「自」恢复跟随项目。
• 自动化颜色：「自动化」页的每张自动化卡片默认跟随其所在项目的颜色；右键卡片（或卡片「…」菜单）点「调整颜色（此自动化）」可单独指定颜色，「取消颜色（此自动化）」/「透明」让这一条明确无色，「自」恢复跟随项目。
• 项目图标：30 个精选 Lucide 图标（从 ZCode 自带图标抽取，风格零偏差），替换项目头的 folder 图标，并跟随显示在「分组」视图每条对话行的最左侧（标题前，颜色随项目色）；home/远程项目的 house/cloud 语义图标保留。
• 项目重命名：只改 ZCode 内的显示名（别名），不碰磁盘文件夹与工作区关联。
• 侧边栏按最近活跃排序：项目、分组、时间线三个视图都生效——列表按对话的最后活跃时间排，项目/分组按各自最新对话排，最近有回复的对话始终在最上面。纯显示层重排（CSS order），不写入手动拖拽的顺序，开关关掉立即恢复原样；超过 80 项的虚拟化长列表或结构无法识别时自动不生效。
• 全局开关：压暗对话标题（60% 不透明度）、调亮思考动画（shimmer 暗侧从 20% 提到 65%，覆盖 computer-use 标签）、自动配色、按最近活跃排序。

使用

操作	入口
颜色 / 图标	右键项目标题行，或项目头 … 菜单 →「调整颜色」
单条对话换色	右键对话行 →「调整颜色（此对话）」（「透明」= 本条不染色；「自」恢复跟随项目）
自动化卡片换色	右键「自动化」页的卡片 →「调整颜色（此自动化）」（默认跟随所在项目色）
一键取消颜色	右键对话行 / 项目头 … 菜单 →「取消颜色」
重命名	项目头 … 菜单 →「重命名」（仅显示名）
任意视图换项目色	Alt + 右键该项目的任意会话行
全局开关	取色盘底部「Prism 全局」
清除颜色	色盘里的「自」（自动配色关闭时即无色，开启时回到哈希色）
状态自检	会话内运行 /status（查看 shim 安装状态与用法提醒）

所有选择即时生效；数据存于渲染进程 localStorage（zcProjectTint.* / zcPrism.settings.v1）。排查排序是否生效：打开开发者工具控制台，找 [zc-prism] recency: … 状态行（applied: … 即在工作）。

安装

要求：macOS + ZCode 桌面端（仅在 /Applications/ZCode.app 默认布局下验证过）。

本仓库根目录即一个 ZCode marketplace：

Settings → Plugins → Discover → + → Add marketplace → 填入本仓库路径（或 Git 地址）→ 安装 prism

开启（opt-in）

安装/启用插件后它不会立即修改任何东西。要让渲染层 shim 生效，创建标记文件并开一个新会话（或重启 ZCode）：

mkdir -p ~/.zcode && touch ~/.zcode/prism-opt-in

之后 SessionStart 钩子会自动把渲染层 shim 打进 /Applications/ZCode.app（后台执行，不阻塞会话）；应用自动更新后也会自动重打。shim 内容以 hash 契约校验，插件升级后下次开会话自动更新。没有标记时钩子保持静默；若发现历史遗留的补丁，会自动将其剥离并恢复原始包。

回滚

推荐：删除 opt-in 标记后开一个新会话，钩子会自动把 app.asar 恢复为未打补丁状态并刷新 pristine 备份：

rm ~/.zcode/prism-opt-in

手动方式（立即生效）：

node <插件目录>/hooks/ensure-shim.js --rollback
# 或直接换回备份：
cd /Applications/ZCode.app/Contents/Resources
mv app.asar app.asar.patched && mv app.asar.pristine-backup app.asar

插件层面：在插件列表禁用/卸载即可（shim 已打入的着色随回滚消失）。

工作原理（一句话版）

ZCode 插件系统碰不到桌面端 UI，所以 Prism 分两层：插件本体（hooks/commands，负责把渲染层 shim 安装进 app 并自愈）+ 渲染层 shim（注入 index.html 的独立脚本，负责着色/图标/别名/菜单扩展，全部防御式编码，异常只影响自身不影响 App）。安装行为受 opt-in 标记（~/.zcode/prism-opt-in）门控：无标记时不打补丁，且任何自动路径都无法绕过该检查。

安全提示：shim 具备改写应用 bundle 的能力，安装前请审阅 prism/renderer/prism.js 与 prism/hooks/ensure-shim.js——两者都很短，且只在 /Applications/ZCode.app 存在时工作。

开发

# 重新生成图标集（先解包当前 app.asar）
npx @electron/asar extract /Applications/ZCode.app/Contents/Resources/app.asar /tmp/zc-extracted
node tools/extract-icons.js /tmp/zc-extracted/out/renderer/assets icons.generated.js
# 用生成结果更新 prism/renderer/prism.js 的 ICONS 常量后：
node prism/hooks/ensure-shim.js --apply     # 按标记状态收敛（无标记只剥离不安装）
node prism/hooks/ensure-shim.js --rollback  # 无条件剥离已装 shim

• tools/fuse-check.js：检查 Electron 熔丝（Prism 依赖 asar 完整性校验未启用的前提，换机器迁移时先跑它）。
• prism/node_modules 随仓库提交，供本地开发安装就地使用 @electron/asar；市场分发不带 node_modules，钩子此时回退到 prism/hooks/asar-lite.js（零依赖实现，已与官方库在真实应用档案上做过字节级比对）。
• macOS 仅在 /Applications/ZCode.app 布局下验证过；其他平台/安装位置需改 ensure-shim.js 里的 ASAR 常量。

License

MIT（本仓库代码，全文见 LICENSE）。内嵌图标为 Lucide（ISC）path 数据。

更新日志

见 CHANGELOG.md。