ds-harness-remote-fast/AGENTS.md

14 KiB
Raw Blame History

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-remote CLI;无可见 Client 模式)。
  • packages/tui & packages/tui-plugin:
    • packages/tui 为同版本独立发布的 ds-harness-remote-tui Host 组合包(装配官方 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/Client exports、CLI bin 与根 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 须保持字节一致。
  • 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 加密通道(SecureMessageCodec 48 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),父连接关/替即销毁监听器与临时文件。
  • 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 仅用官方 TypertGateway carrier(0.1.1-rc.2 ApiProxy 已删;共享旧类型仅供独立 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.json 161 端点 + btw/btw-cancel/room-continue:
    • 保持 30s 预算与不重放 mutation。
    • 管理/凭据/电脑控制/审批 choice 交认证后 DS-Bot handler 校验。
  • 仅五类受限写入例外(禁通用 fs 写或远程桌面 RPC):
    1. workspace.upload(.lan).v1 写会话验证根(排他 tmp+fsync+原子不覆盖;直连 1 GiB / 中继 20 MiB 动态复检 channel.mode;LAN 限 >=1 MiB,发 open 后禁换通道重放)。
    2. 官方 workspace/create 递归建非根无 NUL 绝对目录。
    3. AGY 私有 tmp 图缓(PNG/JPEG/WebP/GIF,≤4×8 MiB / 总 512 MiB / 24h 清理)。
    4. OpenCode v1 --help 确认后经私有 127.0.0.1 认证 HTTP 调 PATCH time.archived(纯 stdio/v2 返 OPENCODE_ARCHIVE_UNAVAILABLE)。
    5. 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、全局 ≤32 RATE_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 依赖),禁写 DSH SessionStore、Workspace 库或 Harness 日志。
  • CodeX authority 取 project/list(回退 thread/list 绝对 cwd),project/create 仅注册已存在目录(realpath)。
  • ACP 边界:
    • 强制 <backend>:cwd: 与 Host realpath/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.js fallback 待办,未修禁删)。
  • docs/CHANGELOG.md 与 Release Notes 只写用户可感知变化与贡献者,不写测试数、构建命令或未验收表。
  • 临时验收、评审、地址、日志、构建哈希、采样与调试/验收截图录屏禁新增提交入库或堆入 AGENTS.md/docs/:
    • 复现步骤留测试或 transport-bench;现场结果放 Issue/PR 附件或已忽略 artifacts/、docs/screenshots/。
    • README 展示图 docs/images/ 与应用运行资源保留。