14 KiB
14 KiB
Repository Guide for Agents
定义编码 Agent 在本仓库工作的边界、结构、门禁、架构不变量、测试与文档规范。
- 版本与依赖:不硬编码版本或构建号,以根及各包
package.json、dsh-plugin.json、apps/android/app.json与pnpm-lock.yaml为准。 - 兼容与待办:兼容基线见 compatibility.zh.md(EN);待办与限制见 TODO.md。
- 协议权威:线协议以 protocol.md、
packages/protocol与fixtures/为准。
Repository Boundary
已实现
packages/plugin:DeepSeek Harness Plugin(Remote Host、本地工作区入口、Remote Agent Tools、ds-harness-remoteCLI;无可见 Client 模式)。packages/tui&packages/tui-plugin:packages/tui为同版本独立发布的ds-harness-remote-tuiHost 组合包(装配官方 API 并调applyTuiHost)。packages/tui-plugin为未发布开发与契约校验包。
apps/android:Expo SDK 57 客户端(官方 Typert、codex.app.*、agent.acp.*、plugin.route.call、9 语言;见 Android Guide)。apps/vscode:VS Code 扩展 Client。apps/browser:Chrome/Edge MV3 启动器(换独立凭据开同源 Remote Web,无登录/传输/会话 UI)。packages/{protocol,crypto,webrtc,client-core}&fixtures/:共享协议/加密/传输/客户端库与一致性向量。apps/server:最小自部署 Server(单账号环境变量、JSON 凭据与 refresh 恢复、Noise/Control 盲转发、可选 WebRTC/TURN、密文 Relay、Web 登录/状态页、Docker/Compose)。examples/mock-host:冻结的旧协议互操作工具,不加新功能。
禁止实现
- 多账号 Server、Remote Web 会话 UI、Admin 前后端、数据库/migration/队列、K8s/Terraform,及
apps/server-web、apps/web或空 Web/UI 目录。 - 禁把 server.md 完整站点设计写为
apps/server已实现能力(须保留该文档与protocol.md)。
Project Structure & Packaging Boundaries
apps/ android/ browser/ server/ vscode/
packages/ plugin/ tui/ tui-plugin/ protocol/ crypto/ webrtc/ client-core/
examples/ mock-host/
fixtures/ crypto/ pairing/ protocol/
scripts/ install.sh、bundle/WebRTC/场景/基准校验
docs/ README.md、protocol.md、compatibility*.md、TODO.md、CHANGELOG.md、design/
- 同名包过滤:
packages/tui(无scripts)与packages/tui-plugin(test跑packages/tui-plugin/scripts/verify-bundle.mjs校验 16 个@deepseek-ai/*固定版本与inject契约)同名ds-harness-remote-tui,pnpm --filter须用./packages/tui或./packages/tui-plugin。 - 根包边界:
- 根
package.json与dsh-plugin.json为 DSH Desktop GitHub 安装边界,须留dsh.bundle.patch、Host/Clientexports、CLIbin与根cordis.patch.yml。 - 根
package.json严禁设scripts、private: true或repository.directory。
- 根
- npm 发布:仅由 Release 在
packages/plugin执行(校验五处版本及versionCode === buildNumber一致),禁根目录npm publish。 - 提交产物:
- Git 仅允许提交
packages/plugin/dist/{index,client.github}.js(另留index.js、packages/plugin/bin/ds-harness-remote.js;client.js忽略但verify-dsh-plugin.mjs会校验)。 locale/README.*.md与packages/plugin/locale/README.*.md须保持字节一致。
- Git 仅允许提交
- Host 内联闭包:
- 内联全部运行时依赖(
ws、qrcode、schemastery、werift;werift置devDependencies,ESM banner 用局部createRequire禁改全局)。 - 裸 import 仅留
@deepseek-ai/dsh-client-connection(及可选@roamhq/wrtc)。 - esbuild 统一模块路径标签;改插件或共享包后必过 verify-dsh-plugin.mjs、verify-packed-webrtc.mjs 与
git diff --exit-code。
- 内联全部运行时依赖(
Development & Verification
环境:Node.js >=24.9、pnpm@9.15.4(Android 原生另需 JDK 17 与 Android SDK)。
pnpm install --frozen-lockfile
pnpm --filter './packages/**' -r build
pnpm -r check
node scripts/verify-dsh-plugin.mjs
pnpm -r test
NODE_ENV=production pnpm --workspace-concurrency=1 -r build
node scripts/verify-packed-webrtc.mjs
git diff --exit-code -- packages/plugin/dist/index.js packages/plugin/dist/client.github.js
- Fresh clone 先建
./packages/**;全仓生产构建必加--workspace-concurrency=1(防 Android prebuild 与 Plugin 打包并发竞争)。 apps/server独立验证前先建@dsh-remote/protocol,禁交apps/server/data/与.env。apps/android的check/test会执行build:renderers写忽略目录src/generated/。- 安装入口仅维护 install.sh(无 Windows 或自动卸载脚本):
- macOS 非 root 复用 Desktop launcher 或 CLI,不装服务。
- Linux 需 root,管
/opt/ds-harness-remote与ds-harness-remote-<profile>.service;遇运行/启用中的旧归属服务拒绝继续,不碰未知服务与系统 Node/PATH,且须明示终端具备 root 权限。
Architecture & Implementation Rules
1. 线协议、加密与信任边界
- 线协议以 protocol.md 为权威,变更同步 schema、
fixtures/与消费端。 - 业务仅经
Noise_IK_25519_ChaChaPoly_SHA256加密通道(SecureMessageCodec48 KiB 分片 / 4 MiB 上限)传输。 - 明文、未知
connection、错 target、重放与 identity 不匹配均 fail-closed;Server membership 与 Host 本地 trusted peer 须同时成立。 apps/server只盲转发(零解密):- 按配置返回
transport.{lan,p2p,turn,relay}交集,每连接 ≤256 ICE,建链后忽略迟到信令。 DSH_SERVER_TURN_URLS与DSH_SERVER_TURN_SECRET须成对配置并签短期 coturn HMAC 凭据。- refresh 丢响应恢复以旧 bearer 作 HMAC 密钥派生后继 pair,磁盘仅存摘要与元数据;再次轮换拒祖先且不撤现凭据,损坏返
503。
- 按配置返回
AdaptiveTransport仅重试 Server 精确4001 / CONNECTION_FAILED并重握 Noise。- Client GET 遇
401至多刷新重试一次,禁重放 mutation、审批或终端输入。 - Token、私钥、配对码、二维码、Prompt、源码、隐私路径与工具/终端输出禁写日志。
2. 网络监听、Loopback 控制与本机自升级
- Plugin 不监听公网,仅两处受限监听例外:
- Desktop Client 监听
127.0.0.1随机端口承载loopback.ports预览(Host 只出站连127.0.0.1白名单,禁公网/任意目标/CONNECT/通用 TCP 转发)。 - Host
workspace.upload.lan.v1仅在本机非回环 RFC1918 IPv4 临时监听,凭 10s 一次性票据升级并绑定 connection/device key/session/upload。 - LAN 上传 Client 锁死 RTC 选中 IPv4(禁 DNS/公网/loopback),父连接关/替即销毁监听器与临时文件。
- Desktop Client 监听
- Host 控制路由限 loopback
/ds-harness-remote(Web SSE 用相对路径保代理前缀)。 client.authorization.status纯只读不刷新不联网;loopback 错误须保留details.remoteCode与code。settings/update|replace|mutate禁远程改ds-harness-remote/dsh-remote;启动仅自动禁用自有@dsh-remote/plugin,严禁误禁他人dsh-remote。- 本机版本检查与升级:
- 启用且有
connection时每 24h 并发竞速npmjs.org与npmmirror。 plugin.update仅在listBundles标update: 'registry'(仅缺update时兼容updatable: true;禁按 npm source 推断,'git'手动)时,以确认的latest调pluginManager.updateBundle。- 断响应靠轮询
status(≤60s / 存活 Host 连续 3 次旧版即停)结算;加密远程通道严禁停用、卸载或更新 Remote 自身及所属 bundle。
- 启用且有
- 外部原生 WebRTC 探测必带
ELECTRON_RUN_AS_NODE=1,加载前拒绝 Electron。
3. 凭据迁移、V2 刷新锁与 DSH-Go 配对
- 默认凭据根为
$DSH_HOME/ds-harness-remote(日志前缀统一ds-harness-remote;自定义IdentityStore.directory保持原路径)。 - 目录外
.ds-harness-remote-migration/闸门串行迁移与刷新:- 迁移前只读全验旧
remote白名单、公私钥、指纹与 scope 哈希。 - 容忍
trusted-peers.json.<pid>.<UUIDv7>.tmp及普通.DS_Store/desktop.ini/Thumbs.db,拒._*、软硬链接与未知文件。 - rename 失败写
legacy-root.json固定原dev/inode沿用,禁合并覆盖或另建身份。
- 迁移前只读全验旧
- 刷新用 V2 硬链接 marker +
.holder-<pid>-<uuidV7>队列锁(限 Linux 单机 ext4/XFS,不含 NFS/SMB;升/降级前停全部 Harness,见 plugin-integration.md),不按时间抢锁。 4003映射CONNECTION_REPLACED并停止抢占。- DSH-Go 配对(device-pairing-v1.md)限 Host 本地扫码与单次 AES-GCM 提交,持久化
pairing-host-only.json(inbound-only),禁建 Client 角色。
4. Harness Carrier、路由白名单、受限写入与异步压缩
- Harness 仅用官方
TypertGatewaycarrier(0.1.1-rc.2ApiProxy 已删;共享旧类型仅供独立 VS Code,禁在 Host/Android 重开或另建协议)。 - 激活备共享 fallback owner Peer,每条已认证连接独占释放独立 owner Peer。
RemoteSnapshotStream延后断线错至重连取消点;RemoteTypertGateway为旧ui-theme补默认字体。harness.transport.describe向session/list发{ args: { __remoteCapabilityProbe: true } }:- 仅认
gateway/arguments-invalid(零调用、5s 预算,禁换合法空请求扫库;余错或意外成功均 fail-closed)。
- 仅认
session/list超 2,048 行时 Host 只留最新根会话并提升projections.values.title,Client 先过滤再截断。- Harness v1 审批限
allow_once | deny(禁allow_session);问答限userQuestions/answer|attachWait(断线释 claim)。 packages/plugin/src/plugin-route-bridge.ts仅放行api/session/uploadFileBinary与packages/plugin/tests/fixtures/ds-bot-v0.3.6-endpoints.json161 端点 +btw/btw-cancel/room-continue:- 保持 30s 预算与不重放 mutation。
- 管理/凭据/电脑控制/审批
choice交认证后 DS-Bot handler 校验。
- 仅五类受限写入例外(禁通用 fs 写或远程桌面 RPC):
workspace.upload(.lan).v1写会话验证根(排他 tmp+fsync+原子不覆盖;直连 1 GiB / 中继 20 MiB 动态复检channel.mode;LAN 限>=1 MiB,发open后禁换通道重放)。- 官方
workspace/create递归建非根无 NUL 绝对目录。 - AGY 私有
tmp图缓(PNG/JPEG/WebP/GIF,≤4×8 MiB / 总 512 MiB / 24h 清理)。 - OpenCode v1
--help确认后经私有127.0.0.1认证 HTTP 调PATCH time.archived(纯 stdio/v2 返OPENCODE_ARCHIVE_UNAVAILABLE)。 - Remote Tools
remote_download_file写本机独立Downloads/dsh-remote-*(≤50 MiB),操作仅内存去重,unknown禁重发。
remote.history.compact.v1按连接配置且不改源记录(compact-bot-round.ts保replies并标truncated: true,128 Ki 字符预算)。/compact走packages/plugin/src/remote-compaction-operations.ts:(deviceId, sessionId, requestId)幂等、同会话单活AGENT_BUSY、全局 ≤32RATE_LIMITED、30m 预算。- 取消/超时查
session/events确认,succeeded优先,unconfirmed禁 Client 重提。
5. CodeX、ACP 多后端与共享远程终端
- CodeX(
packages/plugin/src/codex/,codex.app.*)与 ACP(agent.acp.*:cursor/antigravity/pi/opencode/claude/hermes,见 acp-remote.md、codex-remote.md)保持独立数据面。 - UI 仅内存投影(
packages/plugin/src/acp/virtual-harness.ts禁 Node/FS 依赖),禁写 DSHSessionStore、Workspace 库或 Harness 日志。 - CodeX authority 取
project/list(回退thread/list绝对cwd),project/create仅注册已存在目录(realpath)。 - ACP 边界:
- 强制
<backend>:cwd:与 Hostrealpath/catalog 校验,不猜 adapter 不降级。 - Claude 禁图片;批量
prewarm=false。 - Cursor/Pi 每会话独立进程(≤30 活+1 history,历史 ≤8 MiB/10k 更新);模型/思考用上游确认值禁回复中切。
- ACP 审批按
options.kind映单次optionId(允许/拒绝/取消),禁allow-always。
- 强制
- 共享终端
packages/plugin/src/remote-terminal-controller.ts受terminal.enabled控制:- 仅运行验证候选 shell,维护 1,000 行 / ≤256 KiB xterm 快照与 1 MiB 队列(≤8/会话、≤256/域)。
- 绑设备归属与当前 follower 输入权,2h 明确 idle 回收,重配等清理完再重开。
Test Policy
- 预算仅限:
- 协议编解码与 schema;
- 身份、加密、篡改与重放;
- 鉴权、配对、锁与迁移;
- RPC 关联、fail-closed、allowlist 与异步压缩;
- 传输切换与重连核心状态机。
- 纯展示 UI、文案、图标、配色、排版、静态说明与源码字符串匹配不写单测(靠
check与烟测)。 - 共享实现仅在所属包测一次;Node 不计 Android 原生验证。
- 多变体合并为隔离命名场景矩阵(如 test-scenarios.mjs),失败报具体场景并续跑同组;禁
skip/exclude藏测。
Documentation Rules
- 根目录留
README.md(默认英文,不另建独立英文副本)、README.zh.md、README.ja.md、AGENTS.md与根清单。 - 专题集中于 docs/,设计位于
docs/design/(旧归档目录已移除);自部署 Server 实际能力见 apps/server/README.zh.md。 docs/TODO.md只记待办与已知限制(保留 Metro@noble/hashes/crypto.jsfallback 待办,未修禁删)。docs/CHANGELOG.md与 Release Notes 只写用户可感知变化与贡献者,不写测试数、构建命令或未验收表。- 临时验收、评审、地址、日志、构建哈希、采样与调试/验收截图录屏禁新增提交入库或堆入
AGENTS.md/docs/:- 复现步骤留测试或 transport-bench;现场结果放 Issue/PR 附件或已忽略
artifacts/、docs/screenshots/。 - README 展示图
docs/images/与应用运行资源保留。
- 复现步骤留测试或 transport-bench;现场结果放 Issue/PR 附件或已忽略