deepseek-harness-agentchat

DeepSeek Harness 的 Cordis 插件，作为Lighthouse Agent 的通道桥。

DSH 主进程作为客户端主动连出：每个账号（uin）独立换票 → 拨 WebSocket 到远端 AgentChat 服务。一个 DSH 进程可同时承载 N 个账号，会话完全隔离。

目录

• 前置条件
• 快速上手
• 配置参考
• 架构说明
• 开发
• 故障排查
• Contributing
• License

前置条件

• Node.js ≥ 22.19
• pnpm ≥ 10
• 已安装并可用的 dsh CLI（来自 deepseek-harness 主仓库）

若 dsh 命令尚未安装，请先从主仓库构建：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install && pnpm build
cd apps/cli && pnpm link --global
dsh --help

快速上手

1. 安装插件

dsh plugin --profile web add deepseek-harness-agentchat

2. 配置账号

编辑 ~/.dsh/profiles/web/cordis.patch.yml，添加以下内容：

- id: agentchat-web-channel
  config:
    cwd: '/absolute/path/to/workspace'
    aiServer:
      baseUrl: 'https://lightai.cloud.tencent.com'
    accounts:
      '100032236607':
        apiKey: 'sk-xxxxxxxxxxxxxxxx'

多账号并行只需在 accounts 下追加条目：

    accounts:
      '100032236607':
        apiKey: 'sk-xxxxxxxxxxxxxxxx'
      '100032236608':
        apiKey: 'sk-yyyyyyyyyyyyyyyy'

3. 启动

dsh --profile web

使用安装脚本（可选）

项目提供了 scripts/dsh-install.mjs 脚本，可自动完成安装、配置写入和校验：

APIKEY='sk-xxxxxxxxxxxxxxxx' \
UIN='100032236607' \
DSH_AGENTCHAT_WEB_CWD="$PWD" \
SITE=cn \
node scripts/dsh-install.mjs

安装完成后可运行预检脚本验证配置：

node scripts/dsh-preflight.mjs

配置参考

配置类型定义见 src/types/config.ts，Schemastery 校验与默认值见 src/constants/plugin.ts。

必填项

字段	类型	说明
cwd	string	Agent 运行时工作目录（必须为绝对路径）
aiServer.baseUrl	string	远端 AgentChat 服务地址，如 https://lightai.cloud.tencent.com
accounts	Record<uin, { apiKey: string }>	至少 1 个账号

上游连接（aiServer.*）

字段	默认值	说明
ticketPath	/cgi/ticket	换票 HTTP 路径
wsPath	/ws/agent	WebSocket 路径
reconnectMinDelayMs	1000	重连最小间隔（ms）
reconnectMaxDelayMs	30000	重连最大间隔（ms）
reconnectInitialJitterMaxMs	10000	首次连接前随机抖动上限（ms）
reconnectJitterRatio	0.5	抖动比例（0–1）

运行时能力

字段	默认值	说明
agentPreset	—	Agent preset ID
systemPrompt	内置文本	附加到每轮对话前的 system prompt
imageInputMode	auto	图片注入策略：auto / always / never

超时与限额

字段	默认值	说明
responseTimeoutMs	300000	单轮响应总超时（ms）
approvalTimeoutMs	120000	单次审批等待超时（ms）
mediaDownloadTimeoutMs	30000	附件下载超时（ms）
sendTimeoutMs	30000	单帧下发超时（ms）
sendRetries	2	下发失败重试次数（0–5）
maxReplyChars	20000	单条回复最大字符数
maxSeenMessageIds	5000	幂等去重窗口大小
maxOutboundFileBytes	52428800	下发文件最大字节数（默认 50 MiB）

环境变量

变量	说明
DSH_AGENTCHAT_WEB_CWD	覆盖 cwd（必须绝对路径）
DSH_AGENTCHAT_WEB_BASE_URL	覆盖 aiServer.baseUrl，默认 https://lightai.cloud.tencent.com
DSH_AGENTCHAT_WEB_ACCOUNTS	JSON 字符串，如 {"100032236607":{"apiKey":"xxx"}}

架构说明

加载流程

flowchart LR
    A[dsh plugin add\ndeepseek-harness-agentchat] --> B[写入 profile\npackage.json]
    B --> C[dsh --profile web]
    C --> D[加载 cordis.patch.yml]
    D --> E[import 插件默认导出]
    E --> F[apply ctx, config]
    F --> G[N × UpstreamGateway\noutbound WS]

运行时形态

flowchart TD
    subgraph DSH 主进程
      B[AgentChatWebBridge]
      subgraph "account = uin_A"
        CA[ConversationManager A]
        GA[UpstreamGateway A]
      end
      subgraph "account = uin_B"
        CB[ConversationManager B]
        GB[UpstreamGateway B]
      end
      B --> CA & GA
      B --> CB & GB
    end
    GA -.WSS.-> R[(远端 AgentChat\naiServer.baseUrl)]
    GB -.WSS.-> R

消息链路

用户消息 → typing_start
         → conversations.handleIncomingMessage()
         → 流式 stream_chunk（无文本时 emitFallback 兜底）
         → typing_stop

开发

# 类型检查
pnpm typecheck

# 运行测试
pnpm test

# 构建（esm + d.ts + sourcemap）
pnpm build

# 一键检查（typecheck + test + build）
pnpm check

独立冒烟测试

无需拉起 DSH 主进程，用 mock 服务验证通道协议：

pnpm smoke

前端切换到 mock：在 URL 后加 ?bridge=smoke（等价 http://localhost:8787）。

故障排查

现象	常见原因	处理方式
Command 'dsh' not found	未安装 DSH CLI	见前置条件
pnpm not found on PATH	未安装 pnpm	npm i -g pnpm@10
Cannot find module '.../dist/index.js'	未构建产物	执行 pnpm build
accounts 为必填项 启动报错	未配置账号	在 cordis.patch.yml 中添加 accounts
cwd 必须是绝对路径 报错	传入了相对路径	改为绝对路径，或不传（使用默认值）
aiServer.baseUrl 为必填项 报错	未提供服务地址	设置 DSH_AGENTCHAT_WEB_BASE_URL 或在 patch 中显式配置
pnpm ≥10 报 prepare script blocked	git 依赖构建脚本被拦截	在 pnpm-workspace.yaml 中添加 allowBuilds 白名单

Contributing

欢迎提交 Issue 和 Pull Request。在提交 PR 前，请确保：

1. 通过 pnpm check（typecheck + test + build）
2. 遵循现有代码风格（ESLint + Prettier）
3. 新功能附带对应测试

License

MIT