TGYD-helige/dsh-plugins

dsh-plugins

dsh-plugins 预览

面向 DeepSeek Harness (dsh) 的可组合、配置驱动的插件。每个包都是一个可发布的 dsh 捆绑包：只安装 agent 所需的部分，通过 Cordis 进行配置，并保持 dsh 本身不被修改。

包

| 包 | 功能 | 主要接缝 |
| --- | --- | --- |
| @amaster.ai/dsh-a2a | 通过 A2A 协议 1.0（JSON-RPC + SSE，带 v0.3 兼容层）为 dsh agent 提供服务：流式轮次、任务取消、任务列表、agent card；可插拔的任务状态存储（memory/Redis/GCS + 工作区归档） | ctx.agents、session/event、自有 HTTP 服务器 |
| @amaster.ai/dsh-storage | 将会话事件流镜像到 MySQL/PostgreSQL/SQLite/SQL Server（ai_messages / ai_chat_histories） | session/event 监听（本地持久化仍为权威来源） |
| @amaster.ai/dsh-langfuse | Langfuse 可观测性：每次 LLM 调用对应一个 generation（外加一个嵌套的 llm-request span，包含循环构建的原始请求），每次工具调用对应一个 span，每个轮次对应一个 trace；子 agent 子会话嵌套在父级树之下 | llm/stream + tools/execute 瀑布流、session/event、session/created + subagent/start/subagent/end |
| @amaster.ai/dsh-policy | 声明式工具调用策略：配置驱动的 allow/deny/ask 规则（工具名称、参数模式、按分段的 shell 命令前缀/正则、优先级）——Gemini CLI 风格的策略文件作为普通插件配置 | tools/pre-execute 瀑布流（ask 借助 dsh 的审批接缝） |

插件预览

dsh-a2a
dsh-storage
dsh-langfuse
dsh-policy

状态

这是一个早期的 dsh 预览生态系统。插件形态、配置 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.5-rc.1（npm） | ^4.0.1 | ^1.1.0（A2A 1.0 + v0.3 兼容） |
dsh 处于开发者预览阶段，并且会在版本之间破坏兼容性。这些插件的每个版本都在此矩阵中固定了一个经过测试的 dsh 版本；请谨慎升级。

安装

每个包都是一个 dsh bundle，并附带一个 cordis.patch.yml。使用 dsh CLI：

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 校验，支持热重载）。示例 profile 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 | redis | gcs — A2A task state only
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 对等包：@prisma/client 以及适用于你的数据库的驱动适配器（MySQL 使用 @prisma/adapter-mariadb，PostgreSQL 使用 @prisma/adapter-pg，SQLite 使用 @prisma/adapter-libsql，SQL Server 使用 @prisma/adapter-mssql）。PrismaClient 已按 provider 预生成并随包提供——无需 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 的工作方式相同

SQL Server 注意事项：Prisma 的 sqlserver 连接器没有 Json 类型，因此其变体将 JSON 列映射为文本——后端在写入时会自动对其进行序列化（源自 provider: sqlserver；SQL Server 的 ISJSON / JSON_VALUE 仍可将该文本作为 JSON 查询）。

- ai_messages — 每个投影的会话事件（用户 / 模型 / 工具）一行，包含 thoughts、tokens、tool_calls、agent_id、metadata JSON 列以及软删除。
- ai_chat_histories — 按会话汇总（消息数、总 token 数、首条/末条消息时间戳）。

逻辑消息 id 承载于 metadata.id 中；消息行使用 (session_id, message id) 的确定性哈希作为其主键，因此重新投影的事件会原地 upsert 而非重复——在所有连接器上均如此（源项目的 metadata.id JSON 路径查找仅在 PostgreSQL/MySQL 上有效）。会话行通过 session_id 匹配，并保留其 cuid 主键——按会话的序列化链使先查找后写入是安全的，且来自早期脚手架（或源项目）的行会被延续，绝不会重复。升级注意事项：早期脚手架使用 cuid 键写入消息；如果你运行过它，请在启用此版本之前按 metadata.id 对这些消息去重。

A2A 任务状态 与对话历史是不同的问题：dsh-a2a 提供可插拔的 TaskStore 后端——内存（默认）、Redis（任务状态 JSON + TTL）和 GCS（gzip 压缩的任务状态，与源项目的 GCSTaskStore 相同的对象布局）。每个后端仅持久化元数据外壳（保存前会剥离历史/产物——对话历史属于 dsh-storage），并且保存会被折叠为任务状态转换，因此流式文本增量永远不会到达后端。

安全

dsh 不附带任何身份验证或授权。dsh-a2a 默认绑定 127.0.0.1；如果你将其暴露出去，请在前面放置一个经过身份验证的反向代理，并将每个 agent 视为以宿主进程的操作系统权限运行。多租户部署还需要在此基础上进行按租户隔离（容器）。

仓库布局

packages/
├── dsh-a2a/        # A2A 协议服务器插件
├── dsh-storage/    # 会话存储镜像插件（+ prisma schema）
├── dsh-langfuse/   # Langfuse 可观测性插件
└── dsh-policy/     # 声明式工具调用策略插件

开发

pnpm install
pnpm build        # 每个包执行 tsc
pnpm typecheck
pnpm test         # vitest（带有测试脚本的包）

当前限制

- 所有插件默认禁用；请在配置文件中显式启用并配置每个插件。
- dsh-a2a 在协议边界上仅支持文本（非文本消息部分会被拒绝），没有审批/input-required 的轮次中途桥接（dsh 仅将审批接缝作为可选的 dsh-user-approval 包提供，无头配置文件不会组合它），并且不会在重启后恢复活动会话——持久化的任务外壳会保留在 Redis/GCS 中，但继续对话会启动一个新会话。订阅不会保留任何事件重放：SubscribeToTask 以当前任务快照打开，并且仅跟随实时总线。
- dsh-a2a GCS 存储：工作区归档（archiveWorkspace）会调用 tar，并且尚未接入任务生命周期。

许可证

MIT