dsh-plugins

English

个人维护的 DeepSeek Harness（DSH）插件集合，以 pnpm workspace monorepo 组织。可独立安装的插件位于 packages/*。

这是个人维护的非官方社区项目，不隶属于 DeepSeek AI 或 DeepSeek Harness 官方团队。

本 README 是用户入口，负责项目选择、安装方式和仓库结构；各项目 README 负责记录自身的具体行为和限制。安装章节会列出当前 workspace 中的插件及版本示例；实际版本、DSH 兼容关系及发布记录请以 CHANGELOG.md 和各项目的 package.json 为准。

项目总览

当前 workspace 的发布与兼容基线为 DeepSeek Harness Desktop 实际内置的 DSH runtime v0.2.0-rc.2，并保留对 v0.2.0-rc.1 和 v0.1.7-rc.2 的兼容。以后只有 Desktop runtime 实际升级后才同步插件版本；上游 Git tag 仅用于提前观察与兼容审计，不再直接触发发布。

项目关系

• 每个插件都可以独立安装、更新和卸载，不再维护组合 pack。
• Codex 用量插件读取同一份 llm-pi-ai/openai-codex 凭据；它只读凭据、不写凭据，也不自己刷新 token。
• Codex 登录插件仅用于首次登录；登录完成后即可卸载。

设计原则

• 最小依赖、最少代码：只引入完成目标所需的依赖，优先复用 DSH 已提供的服务和扩展点。
• 轻量、稳定：围绕实际使用场景提供小而明确的能力，不追求覆盖所有场景，优先控制维护成本。
• 最小侵入：插件以独立 Profile layer 接入，不修改 DSH 核心，不接管 Agent 循环、审批流程或其他主流程。
• 开放协作：欢迎社区通过 Issue 和 Pull Request 提交问题、建议、文档、测试或实现；贡献应尽量保持独立、低依赖和低侵入。
• 稳定优先：优先保持现有行为和公开契约；通知等旁路能力失败时，不应影响 DSH 主流程。
• 上游优先、可撤销：当 DSH 官方提供等价能力时，对应插件会停止维护、标记废弃并删除，而不是长期保留重复实现。

参与贡献

如果你有希望加入的能力、使用中的问题或改进建议，欢迎提交 Issue；如果已经有可行实现，也欢迎直接提交 Pull Request。新增或修改内容请尽量遵循以下原则：

• 保持功能边界清晰，不做与 DSH 主流程无关的大范围改动；
• 优先使用 DSH 已有的公开服务和扩展点，避免引入不必要的依赖；
• 同步补充必要的测试和文档，并说明验证方式；
• 尊重上游方向；当 DSH 官方提供等价能力时，及时讨论迁移或删除方案。

安装、卸载与更新

每个插件都从 GitHub 的 packages/* 子目录独立安装，不需要 clone、进入仓库或预装其它插件。桌面端安装、更新或卸载时，将命令中的 --profile web 改为 --profile desktop 即可。

安装

当前 workspace 中有以下 4 个可独立安装的插件（版本示例取自各自的 package.json）：

从当前默认分支安装单个插件：

# 系统通知
dsh plugin --profile web add 'github:zz-zhi54/dsh-plugins#path:packages/system-notification'

# Codex 登录
dsh plugin --profile web add 'github:zz-zhi54/dsh-plugins#path:packages/codex-login'

# Codex 额度
dsh plugin --profile web add 'github:zz-zhi54/dsh-plugins#path:packages/codex-usage'

# Session 费用
dsh plugin --profile web add 'github:zz-zhi54/dsh-plugins#path:packages/session-cost'

也可以一次安装全部插件：

dsh plugin --profile web add \
  'github:zz-zhi54/dsh-plugins#path:packages/system-notification' \
  'github:zz-zhi54/dsh-plugins#path:packages/codex-login' \
  'github:zz-zhi54/dsh-plugins#path:packages/codex-usage' \
  'github:zz-zhi54/dsh-plugins#path:packages/session-cost'

已安装插件需要更新时，重新执行对应的 add 命令即可；使用固定 release 时，将命令中的版本标签替换为新版本。

固定 release 时，在路径前加入版本标签。以下以当前已发布版本 v0.2.0-rc.2.2 为例：

# 系统通知
dsh plugin --profile web add 'github:zz-zhi54/dsh-plugins#v0.2.0-rc.2.2&path:packages/system-notification'

# Codex 登录
dsh plugin --profile web add 'github:zz-zhi54/dsh-plugins#v0.2.0-rc.2.2&path:packages/codex-login'

# Codex 额度
dsh plugin --profile web add 'github:zz-zhi54/dsh-plugins#v0.2.0-rc.2.2&path:packages/codex-usage'

# Session 费用
dsh plugin --profile web add 'github:zz-zhi54/dsh-plugins#v0.2.0-rc.2.2&path:packages/session-cost'

安装后检查 Profile：

dsh --profile web --dump-config

卸载

按 package name 卸载对应插件：

# 系统通知
dsh plugin --profile web remove dsh-system-notification-plugin

# Codex 登录
dsh plugin --profile web remove dsh-codex-login-plugin

# Codex 额度
dsh plugin --profile web remove dsh-codex-usage-plugin

# Session 费用
dsh plugin --profile web remove dsh-session-cost-plugin

只卸载实际安装过的插件即可。

需要某项能力时，也可以进入对应项目 README 查看更具体的行为、限制和验证步骤：

• Codex 登录插件
• Codex 用量插件
• Session 费用插件
• 系统通知插件

开发

依赖安装和检查都从仓库根目录执行，并使用 pnpm：

pnpm install
pnpm check

只检查单个项目：

pnpm --filter dsh-codex-login-plugin run check
pnpm --filter dsh-codex-usage-plugin run check
pnpm --filter dsh-codex-usage-plugin run test
pnpm --filter dsh-session-cost-plugin run check
pnpm --filter dsh-session-cost-plugin run test
pnpm --filter dsh-system-notification-plugin run check
pnpm --filter dsh-system-notification-plugin run test

根工作区没有统一的 build、test、lint 或 format 脚本；依赖解析记录统一维护在根目录 pnpm-lock.yaml。本地 workspace 保持 pnpm 默认的 peer 自动安装行为。不要在子项目中使用 npm/yarn 单独安装依赖。

仓库结构与文档分工

• packages/*/src：各插件的运行时代码。
• packages/*/cordis.patch.yml：对应插件要插入的 Profile 条目。
• CHANGELOG.md：版本、兼容关系和发布记录。
• AGENTS.md：面向编码 Agent 的项目约束，不是用户使用手册。
• dsh/：部署到用户全局 ~/.dsh/ 的 DSH 源文件，不属于 pnpm workspace。

插件通过自身 package.json 的 dsh.bundle.patch 指向 patch 文件；patch 只描述组件 ID 和 package 名称，业务实现留在对应项目中。每个插件都可独立安装，不需要组合层或递归依赖。

许可证

本项目代码采用 Apache License 2.0。第三方依赖及 DeepSeek Harness 本身仍以各自的许可证和条款为准。