dsh-mate

---

✨ 功能亮点

🚀 能力	说明
📶 扫码即配对	电脑终端显示二维码 / 6 位短码，App 扫码完成 HMAC-SHA256 挑战应答
💬 会话列表 + 详情	查看所有 DSH 会话，实时流式渲染 AI 回复与工具调用
🎯 决策卡片	审批（允许/拒绝）、回答问题、计划审阅，一键操作
🔔 任务通知	任务完成 / 等待决策时实时推送（WebSocket；v1.1 可选华为 Push Kit）
🛠 设备管理	查看已配对设备、重命名、吊销
🌐 局域网优先	默认 LAN 直连；跨网复用用户自建隧道，无账号依赖

---

🏗 架构

flowchart LR
    subgraph Phone["📱 鸿蒙手机"]
        A["DSH Mate App<br/>(ArkTS · HarmonyOS NEXT)"]
    end
    subgraph PC["🖥 电脑 (dsh web 进程)"]
        B["dsh-mate 桥插件<br/>(Node.js · Cordis)"]
        C["DSH 宿主<br/>(DeepSeek Harness)"]
    end
    A <-->|REST / WebSocket| B
    B <-->|Cordis 事件与服务| C
    B --- B1["配对服务 (QR/HMAC)"]
    B --- B2["HTTP :3082 REST API"]
    B --- B3["WebSocket 事件推送"]
    B --- B4["信任层 (限流/封禁)"]
    B --- B5["可选推送中继 (v1.1)"]

手机 App ◄──REST/WS──► dsh-mate 桥插件 ◄──Cordis──► DSH 宿主
                         ├─ 配对服务 (QR/HMAC)
                         ├─ HTTP :3082 REST API
                         ├─ WebSocket 事件推送
                         ├─ 信任层 (限速/封禁/会话)
                         └─ 可选推送中继 (v1.1)

💡 图表在支持 Mermaid 的 GitHub 渲染；否则展示上方 ASCII 版。

---

📂 目录结构

dsh-mate/
├── 📦 packages/dsh-mate/      # 电脑端 DSH 插件（TypeScript · Cordis）
│   ├── src/
│   │   ├── index.ts           # 插件入口（装配 + 终端二维码）
│   │   ├── config.ts          # 配置归一化与安全校验
│   │   ├── server/            # HTTP + WebSocket 服务器 + 信任层
│   │   ├── pairing/           # QR/HMAC 配对 + 设备注册表
│   │   ├── bridge/            # 宿主桥（会话/交互/作业/goal/设备/事件）
│   │   ├── push/              # 可选推送中继（v1.1）
│   │   ├── tools.ts           # 会话内工具 mate_qr / mate_devices
│   │   └── types.ts           # 类型定义
│   ├── cordis.patch.yml       # 插件装载行 + 默认配置
│   └── package.json
├── 📱 harmony-app/            # 鸿蒙 App（HarmonyOS NEXT · ArkTS 严格模式）
│   └── entry/src/main/ets/
│       ├── pages/             # 页面（配对/会话列表/详情/通知/设备/设置）
│       ├── net/               # 网络层（RestClient/EventStream/TokenStore/PairingClient）
│       ├── model/             # 数据模型
│       ├── store/             # 全局状态（AppStore 单例）
│       ├── common/            # 常量 + 工具函数
│       └── entryability/      # Ability 入口
├── 🔗 shared/protocol/        # 跨端契约（schema.json 为单一来源）
├── 🛠 scripts/                # 开发辅助脚本
├── 📖 docs/                   # 设计文档（01–10）
└── README.md

---

🚀 快速开始

前置要求

组件	版本
🟢 Node.js	≥ 20
🤖 DSH (DeepSeek Harness)	已安装并运行
🧩 DevEco Studio	6.1+（仅鸿蒙 App 开发需要）

安装

git clone https://github.com/RevolutionLA/dsh-mate.git
cd dsh-mate
npm install

🔌 电脑端插件

# 从 npm 安装
dsh plugin --profile web add dsh-mate

# 或从源码构建后安装
cd packages/dsh-mate
npm run build
dsh plugin --profile web add file:/path/to/dsh-mate/packages/dsh-mate

# 配置 — 在 ~/.dsh/profiles/web/cordis.patch.yml 追加：
#   见 cordis.patch.yml 示例

# 启动
dsh web    # 终端出现配对二维码

📱 鸿蒙 App

1. 用 DevEco Studio 打开 harmony-app/ 目录
2. 配置签名（Build → Edit Signing Config）
3. 连接鸿蒙真机或启动模拟器（API ≥ 23）
4. Run → 运行到设备

🧪 离线开发：无需真实桥，用 Mock 桥即可开发 App：

npm run mock:bridge   # 启动 localhost:3082 模拟桥

---

🔐 协议与安全

配对协议（docs/03）

sequenceDiagram
    participant App as 📱 鸿蒙 App
    participant Bridge as 🖥 桥插件
    App->>Bridge: ① 扫码 / 短码
    Bridge-->>App: ② challenge (nonce + ts)
    App->>App: ③ proof = HMAC-SHA256(secret, sid|nonce|ts)
    App->>Bridge: ④ POST /verify (proof)
    Bridge-->>App: ⑤ deviceId + sessionToken
    Note over App,Bridge: ⑥ 请求携带 Bearer / HttpOnly Cookie

🛡 安全措施

措施	说明
🔑 HMAC-SHA256 挑战应答	CryptoArchitectureKit 实现，一次性 nonce
🧩 双通道认证	Bearer Token + HttpOnly Secure Cookie
📊 IP 级限速	300 req/min + 认证失败封禁（10 次 → 5min ban）
⏳ 配对载荷 TTL	5 分钟，一次性
🚧 强制配对	非回环绑定必须启用配对，否则拒绝启动
🔁 断线重连	WebSocket ACK 协议 + 指数退避

---

🧰 开发

常用脚本

命令	说明
npm run build	🏗 构建电脑端插件
npm run mock:bridge	🧪 启动 Mock 桥（App 离线开发）
npm run dev:qr	📶 终端二维码预览
npm run check:consistency	🔍 协议一致性校验（docs vs schema vs types）
npm run test:project	✅ 项目冒烟检查

插件开发

cd packages/dsh-mate
npm run build      # tsc → lib/
npm run typecheck  # 类型检查
npm run watch      # 增量编译

鸿蒙 App 开发

项	值
📱 SDK	HarmonyOS NEXT 6.1.1(24)，兼容 6.1.0(23)
📝 语言	ArkTS 严格模式
🧱 架构	分层解耦 — model → net → store → pages
🗃 状态管理	AppStore 单例 + 多播回调数组
🌐 网络	RestClient (HTTP) + EventStream (WS) + PairingClient + TokenStore

关键设计决策见 docs/10-鸿蒙App开发实施文档.md。

协议变更流程

1. 修改 shared/protocol/schema.json
2. 同步 docs/04-移动端桥协议.md
3. 递增 protocolVersion
4. App 根据 GET /mate/v1/info 提示升级

运行一致性校验：npm run check:consistency

---

⚙️ 配置参考

插件配置写入 cordis.patch.yml 的 config 段：

字段	默认值	说明
host	0.0.0.0	监听地址
port	3082	监听端口
publicUrl	null	公网隧道 URL（写入二维码）
pairing.enabled	true	是否启用配对（非回环绑定强制 true）
pairing.ttlMs	300000	配对载荷 TTL（5 分钟）
pairing.sessionMaxAgeDays	30	会话最长寿命
pairing.deviceIdleExpiryDays	90	设备闲置回收
rateLimit.max	300	IP 限速（请求数/窗口）
rateLimit.windowMs	60000	限速窗口
authFailure.max	10	认证失败封禁阈值
authFailure.windowMs	300000	认证失败窗口
authFailure.banMs	300000	封禁时长
push.provider	none	推送通道（none / huawei-pushkit / webhook）
push.webhookUrl	—	webhook 通道 URL

完整说明见 docs/05-内网穿透与部署.md。

---

📡 REST API 速览

方法	路径	说明
🟢 GET	/mate/v1/info	协议版本 + 能力
🟢 GET	/mate/pair/challenge?sid=	获取配对质询
🟠 POST	/mate/pair/verify	提交配对证明
🟢 GET	/mate/v1/sessions	会话列表
🟢 GET	/mate/v1/sessions/:id	会话快照
🟠 POST	/mate/v1/sessions/:id/messages	发送消息
🟠 POST	/mate/v1/sessions/:id/abort	中止会话
🟠 POST	/mate/v1/sessions/:id/markRead	标记已读
🟠 POST	/mate/v1/answers	回答问题
🟠 POST	/mate/v1/approvals/:id/decide	审批决策
🟢 GET	/mate/v1/jobs	作业列表
🟠 POST	/mate/v1/jobs/:id/kill	终止作业
🟢 GET	/mate/v1/devices	设备列表
🟠 POST	/mate/v1/devices/:id/rename	重命名设备
🔴 DELETE	/mate/v1/devices/:id	吊销设备
🟠 POST	/mate/v1/me/forget	注销本设备
🔵 WS	/mate/v1/events	事件流（WebSocket）

完整契约见 docs/04-移动端桥协议.md 与 shared/protocol/schema.json。

---

🧩 技术栈

组件	技术
🖥 电脑端插件	TypeScript · Node.js · ws · Cordis
📱 鸿蒙 App	ArkTS · ArkUI · HarmonyOS NEXT SDK
🔑 配对安全	CryptoArchitectureKit (HMAC-SHA256)
🌐 协议	REST + WebSocket 事件流
🔔 推送 (v1.1)	华为 Push Kit / Webhook

---

🗺 Roadmap

• ✅ v1.0 电脑端桥插件（配对 / REST / WS / 信任层）
• ✅ v1.0 鸿蒙 App（配对 / 会话 / 通知 / 设备 / 设置）
• ⏳ v1.1 华为 Push Kit 推送中继
• ⏳ v1.1 Webhook 推送通道
• ⏳ v1.1 通知设置持久化
• ⏳ v1.1 会话内图片 / 文件预览

---

📄 License

MIT © 2026 DSH Mate Contributors