插件合集 TGYD-helige/dsh-plugins

dsh-plugins

dsh-plugins preview

可组合、配置驱动的插件，面向 DeepSeek Harness (dsh)。每个包都是可发布的 dsh bundle：智能体需要什么就装什么，通过 Cordis 配置，dsh 本体保持不打补丁。

包

| 包 | 作用 | 主要接缝 |
| @amaster.ai/dsh-a2a | 通过 A2A 协议 1.0 对外提供 dsh 智能体服务（JSON-RPC + SSE，可选 HTTP+JSON/REST 与 gRPC，兼容 v0.3）：全部十一个标准操作、工具审批、可选的原生 inbox 执行；任务状态存储可插拔（memory/filesystem/Redis/GCS + workspace archive） | ctx.agents、session/event、approval/request、自有协议监听器 |
| @amaster.ai/dsh-storage | 把会话事件流镜像到 MySQL/PostgreSQL/SQLite/SQL Server（ai_messages / ai_chat_histories） | session/event tap（本地持久化仍是权威来源） |
| @amaster.ai/dsh-langfuse | Langfuse 可观测性：每次 LLM 调用一个 generation（外加一个嵌套的 llm-request span，内含循环构建的原始请求），每次工具调用或钩子运行一个 span，每轮一个 trace；子代理子会话嵌套在父级树之下 | llm/stream、tools/pre-execute → tools/result、session/event（含 hook/）、session/created + subagent/start/subagent/end |
| @amaster.ai/dsh-telemetry | 面向 Langfuse 或 Phoenix 的统一 OTel 追踪，覆盖请求上下文、钩子、子代理和 A2A 任务 | 共享的 llm/stream、工具、会话、钩子、子代理和 A2A 采集器 → 后端适配器 → 共享 OTLP/HTTP protobuf |
| @amaster.ai/dsh-policy | 声明式工具调用策略：配置驱动的 allow/deny/ask 规则（工具名、参数模式、按段拆分的 shell 命令前缀/正则、优先级）——Gemini CLI 风格的策略文件直接当插件配置用 | tools/pre-execute waterfall（ask 走 dsh 的审批接缝） |
| @amaster.ai/dsh-subagent-filesystem | 通过调用方的文件系统发现 Markdown 专家角色，再经由原生进程内子代理委派任务 | ctx.fs、作用域内的 ctx.tools / ctx.systemPrompt、agent/created、ctx.subagents |

插件预览

dsh-a2a
dsh-storage

dsh-langfuse
dsh-policy

dsh-subagent-filesystem
dsh-telemetry

状态

这是早期的 dsh-preview 生态。插件形态、配置 schema 和接缝选型都已就位；dsh 预发布 API 可能变动的地方，事件载荷的字段名标了 TODO(verify)。上生产前请锁定 dsh 版本，并核对这些标记。

兼容性

| @amaster.ai/dsh- | dsh | cordis | @a2a-js/sdk (dsh-a2a) |
| 0.1.x | >=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1 || >=0.2.2-rc.1（peer 下限）/ 0.2.2-rc.1（实测） | ^4.0.1（实测 4.1.0） | ^1.1.0（兼容 A2A 1.0 + v0.3） |

dsh 还在开发者预览阶段，版本之间会破坏兼容性。插件把最老的兼容 dsh 版本声明为固定的 peer 下限，每次发布都在本矩阵里记录实测的 dsh 版本；只有插件开始依赖更新的 dsh API 时，下限才会上移。安装走 dsh plugin add，只支持 pnpm —— pnpm 的 peer 匹配没有预发布门槛，任何更新的 dsh（alpha 或稳定版）都能满足下限，不会报警告。npm 用户的限制不一样：除非版本范围用预发布比较符点名了那个发布元组，npm 绝不让预发布版本满足范围，所以 peer 范围也点名了 0.1.6、0.1.7、0.2.0、0.2.1、0.2.2 这几个预发布元组。等某条线发布正式版后，就把对应的并集成员删掉。

dsh-a2a 的收件箱执行还额外测试了未经修改的官方 DSH 0.2.2-rc.1 npm 运行时。它的 agent peer 下限是 >=0.2.2-rc.1，用于通过 agent 选项做初始模型选择，以及作用域内的模型切换通知钩子。排队使用 Agent.send；不需要改核心补丁。

dsh-a2a 的可选 Goal 集成依赖 @deepseek-ai/dsh-goal >=0.2.0-rc.2 || >=0.2.1-alpha.1 || >=0.2.2-rc.1，并保留官方 Goal 轮次校验（已用 0.2.2-rc.1 的 Goal 服务和轮次驱动实测）。

dsh-a2a 的审批桥有一个可选的 @deepseek-ai/dsh-user-approval peer 下限：>=0.1.6-alpha.2 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1 || >=0.2.2-rc.1（实测于 0.2.2-rc.1）。
dsh-a2a 要求 @deepseek-ai/dsh-session >=0.2.1-rc.5 || >=0.2.2-rc.1，因为原生收件箱操作和带检查点的失效处理要用到按所有者隔离的 SessionStore.flush 持久化屏障。可选的子代理流式输出还会读取会话生命周期偏移量，用来区分新子会话和恢复的会话。

dsh-langfuse 的可选图片展示使用 @deepseek-ai/dsh-attachment >=0.2.0-rc.1 || >=0.2.2-rc.1（已在 0.2.2-rc.1 上测试）；仅做元数据追踪时不需要附件后端。

dsh-subagent-filesystem 要求 @deepseek-ai/dsh-subagent >=0.2.1-rc.2 || >=0.2.2-rc.1（已在 0.2.2-rc.1 上测试），并且需要原生进程内 spawn 服务商。它支持前台报告和可继续的后台子会话；Markdown 定义无法覆盖模型、工具或权限。

dsh-telemetry 用 OTel API 1.9.1、SDK/resources 2.10.0 和 OTLP/HTTP protobuf 导出器 0.221.0 测试同一个 dsh 0.2.2-rc.1 收集器。它不需要 Langfuse SDK。后端服务器/版本限制、项目配置和迁移见其 README；每个配置档只启用一个收集器。

安装

每个包都是 dsh bundle，自带 cordis.patch.yml。用 dsh 命令行：

dsh plugin --profile my-agent add @amaster.ai/dsh-a2a @amaster.ai/dsh-storage @amaster.ai/dsh-langfuse
dsh --profile my-agent

要从本仓库本地开发，改用 --patch 覆盖层（无需打包）：

dev.patch.yml
- insert:
- id: langfuse
name: file:///absolute/path/to/dsh-plugins/packages/dsh-langfuse

dsh --profile my-agent --patch dev.patch.yml

配置

所有插件默认禁用，通过标准 dsh 插件配置层配置（Schemastery 校验，支持热重载）。配置档 cordis.patch.yml 片段示例：

- insert:
- id: langfuse
name: '@amaster.ai/dsh-langfuse'
config:
enabled: true
publicKey: pk-lf-...
secretKey: sk-lf-...
baseUrl: https://cloud.langfuse.com
- id: storage-mirror
name: '@amaster.ai/dsh-storage'
config:
enabled: true
database:
enabled: true
provider: mysql # mysql | postgresql | sqlite | sqlserver
url: mysql://user:pass@host:3306/agent
- id: a2a
name: '@amaster.ai/dsh-a2a'
config:
enabled: true
host: 127.0.0.1 # no auth built in — keep loopback or front with a proxy port: 41241 cwd: /srv/agent-workspaces taskStore: redis # memory | filesystem | redis | gcs — A2A task state only filesystem: root: /srv/dsh/a2a-tasks redis: url: redis://127.0.0.1:6379 gcs: bucket: my-agent-archives
- id: policy
name: '@amaster.ai/dsh-policy'
config:
enabled: true
rules:
- tool: bash
decision: deny
commandPrefix: npm
priority: 200
message: 'npm is not allowed. Use bun instead.'
- tool: '*'
decision: allow
priority: 20

数据模型

dsh-storage 的关系结构与源项目的 ai_messages / ai_chat_histories 表一致，现有数据保持兼容（有一处差异：没有 user_id 列，租户归属由 session_id 承载）。运行时需要 Prisma 7 的 peer 包：@prisma/client，以及对应数据库的驱动适配器（MySQL 用 @prisma/adapter-mariadb，PostgreSQL 用 @prisma/adapter-pg，SQLite 用 @prisma/adapter-libsql，SQL Server 用 @prisma/adapter-mssql）。PrismaClient 已按服务商预生成，随包发布，不需要 prisma generate 步骤。用随包发布的 schema 变体建表或升级表：

npx prisma db push --schema node_modules/@amaster.ai/dsh-storage/prisma/schema.mysql.prisma --url "mysql://user:pass@host:3306/agent"
schema.postgresql.prisma / schema.sqlite.prisma / schema.sqlserver.prisma work the same way

SQL Server 注意：Prisma 的 sqlserver 连接器没有 Json 类型，所以该变体把 JSON 列映射为文本，后端写入时自动序列化（由 provider: sqlserver 推导；SQL Server 的 ISJSON / JSON_VALUE 仍可按 JSON 查询这些文本）。

- ai_messages —— 用户/模型行，含 thoughts、tokens、tool_calls、agent_id、metadata 等 JSON 列，支持软删除；工具结果会更新对应模型行的 tool_calls。
- ai_chat_histories —— 按会话汇总（消息数、总 token 数、首条/末条消息时间戳）。

逻辑消息 id 放在 metadata.id 里；消息行用 (session_id, message id) 的确定性哈希作主键，所以重复投影的事件会原地 upsert，不会产生重复——所有连接器都如此（源项目按 JSON 路径查 metadata.id，只在 PostgreSQL/MySQL 上有效）。会话行按 session_id 匹配，保留各自的 cuid 主键——按会话串行化的链条让「先查后写」是安全的，早期脚手架（或源项目）留下的行会被续写，不会重复。升级注意：早期脚手架用 cuid 作消息主键；如果你跑过它，先按 metadata.id 去重，再启用这个版本。

任务更新走标准 A2A 流式/订阅、快照，以及可选的官方 SDK Push Notifications。开启 pushNotifications: true 后，客户端可注册标准任务 webhook。

原生 inbox 模式需显式开启，使用官方 DSH API；已在未修改的 0.2.2-rc.1 npm 运行时上测试通过。队列、引导、暂停/恢复语义与运行时集成检查见原生 inbox 执行。
选择启用 inbox: { enabled: true, shutdown: retain-pending }，就能在宿主优雅重启后保留尚未认领的 A2A steering 和后续轮次。会话持久化和 TaskStore 存储都要保留；宿主仍会发现并唤醒符合条件的工作。显式取消和清空上下文仍是终止操作。详见关闭约定。

A2A 任务快照与完整对话日志分开存放：dsh-a2a 提供可插拔的 TaskStore 后端——内存（默认）、文件系统（私有原子 JSON 快照）、Redis（任务 JSON + TTL）、GCS（gzip 压缩的任务 JSON）。快照在任务状态转换时保留 A2A 历史和产物；dsh-storage 另行记录完整对话。流式文本增量在下次状态变更前一直留在进程内，所以 token 速率事件永远不会进入 Redis 或 GCS。Redis 和 GCS 的键按 A2A 租户和用户划分作用域；旧的无作用域记录需要迁移或等待过期。

安全

dsh 不带任何身份认证或授权。dsh-a2a 默认绑定 127.0.0.1；如果要对外暴露，请在前面加一层带认证的反向代理，并把每个智能体都当作以宿主进程的操作系统权限运行。多租户部署还需要在之上做按租户隔离（容器）。

仓库结构

packages/
├── dsh-a2a/ # A2A protocol server plugin
├── dsh-storage/ # session storage mirror plugin (+ prisma schema)
├── dsh-langfuse/ # Langfuse observability plugin
├── dsh-telemetry/ # Unified Langfuse/Phoenix tracing
└── dsh-policy/ # declarative tool-call policy plugin

开发

pnpm install
pnpm build # tsc per package
pnpm typecheck
pnpm test # vitest (packages with a test script)

当前限制

- 所有插件默认禁用；请在配置档中逐个显式启用并配置。

- dsh-a2a 不为订阅保留事件重放：SubscribeToTask 以当前任务快照开场，之后只跟随实时总线。重启后恢复 dsh 会话需要可选的 sessionPersistence 服务。
- dsh-a2a 的 GCS 存储：工作区归档（archiveWorkspace）会调用外部 tar，目前尚未接入任务生命周期。

许可证

MIT