Skip to content

dsh-session-flags

Verified

dsh-session-flags · v0.1.0 · MIT · Web UI

Colored, user-named flags for DeepSeek Harness session lists — mark important sessions and find them fast.

Install

dsh plugin add dsh-session-flags

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Creators

Readme

dsh-session-flags

彩色旗标

为 DeepSeek Harness 的会话列表提供可命名颜色的彩色旗标。
标出重要会话,给每种颜色起自己的名字,并在侧边栏的可搜索面板里随时找回它们。

English | 中文

Stars Forks License: MIT npm DeepSeek Harness 0.2.1-rc.2

Platform Bilingual PRs welcome

旗标不是置顶:置顶会改变列表顺序,旗标只是给会话加上标签。你可以用一种颜色表示「等我处理」,另一种表示「重构中」,第三种表示「明天再看」——并且把颜色名改成自己的工作语言。

功能亮点

  • 每个标旗会话行都有彩色旗标。 会话行处于空闲状态时,标题前的前导位会显示一枚小旗标;当会话需要关注时,行自身的状态点优先显示。
  • 悬停一键设置。 会话行悬停条的旗标按钮一步可达;空心状态可以一眼区分出未标旗的行。
  • 会话「…」菜单里的「设置旗标」。 位于「分叉会话」与「归档会话」之间,图标展示当前颜色。
  • 颜色可命名。 八种调色板颜色都可以重命名,名字会出现在悬停卡片、选择器和菜单里,让颜色体系承载你自己的词汇。
  • 可搜索的「旗标会话」面板。 侧边栏面板行打开一个页面,按颜色分组展示所有已标旗会话,显示颜色名,并可跳回对应会话;搜索同时匹配会话标题、工作区和颜色名。
  • 中英双语界面,跟随 GUI 语言切换。
  • 持久、本地、私密。 旗标保存在 DSH 主目录下的一个 JSON 文档里,由插件的宿主半端管理;不联网、不上报、不修改会话本身。

界面截图

标旗会话行 + 颜色名 选择旗标颜色 重命名颜色
带颜色名 chip 的标旗会话行 旗标颜色选择器 重命名每种颜色
「旗标会话」面板
按颜色名分组的旗标会话面板

环境要求

  • DeepSeek Harness Desktop(或 Web GUI)0.2.1-rc.2。包内声明了 engines.dsh: ">=0.2.0-rc.2",命名安装会先按该范围做兼容性预检,再交给包管理器。
  • 这是一个普通的独立 DSH 插件包(宿主半端 + 客户端浏览器 bundle),安装进 profile,而不是装进应用本体。

安装

从 npm 安装

已发布为 npm 包 dsh-session-flags:

# 先做兼容性预检(engines.dsh),再由包管理器安装;
# profile 重组时会自动把新 bundle 加入启用列表,无需第二步。
dsh plugin --profile desktop add dsh-session-flags

在 GUI 里等价于 插件 → 添加插件,输入 dsh-session-flags。无论哪种方式,安装后都要重新加载 profile——重启 Harness,让新的客户端 bundle 注册。官方 DSH Desktop 建议使用应用自己的 Settings → Plugins 页面:该 profile 归应用的插件管理器所有,运行中的 CLI 无法修改它。

从本地仓库安装

pnpm install
pnpm build          # 生成 lib/index.js(宿主)与 lib/client.js(客户端 bundle,CJS ModuleLoader)

dsh plugin --profile desktop add file:/绝对路径/dsh-session-flags
# 或使用干净的隔离 profile:
dsh plugin --profile flags-dev add file:/绝对路径/dsh-session-flags

重启 Harness 并打开 插件 页——bundle 与 dsh-session-flags 行应处于启用状态。profile 补丁层(cordis.patch.yml)会通过包的 dsh.bundle.patch 字段自动应用。

从 tarball 安装

pnpm build
pnpm pack            # 生成 dsh-session-flags-0.1.0.tgz("files" 已包含 lib/)
dsh plugin --profile desktop add /绝对路径/dsh-session-flags-0.1.0.tgz

插件市场

第三方插件的收录独立于 npm。社区 dsh-market 读取策展目录 awesome-dsh-plugin:收录就是在该仓库提一个 PR,添加 data/plugins/<owner>__<repo>.yml,市场应用会从该目录读取(通常在 PR 合并后一天内出现)。具体的投稿文件与发布清单见 docs/releasing.md。

官方 Harness 不内置插件市场。可选的 自定义插件市场 bundle(@deepseek-ai/dsh-experimental-plugin-market-bundle)会提供 Discover 标签页,由用户自行添加市场索引源;社区目录以 format-1 索引形式发布在 https://cdn.jsdelivr.net/npm/dsh-plugin-catalog/index.json。从 插件 → More → Experimental plugins → Custom plugin markets 开启后,添加该索引源即可搜索 dsh-session-flags。开启后,Agent 也能通过只读的 plugin_market 工具浏览同样的索引。

使用方式

位置 作用
会话行前导位 会话空闲时显示旗标颜色(需要关注时状态点优先)。
会话行悬停条 旗标按钮 → 打开 设置会话旗标 对话框。
会话「…」菜单 → 设置旗标 同一个对话框,无需悬停即可到达。
会话悬停卡片 彩色圆点 + 当前颜色名。
对话框 → 管理旗标颜色 重命名八种颜色;清空名称则回退到本地化默认名。
侧边栏 → 旗标会话 可搜索页面,按颜色名分组展示全部标旗会话;搜索匹配会话标题、工作区或颜色名。
面板行悬停 → × 不打开会话即可清除该会话的旗标。
面板标题 → 管理颜色 在列表旁直接打开颜色名管理器。

选择「无旗标」即清除旗标。确认后立即保存;宿主拒绝写入时,对话框会显示错误而不是关闭。

实现方式

src/
  shared/         两个半端共享的调色板与 RPC 协议
  host/           Cordis 插件:持有 flags.json,注册精确 Fetch 路由
  client/         Cordis 插件:文案、样式、slot 贡献、对话框
  index.ts        重导出宿主入口
  client/index.ts 客户端 bundle 入口(ModuleLoader 工厂)

宿主半端(name / inject / apply)。只依赖 ctx.connection,用 ctx.connection.fetch.register 在 /api/dsh-session-flags 下注册三条精确 Fetch 路由(state、set-flag、color-names),响应采用 Connection 约定 { ok: true, value } 或 { ok: false, error: { code, message } }。文档采用原子写入(临时文件 + rename)并串行化变更,并发 UI 操作不会丢写。

客户端半端。 注册一个 locale 命名空间、一个 <style data-plugin-css> 元素,以及六个 slot 贡献:

Slot 条目
sidebar.session.row.leading FlagMark — 前导位的彩色旗标 glyph
sidebar.session.row.hover FlagHoverTag — 悬停卡片里的圆点 + 名称
sidebar.workspaces.session.row.action FlagRowAction — 悬停条里的旗标按钮
sidebar.workspaces.session.menu.item FlagMenuItem — 「设置旗标」菜单行
shell.overlay FlagDialog — 选择器 + 颜色名管理器
sidebar.panellist FlagPanelIcon — 旗标会话面板的侧边栏入口

六个贡献都通过 ctx.slots.inject 注册:slot 声明后自动出现,插件卸载时随之销毁。状态通过两个可观察源(FlagsStore、DialogStore)以 hooks 形式交给框架,每个席位因此获得带类型的 useFlags(selector) / useDialog(selector) 钩子——无需跨 slot 导入。

面板是第七个贡献:在布局 main slot 中以 keyed 条目的形式挂在面板 id dsh-session-flags 下。侧边栏行与页面共享该 id(panellist 的 list id 会对应同名 main 面板)。页面通过框架标准 selector hooks 读取会话与工作区控制器快照,与旗标文档一起交给纯函数 buildFlagPanel(有单元测试)投影,再通过 Workspace UI 服务(uiWorkspace.openSession)完成跳转。该服务通过 ctx.inject 软注入,因此没有工作区 UI 的 profile 仍保留所有行内旗标功能。

为什么由宿主存储。 Desktop 宿主以 --port 0 启动 dsh,每次启动的 GUI 都是不同的 loopback origin;浏览器 localStorage 文档会随启动丢失。DSH 主目录下的 JSON 文件在多次启动、多窗口和 Web/TUI 客户端之间保持稳定。

样式以纯 CSS 注入为 <style data-plugin="dsh-session-flags" data-plugin-css="dsh-session-flags/flag.css">,界面控件统一读取 --dsw-* 主题 token(与官方客户端包一致),不引入 CSS 运行时依赖。唯一例外是旗标颜色:它属于用户数据,用持久化的 hex 直接绘制。

开发

pnpm install
pnpm typecheck     # tsc --noEmit(strict、noUncheckedIndexedAccess)
pnpm test          # vitest:调色板、宿主存储、客户端 store、对话框状态机、面板投影、SSR 席位
pnpm build         # tsdown:lib/index.js(ESM,宿主)+ lib/client.js(CJS ModuleLoader)
pnpm dev           # tsdown --watch

客户端 bundle 是 CommonJS ModuleLoader 工厂(window.__ModuleLoader__.load({ id, factory })),react、react/jsx-runtime 与 @deepseek-ai/* 保持 external,由运行中的 Harness 解析——与官方客户端包和其他第三方插件的形态一致。dsh.client.inject 声明 bundle 期望先加载的客户端服务/包。

兼容目标:官方包以 0.2.1-rc.2 作为 devDependencies 固定类型来源;唯一运行时 peer 是 @deepseek-ai/cordis ~4.0.5(可选,由宿主 loader 提供)。engines.dsh 声明支持的宿主范围(>=0.2.0-rc.2),命名安装的预检也以它为准。缺少 slot 或服务时插件会静默降级(不显示旗标、不弹对话框),而不是给宿主或应用打补丁。

数据位置

$DSH_HOME/session-flags/flags.json($DSH_HOME 默认为 ~/.dsh)。宿主通过 Harness 的 dshHomePath 服务解析目录。文档结构:

{
  "version": 1,
  "flags": { "<session-id>": "red" },
  "colorNames": { "red": "重点项目" }
}

未知字段和非法 id 会在加载时丢弃,因此文件局部损坏不会阻塞功能。

发布

npm 发布、GitHub/目录收录与市场发现步骤见 docs/releasing.md。

许可证

MIT © 2026 qingfengzxr