dsh-matrix-agent
DeepSeek Harness（dsh）的 Matrix agent 桥接插件：把 Matrix 房间桥接到 harness agent 会话，每个房间一个会话，支持在聊天里远程监控、审批和追加指令；多分身架构 + 媒体/富文本/回复/编辑信息完整处理。
独立演进：本包由 dsh-matrix 独立而来，已断开与上游的远端关联，按自身路线演进。
src/
├── index.ts # 插件入口（name/inject/apply/Config），无 default export
├── matrix.ts # 兼容 shim：转发 @evlon/dsh-channel-matrix / @evlon/dsh-channel-core
├── tools.ts # 兼容 shim：转发 @evlon/dsh-tools-channel
└── client-main.js # 浏览器端源码（esbuild 打包为 __ModuleLoader__ bundle）：设置页（单入口+标签页：Matrix 账号/社交/时间线）+ 秘书工作台（会话头部快捷入口）
组合包：本包是「纯组合包」——桥接层（bridge/config/format/settings/store/auth-store/
member-store/chatlog/timeline/diag）已拆到独立仓库 @evlon/dsh-bridge；
通道实现 @evlon/dsh-channel-matrix、通道抽象
@evlon/dsh-channel-core、原子工具
@evlon/dsh-tools-channel 也各自独立。
本包只负责「组装」：把 bridge 挂进 cordis 组合、提供 cordis.patch.yml、以及 client 半的设置 UI。
岗位人设与秘书工作流由独立岗位仓承载：@evlon/dsh-job-pm / dsh-job-dev / dsh-job-qa /
dsh-job-leader / dsh-job-newbie / dsh-job-secretary（每仓含 agent.cordis.yml + preset.yml + SKILL.md），
开发期经 E:\ai-works\dsh-jobs\<job> junction 集合 + dsh-dev-job-install（dev_job_install 工具）落盘到 DSH_HOME；
跨岗位通用沟通规范在 communication 技能（随 dsh-dev-job-install 自带，安装任意岗位时一并落盘）。
DeepSeek Harness 版本适配
本插件链接 DeepSeek Harness（DSH）宿主运行时的以下包（作为 peerDependencies，由宿主进程提供，安装时请确保宿主版本在范围内）：
| 宿主包 | 适配的版本范围 |
|---|
@deepseek-ai/cordis | ^4.0.2 |
@deepseek-ai/dsh-agent | ^0.1.2-rc.1 |
@deepseek-ai/dsh-attachment | ^0.1.2-rc.1 |
@deepseek-ai/dsh-llm | ^0.1.2-rc.1 |
@deepseek-ai/dsh-session | ^0.1.2-rc.1 |
@deepseek-ai/dsh-tools | ^0.1.2-rc.1 |
@deepseek-ai/dsh-user-approval | ^0.1.2-rc.1 |
@deepseek-ai/schemastery | ^3.18.2 |
本包同时依赖（dependencies，非宿主提供）：@evlon/dsh-bridge（当前 ^0.1.1）、@evlon/dsh-channel-core / @evlon/dsh-channel-matrix / @evlon/dsh-tools-channel（^0.1.0）。
注意：DSH 以 rc 预发布版本按日推进，而 npm 对预发布版本的范围匹配是按 major.minor.patch 元组锚定的——^0.1.2-rc.1 只会匹配 0.1.2.* 的预发布，不会自动覆盖后续新出的 0.1.3-rc.x/0.1.4-…。因此宿主升到下一个 rc 元组时，本插件需同步把 peer/dev 范围升到对应 rc 并重新构建测试（源码兼容则发 patch；有 API 破坏则需适配后发版）。本版本号对应上面的适配范围；宿主若超出该范围（或为 alpha 不稳定快照）可能导致 peer 冲突或行为异常，请在升级宿主前先升级本插件。
alpha 说明：0.1.5-alpha.1 等 alpha 为不稳定快照，非官方发布通道，未按此适配，仅记录/可尝试使用，出现问题优先反馈。
架构
整体拓扑：每个分身一个 harness 进程
┌──────────────────────────────────────────────────────────────────────────────┐
│ Matrix 房间（每个平台/模块一个房间） │
│ │
│ 真人同事 @tianjintao 真人（Owner）@niukunliang 其他分身 @ai-liuliye │
│ （Matrix 客户端） （Matrix 客户端，仅客户端登录） （跑在自己的 harness） │
└──────────┬──────────────────────┬─────────────────────────┬──────────────────┘
│ │ │
│ 房间内对话 / @提及 / 审批「批准/拒绝」 │
▼ ▼ ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ Matrix Homeserver（im-ipm.ict.cmcc） │
└──────┬───────────────────────┬──────────────────────────┬───────────────────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Harness 进程 A │ │ Harness 进程 B │ │ Harness 进程 C │
│ │ │ │ │ │
│ userId: │ │ userId: │ │ （每个分身 │
│ @ai-niukun- │ │ @ai-niukun- │ │ 一个独立 │
│ liang │ │ liang-dev │ │ 进程） │
│ owner: │ │ owner: │ │ │
│ @niukunliang │ │ @niukunliang │ │ │
└──────┬───────┘ └──────┬───────┘ └──────────────┘
│ │
▼ ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ dsh-matrix 插件（每个进程各跑一份） │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────────────────────┐ │
│ │ 通道层 │ │ 桥接层 │ │ 授权库 │ │
│ │ @evlon/ │ │ @evlon/ │ │ @evlon/dsh-bridge │ │
│ │ dsh-channel-matrix│ │ dsh-bridge │ │ · 记忆授权（L1 静默放行） │ │
│ │ · /sync 长轮询 │ │ · 消息路由 │ │ · Owner 房间确认（L2） │ │
│ │ · send/typing │ │ @提及/私聊/兜底 │ │ · 红线强制确认（L3，每次） │ │
│ │ · 邀请自动加入 │ │ · 合并窗口 .. !! │ │ · auth-store.json 落盘 │ │
│ │ │ │ · per-room agent │ │ │ │
│ └────────────────┘ └────────────────┘ └────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────┘
身份模型
| 角色 | Matrix 账号 | 登录位置 | 职责 |
|---|
| 真人（Owner） | @niukunliang:im-ipm.ict.cmcc | 仅 Matrix 客户端 | 在房间与分身对话、应答「批准/拒绝」审批、吊销授权 |
| 数字分身 | @ai-niukunliang:im-ipm.ict.cmcc | 自己的 harness 进程 | 与真人同事、其他分身协作，执行研发/测试等工作 |
| 真人同事 | @tianjintao:im-ipm.ict.cmcc 等 | Matrix 客户端 | 在房间与分身协作（能否驱动分身由白名单控制） |
每个分身 = 一个独立 Matrix 账号 + 一个独立 harness 进程。分身账号的 owner 指向其工作责任负责人（真人），审批/吊销授权仅 Owner 可应答。
三级授权
分身请求执行工具
│
▼
┌──────────────┐ 命中红线（bash/write/edit…） ┌──────────────────┐
│ 红线检查? │ ───────────────────────────▶│ L3 强制房间确认 │
└──────┬───────┘ │ （每次都要，不入库） │
│ 未命中 └──────────────────┘
▼
┌──────────────┐ 有记忆授权 ┌──────────────────┐
│ 记忆授权库? │ ───────────────────────────▶│ L1 静默放行 │
└──────┬───────┘ └──────────────────┘
│ 无记录
▼
┌─────────────────────────────────────────────────────────────┐
│ L2 房间确认：推送审批 → 仅 Owner 回复「批准」有效 │
│ → 批准后写入记忆授权（auth-store.json），下次同类工具 L1 放行 │
└─────────────────────────────────────────────────────────────┘
能力
- Matrix → DSH：白名单用户文本经合并窗口（
.. 继续 / !! 立即提交 / 裸文本进合并窗口）后，通过 agent.followup 注入对应房间的 agent 会话；/bind <session-id> 可切换到已有会话
- 媒体处理（图片/文件/音视频/位置）：入站非文本消息自动下载（
mxc:// → /media/v3/download），保存到房间工作区 .dsh-matrix/media（或 stateDir/media）并附上本地路径；图片额外持久化为多模态 image 内容块，让模型直接看见——即使模型不支持视觉，harness 也会优雅降级为文本占位而非报错（避免旧版 read_image 工具不存在导致的 unknown tool 失败）；位置消息带坐标
- 信息完整（类人处理）：
preserveRichText（默认开）时入站消息信息不丢失——图文混排保留文字说明（caption，修复旧版丢 caption bug）、富文本（formatted_body 的链接/加粗/代码块/列表）注入结构注记、回复引用（m.in_reply_to）注入被回复原消息上下文、编辑（m.replace）标记为最新版并在聊天记录里去重替换；设为 false 回退纯文本旧行为
- 17 个 Matrix 工具（经
ctx.tools.register 注册，模型可见且可直接执行）：成员/消息/房间/用户查询、主动发送、媒体下载、自我时间线、工作目录/工作区文件、请示/汇报/秘书回传、澄清提问（详情见下方「Matrix 工具」）
- 主动消息：agent 可主动私聊、向房间发消息、@成员（
matrix_send_dm/send_room_message/mention_member）；首用经 Owner 审批记忆授权（proactiveSendRequiresApproval），或配置关闭直接允许
- 房间事件：入群/离群/邀请/改名换头像/房间名/主题变化经
onRoomEvent 投影，notifyRoomEvents 开启后注入 agent 会话（供主动打招呼等）
- DSH → Matrix：监听
session/event，把 assistant/message 的可见文本分段（前缀 （i/n） 参与长度收敛）后以 org.matrix.custom.html 发回；turn/start 显示 typing
- 数字分身架构：每个分身一个 harness 进程——
userId 即分身账号（bot 自己登录），owner 是真实人账号（仅在 Matrix 客户端登录）。分身与真人同事、其他分身在同一房间协作；@提及路由、私聊判定、多账号协调（可选 digitalTwins 同进程跑多分身）均已支持
- 三级授权：
- L1 记忆授权：非红线工具此前被批准过 → 静默放行（
auth-store.json 持久化）
- L2 即时确认：房间推送审批，配置了
owner 的账号仅 Owner 可应答，批准后写入记忆授权库
- L3 红线强制：命中
redlineTools（默认 bash/pwsh/write/edit）→ 每次都必须确认，批准永不入库
- 命令：
Matrix 工具
matrixTools: true（默认）时经 ctx.tools.register 注册以下 17 个工具，agent 既能看见 schema 也能直接调用执行体：
| 工具 | 说明 |
|---|
matrix_get_room_members | 取房间成员名单（含显示名/头像 URL） |
matrix_get_recent_messages | 取房间最近 N 条消息（正序，按需回溯上下文） |
matrix_get_room_info | 取房间基本信息（房间名、人数、是否私聊等） |
matrix_get_user_info | 取指定用户的显示名与头像 |
matrix_send_room_message | 主动向房间发文本/HTML 消息（受交付门禁：需 Owner 批准） |
matrix_send_dm | 主动给指定用户私聊（自动复用既有 1:1 房或 create-room+invite） |
matrix_mention_member | 发消息并 @ 一个或多个成员（HTML m.mention 锚点 + @名字 文本兜底，校验目标都是房间成员；受交付门禁） |
matrix_list_rooms | 列出已加入房间及名称/成员数 |
matrix_get_media | 下载 Matrix 媒体（mxc://）为本地文件并返回路径，或返回 base64 |
twin_timeline | 查自己的跨房间时间线（仅结构化元数据：回复/工具/主动消息/自我介绍/审批/任务），回忆自己在别处做过的事，防脑裂 |
matrix_ask_requester | 任务没说清楚时，在群里 @ 派活的同事澄清需求（指哪个项目/范围/验收标准）。不受交付门禁——它只问需求、不交付成果；问「这事该怎么干」请改用 matrix_request_owner_decision |
matrix_set_room_cwd | 把房间绑定到工作目录（绝对路径，校验存在性） |
matrix_request_owner_decision | 私下向 Owner 请示（情形 2：不知道怎么做 → 问主人）；超时转「挂起待答」，晚答复唤醒 |
matrix_report_owner | 私下向 Owner 汇报结果，等「交付/批准」 |
matrix_reply_worker | 秘书回传决策给 worker（仅秘书会话可调） |
matrix_list_workspace_files | 列出工作目录下的文件（发现原始数据） |
matrix_read_workspace_file | 读取工作目录下文件内容（UTF-8） |
疑问该问谁（两条路径，别问错人）：
| 情形 1：任务没说清楚 | 情形 2：不知道怎么做 |
|---|
| 问的是 | 任务是什么（指哪个项目/范围/验收标准） | 这事该怎么干（方法/取舍/优先级/风险） |
| 谁能答 | 只有派活的同事 | 只有 Owner |
| 用什么 | matrix_ask_requester（群里 @ 他） | matrix_request_owner_decision（私聊） |
matrix_ask_requester 刻意不走交付门禁：交付门禁保护「对外承诺产出」（结果/报告/结论）须 Owner 把关，而需求澄清只有派活人能答、Owner 无从代答——若也要求批准，疑问只能憋在内部（与 communication 技能红线冲突）。详见 bridge.ts approveProactiveSend 的 clarify-exempt 分支与 tests/ask-requester-gate.selftest.mjs。
主动发送类工具（matrix_send_dm/send_room_message/mention_member）isConcurrencySafe=false（防并行重复发送），首用经 proactiveSendRequiresApproval 控制。
为什么通道层不用现成 SDK
matrix-js-sdk 的 Node ESM 导入在 v42 是坏的（oauth 模块的目录导入，官方建议用户自己上 bundler）；matrix-bot-sdk 的 E2EE 原生二进制依赖被 pnpm 默认拦截的 postinstall 下载。而 dsh 插件运行在 dsh 自己的 Node 进程里，两者都不合适。因此通道层参照 telegram 插件自写客户端的做法，用 fetch 直连 client-server API（sync / send / typing / join 四个端点），零运行时协议依赖，dsh plugin add 安装无需任何构建授权。
安装
# 从本仓库 checkout 安装到 profile（dsh.bundle 声明自动加入组合层）
dsh plugin --profile web add .
# 或 git 安装（需要 pnpm 允许该包的 prepare 构建脚本，见 dsh 官方 publish 教程）
dsh plugin --profile web add github:you/dsh-matrix
# 验证
dsh --profile web --dump-config | grep matrix
git 安装拉的是源码：本包 prepare 脚本用 tsc 从 src/ 构建出 lib/，pnpm ≥10 首次 add 会因未授权构建脚本失败，把提示的包键加进该 profile 的 pnpm-workspace.yaml 后重试：
allowBuilds:
dsh-matrix: true
也支持 npm 发布 / pnpm pack tarball，两种都不需要构建授权。
配置
在 profile 的 cordis.patch.yml 行上覆盖（整个 config 值替换，不深合并）：
| 字段 | 默认 | 说明 |
|---|
homeserverUrl | 必填 | homeserver 的 client-server API base URL |
accessToken | '' | 分身 access token；为空回退环境变量 DSH_MATRIX_TOKEN，两者都缺则插件加载失败 |
userId | 必填 | 本进程登录的数字分身账号，如 @ai-niukunliang:example.org |
owner | '' | 工作责任负责人（真人账号，仅客户端登录）；设置后审批/吊销仅其可应答 |
respondToAll | true | 响应房间所有消息；设为 false 则仅 @提及/私聊 响应 |
allowedUserIds | [] | 白名单；为空且 allowAllUsers=false 时拒绝所有人（fail closed） |
allowAllUsers | false | 允许任意用户（仅开发用） |
provider | deepseek-official | 每个房间 agent 的 LLM provider |
model | deepseek-v4-flash | 每个房间 agent 的模型 |
agentPreset | standard | room agent 挂载的 agent preset（决定工具集与角色提示）；留空则无工具 |
chunkMaxChars | 4000 | 出站单条消息字符上限（含分段前缀） |
mergeTimeoutSecs | 5 | 裸文本合并窗口（秒） |
approvalTimeoutSecs | 300 | 审批推送后等待聊天答复的秒数 |
stateDir | .dsh-matrix | 状态目录（state.json 房间映射 + 去重 + sync token） |
maxRetriesBeforeAbort | 5 | 同一房间 turn 内 LLM 受限自动重试达到该次数时主动 cancel 止损 |
retryCircuitBreakerEnabled | true | 是否启用重试熔断兜底 |
digitalTwinMode | false | 可选：同一进程挂载多个分身（见下方示例） |
digitalTwins | [] |
社交记忆配置：
| 配置 | 默认 | 说明 |
|---|
autoIntroduce | true | 自己入群后是否主动 @ 成员做自我介绍 |
maxSelfIntroMentions | 20 | 自我介绍 @ 人数上限（超出截断并附「等 N 人」） |
memberMemory | true | 是否记住成员资料（join/profile/消息 upsert，落盘 member-memory.json） |
autoGreet | true | 新成员（含其他数字人）入群时是否提示 agent 主动打招呼了解对方 |
selfIntroTemplate | 模板 | 自我介绍模板；{{userId}}/{{role}}/{{owner}} 占位符可替换 |
配置示例
推荐：每个分身一个 harness 进程（单账号模式）
# 分身 @ai-niukunliang 的 profile 配置
userId: '@ai-niukunliang:example.org' # 本进程登录的分身
accessToken: '...' # 分身的 token（或 tokenEnv 环境变量）
owner: '@niukunliang:example.org' # 真人账号（仅客户端登录）：审批仅其可应答
respondToAll: true # 参与房间协作，响应所有消息
allowAllUsers: false # 生产建议用白名单 fail closed
allowedUserIds: ['@niukunliang:example.org', '@tianjintao:example.org']
可选：同一进程挂载多个分身（digitalTwinMode）
digitalTwinMode: true
digitalTwins:
- userId: '@ai-niukunliang-pm:example.org' # 分身账号（需预先注册并取得 access token）
tokenEnv: 'DSH_MATRIX_AI_NIUKUNLIANG_PM_TOKEN' # 从环境变量读 token（推荐）；或直接 accessToken
owner: '@niukunliang:example.org' # 工作责任负责人：仅其可在房间应答审批
role: 'pm' # 角色标签（展示用）
respondToAll: false # 默认仅 @提及/私聊 响应；true 则响应所有消息
provider: '' # 留空回退顶层 provider/model
model: ''
每个分身独立 sync 循环、独立状态文件（<stateDir>/twins/<localpart>.json）、独立 per-room agent 会话；审批按「分身×房间」维度记录记忆授权，Owner 变更不影响其他分身。
使用
- 真实人在 Matrix 客户端登录自己的账号（如
@niukunliang），把它加进目标房间
- 每个分身账号各启动一个 harness：
dsh --profile <分身profile>，插件自动加入房间（邀请自动接受）
- 房间里 @提及 分身即可让它干活；分身要执行红线工具时会推送审批，Owner 在客户端回复「批准/拒绝」（超时按 unavailable 处理）
- 常用命令：
/status（看会话）、/auth list（看记忆授权）、/auth revoke <tool>（吊销，仅 Owner）
dsh plugin --profile web remove dsh-matrix 卸载；组合层变更需重启 dsh 进程（不参与 HMR）
安全红线
- Matrix 通道等于绕过本机批准体系：approval 应答必须来自白名单 sender 且对应本房间真实 pending 的审批
- 聊天内容只能进会话流（
source.kind = 'plugin'），绝不允许直接执行 shell
- access token 不进日志、不落盘；
state.json 不包含任何聊天内容
开发
corepack pnpm install
corepack pnpm test # tsc + node --test（format 单测 + 假 homeserver 端到端）+ esbuild 打包 client
corepack pnpm build # tsc（lib/ 产物）+ esbuild 打包 src/client-main.js → lib/client.js
改完代码必须重新 build 并重启 dsh 进程（ESM 缓存 + web bundle 重新扫描）。
Client 半构建约定：dsh web 的 client-modules 加载器要求 exports["./client"]
指向 window.__ModuleLoader__.load({ id, factory }) 注册格式的自包含 bundle。
本项目用 esbuild 打包：src/client-main.js（ES module 源码，import React）
→ CJS bundle → banner/footer 包装成 __ModuleLoader__.load 格式 → lib/client.js
（见 scripts/build-client.mjs）。react 外部化（dsh 模块系统的 shell seed，
由 factory(require) 注入，避免与 shell 的 React 实例冲突）；其余代码内联自包含。
构建后自动 node --check 语法自检。改 client 半时改 src/client-main.js，不要改
lib/client.js。
测试系统（独立仓库 twin-test-system）
数字人行为测试系统已迁出为独立仓库 twin-test-system：
连真实 Matrix homeserver，模拟多个群 + 多个 AI 同事（LLM 扮演），对运行中的数字人发起
真实对话，实时网页查看过程、断言评估、出测试报告——支撑「设计 → 开发 → 测试 → 改进」闭环。
- 多群 + AI 同事：同时跑多个测试房间（群），每房间独立对话循环；OpenAI 兼容 LLM 扮演同事
（角色 persona + 房间上下文 + 测试目标），动态发言、追问细节
- 实时网页：SSE 推送房间列表 + 对话流（同事↔数字人气泡）+ 状态徽标（进行中/完成/失败）
- 干预控制：每房间暂停/继续/跳过等待/停止/换同事/注入消息，全局全部暂停/继续/停止
- 场景生命周期：Web 顶部场景下拉 + 开始/重新开始/停止（stop 清空、重跑 run 计数 +1）、单房间重跑
- 断言引擎：场景房间定义断言（
twin-replied/twin-responded-in-time/twin-mentioned-colleague/
message-count/twin-sent-dm/boss-approved/task-delivered/custom），房间跑完自动评估，
房间卡显示 ✔/✘ 徽标、对话流逐条显示、聚合场景报告——失败的断言即改进清单，改完插件点「重新开始」重测
- 秘书流程场景：
task-flow 场景 + BossAgent（模拟老板：监听数字人私聊，「任务请示」→批准、
「交付确认」→确认交付）——数字人侧把 twinModeRoomPrefix 设为测试房间前缀即可在测试房间开秘书编排
- 仓库位置：
E:\ai-works\twin-test-system（独立 git 仓库；原 dsh-matrix-agent/test-system 子目录已移除）
已知限制与路线图
- 仅非加密房间：
m.room.encrypted 事件只提示不支持（E2EE 二期：Rust crypto + 设备验证）
- 媒体已支持，但无 OCR/转写：图片/文件/音视频会下载落盘并作为多模态附件/路径交给 agent；暂不内置 OCR、音频转写、视频抽帧等解析（可用 agent 自身能力或外部工具处理已保存的文件）
- 不流式推送工具进度：每条
assistant/message 一条（或多条分段）消息
- 仅长轮询：无 appservice/webhook 模式，主机需可出站访问 homeserver
