安装 Sanad
引导用户从检查到验证的 Sanad 安装或更新过程。 保持发布用户和开发者源码工作流程分离。
安全规则
- 在更改任何内容之前先进行检查。将安装、包替换、服务注册、应用程序启动和 Git 更新视为需要用户知情批准的变更。
- 切勿搜索整个主目录或磁盘以查找检出。仅检查当前目录、用户提供的路径以及标准安装命令位置。当无法安全识别项目路径时，要求用户提供。
- 除非用户明确授权该确切操作，否则切勿覆盖、重置、清理、暂存、提交或丢弃脏仓库。
- 切勿请求、引用、记录或重建访问令牌、刷新令牌、提供商凭据、签名密钥或用户内容。仅对于明确授权的代理操作远程安装，接受用户完整的 添加设备 命令，该命令包含其短时效、一次性使用的创建令牌。验证官方引导程序，在不回显、跟踪或持久化于项目工件中的前提下传输它，并且绝不提取/重建其令牌。说明此同意涵盖创建命令在聊天/工具历史中的暴露，以及生成的安装程序命令可能使用令牌参数；不要声称零暴露。保持 SSH 传输参数无凭据。如果用户不接受此暴露，让他们直接执行或使用交互式 Portal 登录。此例外绝不涵盖持久凭据。
- 仅使用官方 Sanad 源：
- 仓库：
https://github.com/EastStarAI/sanad-agent - 发布：
https://github.com/EastStarAI/sanad-agent/releases/latest - 安装程序：
https://sanad.eaststarai.com/install.sh和https://sanad.eaststarai.com/install.ps1
- 仓库：
- 不要禁用操作系统安全控制。在描述当前签名或平台支持之前阅读最新的发布说明。
- 在安装和更新过程中保留 Sanad Home 和用户工作区。
Google Cloud 快速路由
对于 Google Cloud / GCP / 免费云服务器请求，请阅读 references/google-cloud-free-tier.md 并遵循该专门的发布用户路由，而不是重复下面的通用本地/源码问卷调查。它拥有先决条件、最多两个初始问题、资源重用、符合条件的配置、即时配对以及最小内置验证。遵守上述安全规则。不要承诺无条件的零账单或重复现有的免费限额。
1. 检查目标
确定命令将在用户当前机器上运行还是在远程机器上运行。不要假设托管 Sanad Client 的机器应该是托管 Sanad Agent 的机器。
收集只读证据：
- 识别操作系统和架构。
- 检查
sanad和sanad-dev是否在PATH上解析。 - 在相关时检查安装程序拥有的可执行文件：
- macOS/Linux：
${SANAD_HOME:-$HOME/.sanad}/bin/sanad - Windows：
$env:SANAD_HOME\bin\sanad.exe，或$HOME\.sanad\bin\sanad.exe当SANAD_HOME未设置时。
- macOS/Linux：
- 如果当前或提供的目录是 Git 检出，则检查：
git rev-parse --show-toplevel、git remote -v、git status --short --branch和git worktree list。仅当其仓库身份与EastStarAI/sanad-agent匹配或用户确认是有意分支时，才将其作为 Sanad 源码接受。 - 仅通过已解析的 Sanad 可执行文件查询安装版本和服务状态。不要仅仅因为
sanad不在PATH上而失败。
在提出更改之前总结现有状态。
2. 选择工作流程
如果用户的请求已经明确了工作流程，则确认目标并继续。否则展示这些选项并询问他们想要哪一个：
| 路径 | 最适合 | 结果 | 权衡 |
|---|---|---|---|
| 发布/用户 | 日常常规使用 | 打包的客户端和经过验证的 Agent 发布 | 稳定且简单；源码不可编辑 |
| 源码/开发者 | 贡献、调试或更改 Sanad | 通过 sanad-dev 运行的仓库检出 | 可编辑和可测试；需要开发工具和更多磁盘空间 |
对于发布路径，确定拓扑：
- 此桌面： 安装 Sanad Client；本地运行 在同一台计算机上安装并启动匹配的 Agent。
- 另一台计算机或服务器： 客户端保留在桌面、移动设备或网页上，仅安装 Sanad Agent 到目标机器。
- 仅客户端： 安装桌面/移动客户端或使用 Web Client 而不在该设备上安装 Agent。
明确说明确切的操作、目标和服务影响。在下载、安装、替换、注册、启动或重启之前获得批准。
3. 发布/用户路径
安装客户端和本地 Agent
- 阅读最新的官方发布及其清单。仅选择与确认的平台和架构匹配的客户端包。
- 使用该发布发布的校验和、签名和平台指南验证工件。不要将旧版本的签名状态推广到当前版本。
- 使用正常的操作系统流程安装客户端。不要静默绕过应用审查或安全提示。
- 要求用户启动 Sanad Client 并选择本地运行。说明客户端下载、验证、注册、启动并连接到匹配的本地 Agent；不需要 Sanad 帐户和配对令牌。
- 在声明成功之前验证客户端可以到达本地 Agent。
对于 Android、iOS 和 Web，请遵循当前发布说明中声明的可用性。这些平台提供界面，但不托管本机 Agent 服务。
在另一台计算机或服务器上安装 Agent
提供两个同等的选择：
- 通过 Sanad Client 配对： 打开 设置，然后单击设置侧边栏中设备旁边的 + 以打开添加设备。让用户在目标机器上运行完整的生成命令，或根据上述一次性创建令牌异常接受其完整的生成命令以进行授权远程安装。切勿单独请求凭据或将命令回显到报告中。
- 直接安装 Agent： 选择 Portal 登录或仅本地模式，并在批准后运行匹配的官方安装程序。
对于代理操作的 macOS/Linux 终端，避免模糊提示：
curl -fsSL https://sanad.eaststarai.com/install.sh | bash -s -- --login
当用户明确选择仅本地模式时，使用 --no-login 代替。
对于代理操作的 Windows PowerShell 终端：
& ([scriptblock]::Create((irm https://sanad.eaststarai.com/install.ps1))) -Login
当用户明确选择仅本地模式时，使用 -NoLogin 代替。交互式运行任一安装程序的人类用户可能省略显式登录选项并回答其提示。
Portal 登录可能需要用户打开 URL 或输入代码。等待该人工操作，不要暴露返回的凭据。安装后，验证已解析可执行文件的版本和 service status。当选择了云连接时，从 Sanad Client 确认设备。
更新打包安装
-
在更改之前检查已安装的客户端和 Agent 版本并阅读最新的发布说明。
-
通过其平台拥有的更新流程更新 Sanad Client。不要用源码输出替换打包的客户端。
-
通过已解析的可执行文件更新独立 Agent：
sanad update当
sanad不在PATH上时使用完整可执行文件路径。如果更新程序报告restart_required，获得批准并运行sanad service restart。 -
验证最终版本、服务状态、客户端到 Agent 的连接以及 Sanad Home 的保留。报告仍然需要手动执行的平台步骤。
4. 源码/开发者路径
准备检出
如果已存在匹配的检出，则仅在报告其路径、分支、工作树、远程仓库和脏状态后使用它。不要静默克隆重复项。
如果没有检出，建议一个目标并获取批准，然后运行：
git clone https://github.com/EastStarAI/sanad-agent.git sanad-agent
cd sanad-agent
在进一步工作之前阅读仓库的 AGENTS.md、docs/llms.txt 和最近的嵌套契约。对每个 Dart 或 Flutter 操作使用 FVM。
一次性安装用户范围的开发命令。
在 macOS/Linux 上：
scripts/sanad-dev install
在 Windows PowerShell 上：
.\scripts\sanad-dev.ps1 install
然后在每个平台上运行匹配的 Agent 和客户端对：
sanad-dev run
仅当用户明确需要仅本地开发时使用 sanad-dev run --no-cloud。使用 sanad-dev status 和有限的 sanad-dev logs agent -n 50 和 sanad-dev logs client -n 50 调用来进行验证。永远不要从 AI 工具调用中使用日志跟踪模式。
更新开发检出
- 检查活动的分支、上游、工作树和脏文件。
- 仅在确认预期的远程仓库后运行
git fetch。在集成之前说明传入的提交。 - 对于预期的跟踪分支上的干净检出，建议
git pull --ff-only。不要隐式创建合并提交。 - 对于脏检出，停止并提供保留选项。未经明确授权，不要暂存、提交、变基、切换、重置或丢弃。
- 在源更新成功后，重新运行平台特定的
sanad-dev install；然后使用sanad-dev run或用户请求的有限验证命令。 - 永远不要对源码/FVM 运行时使用
sanad update；源码更新属于 Git 和sanad-dev。
5. 报告结果
报告：
- 选定的工作流程和目标机器；
- 检测到的和最终的版本；
- 客户端、Agent、仓库和服务状态；
- 验证命令和结果；
- 仍然需要的任何手动用户操作；
- 更改的文件、服务或 Git 状态。
永远不要仅从下载或命令退出码就声称成功。需要相关的服务或客户端到 Agent 的健康证据。除非用户明确要求该单独操作，否则不要提交、推送、发布或删除用户数据。