# agent-link-workflow

**Repository Path**: omni331/agent-link-workflow

## Basic Information

- **Project Name**: agent-link-workflow
- **Description**: 由AI agent工作线维护：WB / KW / DSH 本机安全联系工作流、脚本与模拟测试。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-07
- **Last Updated**: 2026-11-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

由AI agent工作线维护

# Agent Link Workflow

统一维护本机 **WB（WorkBuddy）／KW（Kimi Work）／DSH（DeepSeek Harness）** 三种联系方式。仓库只包含工作流、脚本、测试与脱敏文档，不包含版权素材、真实会话清单、Cookie、token、API key、HMAC secret、消息正文或本地运行状态。

## 三条通道

| 通道 | 入口 | 用途 | 关键保护 |
|---|---|---|---|
| WB | `wb/wb-broker.mjs`、`wb/wb-send.mjs` | 固定本地 broker，经认证网关向 WorkBuddy 会话投递 | 动态端口与完整 sessionId 核验、双网关拒发、FIFO 单飞、幂等、断链不自动重发 |
| KW | `kw/kw-send.mjs` | 经 Kimi Work 本机 WebSocket 控制面向唯一会话投递 | 每次读取动态 lock、回环限制、目标唯一、完整消息回读、不输出其他会话清单 |
| DSH | `dsh/dsh-find.py`、`dsh/dsh-api-send.py`、`dsh/dsh-verify.py` | 发现本机 DSH Web，按唯一 sessionId 子串投递并做弱开工验证 | 强指纹、仅 127.0.0.1、禁止重定向、私有凭据运行时读取、无内置回退密钥 |

这些 API 都属于本机、版本相关的接口，不是稳定的公共 SDK。公开仓是**脱敏维护副本**，不会自动替换任何现役生产脚本。

## 环境与验证

- Windows。
- Node.js 22+；KW 的 WebSocket headers 形式在维护环境的 Node 24 上实测可用。
- Python 3，DSH 仅使用标准库。
- WB 单元测试使用模拟网关；DSH 单元测试使用模拟 HTTP 服务和虚构密钥，均不接触真实会话。

```powershell
npm test
```

也可以分别运行：

```powershell
npm run check
npm run test:wb
npm run test:dsh
npm run test:public
```

`tools/check_public.py` 检查常见本地状态文件和明显内嵌凭据。发布前还应检查暂存区与完整 Git 历史；不要使用 `git add -A` 代替人工核对。

## WB 快速开始

```powershell
node .\wb\wb-broker.mjs serve --port 47663
node .\wb\wb-send.mjs --list
node .\wb\wb-send.mjs "消息" --to <sessionId前缀> --request-id <稳定唯一键> --verify
node .\wb\wb-send.mjs --status <requestId>
```

详见 `wb/README.md`。broker 默认监听 `127.0.0.1:47663`，状态保存在被忽略的 `wb/state/`。

## KW 快速开始

```powershell
node .\kw\kw-send.mjs "消息" --to <标题关键词或会话ID子串> --verify
```

目标必须唯一。也可通过 `KW_KERNEL_SESSION` 和可选 `KW_WORKSPACE` 精确指定。`KW_LOCK` 可覆盖本机 lock 路径。发送会真实触发一次 Agent turn；`accepted` 只表示控制面接受，不能证明任务完成。详见 `kw/README.md`。

## DSH 快速开始

```powershell
python .\dsh\dsh-find.py
python .\dsh\dsh-api-send.py <会话ID子串> "消息" steer
python .\dsh\dsh-verify.py <会话ID子串> "消息" steer --wait=60 --cwd=<目录>
python .\dsh\dsh-verify.py <会话ID子串> --check-only --wait=60
```

DSH 默认读取 `~/.dsh/.credentials.yaml` 中的 `client-connection/browser-session.secret`。也可通过 `DSH_CREDENTIALS_FILE` 指定文件，或通过 `DSH_HMAC_SECRET` 在运行时注入。读不到有效私有密钥就拒发，没有公共回退值。详见 `dsh/README.md`。

## 验收语义必须分层

- `gateway_accepted` / `SENT` / `accepted`：服务器或网关接受，不等于模型回复。
- `observed_in_stream`、`messageCount` 增长、`running=true`、`updatedAt` 推进：会话活动的弱证据，可能与其他并发消息有关。
- 文件mtime变化：有文件活动，不证明目标产物正确。
- 模型回复、任务完成、测试通过、提交哈希、远端内容和业务产物必须由各线路专用验收器核查。

出现 `outcome_unknown` 时不得换一个新幂等键盲目重发。先复用原键查询本地记录，再结合真实消息流和产物人工核查。

## 安全边界

- 所有通道只应访问本机回环地址；不要把 token、Cookie 或签名 URL 写入文档、issue、提交或聊天。
- `wb/state/requests.json` 含明文消息正文；不要通过它发送密码等敏感内容。
- `_dsh-url.txt`、`state-root.lock`、`.credentials.yaml`、broker token 和请求记录均被 `.gitignore` 排除。
- GUI 协作锁只约束主动接入的协作者，不能阻止未接入脚本，也不承诺崩溃窗口 exactly-once。
- 不要在新旧投递入口之间并行切换同一条线路；一次只迁移一条，并保留回滚和人工核查。

## 维护流程

1. 在对应工作副本中修改，不直接编辑 Gitee 网页造成漂移。
2. 补充模拟测试，尤其是双目标、无凭据、错误端口、响应丢失和重试场景。
3. 运行 `npm test`，再检查 `git status`、暂存 diff 与敏感文件。
4. 单独提交三通道变更；真实会话 ID、运行日志和终端回执不进入提交。
5. 现役生产入口的替换由维护者另行执行，不能随公开仓同步自动发生。