项目规则（dsh-coding-remote-kit）

本仓库是挂在生产 dsh web 上的 Cordis 插件。入口 import 失败会 fail-fast 拖死整棵插件树，表现为 3080 拒连。下面规则对在本仓库干活的人和 agent 一律生效。

完整的文档分层、版本与提交约定见 docs/00-project-rules.md。安装步骤见 INSTALL.md。

1. 禁止自行重启生产 dsh-web（强制）

Agent 不得自行执行下列任何操作：

• systemctl --user restart|stop|start|kill dsh-web.service
• dsh-web restart|start|stop 或对 dsh web 进程 kill / pkill
• 为「让插件生效」而重启、重载、抢占 127.0.0.1:3080

重启会切断正在跑的 GUI 会话（包括当前 agent 自己）。挂回 / 卸包之后，只准备材料并报告，由操作者在自己选的时间窗重启。

允许的只读核对（重启后由操作者或下一轮会话执行）：

• systemctl --user is-active dsh-web.service
• curl -sS -m 6 -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3080/
• journalctl --user -u dsh-web.service 查有无 plugin tree failed
• ss -tlnp | grep -E '3080|6879'

2. 挂回生产 profile 的分工

目标始终是 $DSH_HOME（默认 ~/.dsh）的 web profile，不要写进某个 git checkout 里的 .dsh。

谁	可以做	不可以做
Agent	Docker 沙箱门禁、pnpm pack、把 tgz 拷到仓库外（如 $DSH_HOME/packages/）、dsh plugin --profile web add <tgz>、只读探活、写运维日志	重启 dsh-web、link: 工作树、改本机代理 / 防火墙 / Tailscale
操作者	在自己的时间窗重启 dsh web、确认 3080=200	—

tarball 不要放在本仓库根下再 pnpm add：pnpm 11 会把 file:.../output/*.tgz 解析成 link: 源码树。先拷到 $DSH_HOME/packages/dsh-coding-remote-kit-<ver>.tgz 再 add。

安装前门禁：pnpm test:sandbox 必须绿。未绿禁止改生产 profile。

本机路径、具体保活开关等运维细节只写在 docs/local/（git 忽略），不要写进公开文档。

3. 测试与本机红线

• 测试进 Docker 沙箱（test-dsh-mobile-remote:*），不要在本机抢 3080/7890 或对生产 dsh web 做冒烟。
• 遵守用户级 agent 规则：不扰动本机代理 / DNS / Tailscale；Docker 不用 --network host、不挂敏感目录。
• 不要把交接文档、密钥、真实 token 写进 git。
• package.json 的 exports 必须包含 "./package.json": "./package.json"。dsh-client-modules 用 require.resolve("<pkg>/package.json") 扫描客户端；缺这一项会静默丢掉设置页（服务端仍加载）。

4. 事故备忘

esbuild 把 tweetnacl 打进 ESM 入口会导致 Dynamic require of "crypto" is not supported。server bundle 必须 packages: "external"，构建断言与 tests/bundle-externals.test.js 不得删。

缺 exports["./package.json"] 时设置里看不到「移动远程」，但 6879 数据面仍在。

DSH webServer.register 按 path 去重、不认 HTTP method。同一路径 register 两次会抛 duplicate exact route 并拖死整棵 dsh web。一个 path 只能 register 一次，GET/POST 在 handler 里分支。tests/routes-unique.test.js 不得删。