my-pi/pi-ssh/AGENTS.md

my-pi 维护约定（pi-ssh）

• 扩展入口是 pi-ssh/index.ts，ssh2 transport 与 SFTP 实现在 src/ssh2-transport.ts，有界自适应远程搜索位于 src/remote-search.ts，AES-GCM vault 位于 src/vault.ts，选择性导入入口是根 configure.sh ssh 与 scripts/ssh-config.mjs，权限桥接位于 permission-integration.ts，测试保留在 test/，来源记录是 UPSTREAM.md。
• 同步上游必须从明确 tag/commit 移植并保留 LICENSE、作者和来源；参考其他实现时记录明确 commit，不得导入嵌套 .git、node_modules 或构建产物。
• 运行时必须保持纯 ssh2，不得回退到系统 OpenSSH、sshpass、SSH_ASKPASS 或 ControlMaster；认证可使用密码、私钥文件或 ssh2 直连的 SSH Agent socket（包括 1Password），Agent 模式只保存 socket 路径且不得导出私钥。OpenSSH 只允许由显式配置脚本通过 ssh -G 解析用户选中的 alias，已导入配置变化必须由用户显式更新。第一版遇到 ProxyJump / ProxyCommand 必须拒绝，不能静默忽略。
• 根包必须直接固定安装 ssh2@1.17.0 与配置 CLI 所需的 jiti@2.7.0，因为 packed bundle 直接加载其内置 pi-ssh/ 源码；ssh2 与 cpu-features 的 install scripts 只构建可选加速绑定，当前不得加入根 allowScripts，纯 JavaScript fallback 必须可运行。
• SSH vault 使用同目录独立随机 key 和 AES-256-GCM 整体加密，目录/文件在 POSIX 上必须保持 700 / 600；该设计只防止误看或单独泄漏密文，不防同一用户读取 key。密码、私钥 passphrase、私钥内容、Agent 提供的签名材料、vault key 与解密明文不得进入命令参数、日志、Pi session、权限证据或明文临时文件。
• 已导入主机必须固定 SHA256 Host Key；不匹配时 fail closed。私钥认证只保存文件路径，Agent 认证只保存 socket 路径，均不得复制或导出私钥内容；文件工具使用 SFTP，写入优先临时文件与原子 rename，远端断线不得自动重放命令。
• ssh_connect 是唯一运行时连接入口，只接受 vault 中已导入的 host ID 与可选绝对/~/ remote cwd，并必须默认 ask 后进入 AutoReview；它必须声明 sequential execution mode 且支持取消，Agent 必须作为独立步骤调用并等待成功后才能发出依赖连接的其他 ssh_* 调用，避免连接建立或替换与远端操作重叠。未知 host ID 只可有界列出已导入 ID，不得泄露 endpoint 或凭据。不得注册 /ssh、--ssh、session resume 自动重连或把用户 ! 命令切换到远端。用户未在直接请求中明确服务器和具体远端任务时不得推断、替换或连接主机；新连接替换旧连接，会话结束自动断开。
• ssh_find / ssh_grep 必须在已授权工具调用内部按 fd/fdfind → git ls-files → find 与 rg → git grep → find+grep 顺序检测服务器现有能力，不安装或上传远端二进制；搜索目标必须作为绝对参数与执行 cwd 分离，搜索进程始终从当前已确认 remoteCwd 启动，单文件 ssh_grep 目标不得被当作目录执行 cd。输入必须 shell-safe，结果数量/单行/总捕获必须有界并显式报告 backend 与 truncated；30 秒超时必须报告解析后的 root 并提示先缩小范围。RTK 不得处理这两个搜索工具的结果。
• ssh_cd、ssh_read、ssh_write、ssh_edit、ssh_find、ssh_grep 的远端路径不能按本机路径执行默认 input.path gate；必须通过公共 PermissionsService 注册显式 extractor 关闭本机路径推断，并保持六个工具的默认策略为 ask。权限预览必须依据远端 remoteCwd / remoteHome 解析相对路径与 ~/，同时显示请求值和解析后的绝对远端路径。
• SSH transport 在会话中持久，但不得维护隐藏的交互式 Shell/PTY 状态；ssh_bash 每次调用必须从连接当前 remoteCwd 启动独立的非交互 Bash，必须忽略 Pi 本地 Bash factory 的 cwd 与 PI_* 会话环境。跨调用的工作区切换只能通过受复核且声明 sequential execution mode 的 ssh_cd 显式验证并更新连接状态；Agent 必须把它作为独立步骤调用并等待成功后，才可发出依赖新目录的远端工具调用。普通命令中的 cd 只可作为当次命令的临时目录变化，cd、export、alias 或函数不得被伪装为持久状态。
• 远端 HOME/cwd 探测与 ssh_cd 验证必须使用可取消、输出有界、随机标记 framing 的固定命令，只接受唯一绝对 POSIX 路径；banner、畸形/多行输出、超限、超时或取消时不得更新状态。独立 exec channel 最多并发 4 路，排队调用必须可立即取消；共享 SFTP 操作继续串行。
• ssh_bash 必须在唯一全局 policy 的 shellTools 中映射 commandArgument: "command" 并设置 decisionFloor: "ask"，复用 Bash 命令拆分、硬拒绝、风险 ask 和 authorizer chain；不得新增第二个并行 tool_call 审批层。
• SSH 权限沿用 pi-permission-system gate 与 auto-review authorizer chain：ssh_connect、ssh_cd、ssh_read、ssh_write、ssh_edit、ssh_find、ssh_grep 默认 ask；连接前的证据解析已导入 host ID 为非秘密 target、port 与请求/default cwd，AutoReview 只可依据用户直接消息中的明确目标授权连接。全部远端路径不得送入基于本机 cwd 的默认 input.path 归一化。
• RTK 只把 ssh_bash 当作 Bash 输出别名执行 ANSI 清理、测试/构建/Git/Lint 聚合与兜底截断；不得对远端命令启用 RTK rewrite，也不得处理 ssh_read、ssh_find 或 ssh_grep 返回。
• SSH 工具的权限预览必须包含连接请求或当前远端的 host id、target、port、remote cwd 与有界操作摘要；连接预览只解密本地 vault 以提取非秘密目标字段，绝不包含凭据，远端 shell 的完整命令继续由 Bash payload 单独提供。权限服务缺失或注册失败时必须 fail-safe，不得转为无提示自动允许。
• pi-ssh 只用于从本地项目显式操作服务器，不得自动探测、读取或向系统提示词注入远端 AGENTS.md、CLAUDE.md 或其他项目说明；远端内容只能由明确且已授权的 ssh_* 工具调用获取。
• 修改 SSH transport、vault、导入、权限集成或加载入口后至少运行 pi-ssh 包内 npm test、根脚本语法与 mock 配置测试、pi-permission-system 的 npm run typecheck / npm run test / npm run build、根扩展联合加载和实际 packed tarball 隔离安装验证。未经明确要求不得连接真实服务器或把真实密码写入测试。
• 根加载顺序必须保持 pi-permission-system → subagents → pi-ssh → pi-chrome → pi-tool-search → system-prompt（extensions/system-prompt.ts 为最后一个条目），确保内置 authorizer 与权限服务由同一扩展先注册/发布、subagents wrapper 随后把权限扩展注入子会话 mandatory 列表、SSH 桥接随后安装、Chrome 工具可在授权后进入目录、Tool Search 在提示词组装前建立完整工具目录，且单一提示词出口最后汇总所有扩展的结构化贡献。