# Repository Guide for Agents 定义编码 Agent 在本仓库工作的边界、结构、门禁、架构不变量、测试与文档规范。 - **版本与依赖**:不硬编码版本或构建号,以根及各包 `package.json`、`dsh-plugin.json`、`apps/android/app.json` 与 `pnpm-lock.yaml` 为准。 - **兼容与待办**:兼容基线见 [compatibility.zh.md](docs/compatibility.zh.md)([EN](docs/compatibility.md));待办与限制见 [TODO.md](docs/TODO.md)。 - **协议权威**:线协议以 [protocol.md](docs/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/android/AGENTS.md))。 - `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](docs/server.md) 完整站点设计写为 `apps/server` 已实现能力(须保留该文档与 `protocol.md`)。 ## Project Structure & Packaging Boundaries ```text 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](scripts/verify-dsh-plugin.mjs)、[verify-packed-webrtc.mjs](scripts/verify-packed-webrtc.mjs) 与 `git diff --exit-code`。 ## Development & Verification 环境:Node.js `>=24.9`、`pnpm@9.15.4`(Android 原生另需 JDK 17 与 Android SDK)。 ```bash 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](scripts/install.sh)(无 Windows 或自动卸载脚本): - macOS 非 root 复用 Desktop launcher 或 CLI,不装服务。 - Linux 需 root,管 `/opt/ds-harness-remote` 与 `ds-harness-remote-.service`;遇运行/启用中的旧归属服务拒绝继续,不碰未知服务与系统 Node/PATH,且须明示终端具备 root 权限。 ## Architecture & Implementation Rules ### 1. 线协议、加密与信任边界 - 线协议以 [protocol.md](docs/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...tmp` 及普通 `.DS_Store`/`desktop.ini`/`Thumbs.db`,拒 `._*`、软硬链接与未知文件。 - rename 失败写 `legacy-root.json` 固定原 `dev/inode` 沿用,禁合并覆盖或另建身份。 - 刷新用 V2 硬链接 marker + `.holder--` 队列锁(限 Linux 单机 ext4/XFS,不含 NFS/SMB;升/降级前停全部 Harness,见 [plugin-integration.md](docs/plugin-integration.md)),不按时间抢锁。 - `4003` 映射 `CONNECTION_REPLACED` 并停止抢占。 - DSH-Go 配对([device-pairing-v1.md](docs/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](docs/acp-remote.md)、[codex-remote.md](docs/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 边界: - 强制 `: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](scripts/test-scenarios.mjs)),失败报具体场景并续跑同组;禁 `skip`/`exclude` 藏测。 ## Documentation Rules - 根目录留 `README.md`(默认英文,不另建独立英文副本)、`README.zh.md`、`README.ja.md`、`AGENTS.md` 与根清单。 - 专题集中于 [docs/](docs/README.md),设计位于 `docs/design/`(旧归档目录已移除);自部署 Server 实际能力见 [apps/server/README.zh.md](apps/server/README.zh.md)。 - `docs/TODO.md` 只记待办与已知限制(保留 Metro `@noble/hashes/crypto.js` fallback 待办,未修禁删)。 - `docs/CHANGELOG.md` 与 Release Notes 只写用户可感知变化与贡献者,不写测试数、构建命令或未验收表。 - 临时验收、评审、地址、日志、构建哈希、采样与调试/验收截图录屏**禁新增提交入库或堆入 `AGENTS.md`/`docs/`**: - 复现步骤留测试或 [transport-bench](scripts/transport-bench/README.md);现场结果放 Issue/PR 附件或已忽略 `artifacts/`、`docs/screenshots/`。 - README 展示图 `docs/images/` 与应用运行资源保留。