# Cloud - 技术支持与帮助中心

[English Version](./README.md)

欢迎访问 **Cloud** 官方公开技术支持与帮助中心。Cloud 是专为开发者打造的 AI 编程智能体（Agent）移动端控制与协同终端。

> 📱 **App Store 官方正式版**：App Store 下载 → [https://apps.apple.com/app/id6813359140](https://apps.apple.com/app/id6813359140)<br/>
> ✈️ **iOS TestFlight 公测**：点击加入 → [https://testflight.apple.com/join/BxQvuzYG](https://testflight.apple.com/join/BxQvuzYG)

> **品牌与技术依赖免责声明**
> 本产品是基于 Claude Agent SDK 构建的独立产品，与 Anthropic 不存在隶属、背书或赞助关系。
> An independent product powered by the Claude Agent SDK. Not affiliated with, endorsed by, or sponsored by Anthropic.

---

## 快速导航

- [技术支持与问题反馈](#技术支持与问题反馈)
- [快速入门与服务端配置](#快速入门与服务端配置)
- [常见问题与故障排查](#常见问题与故障排查)
- [安全与隐私保障](#安全与隐私保障)
- [政策与条款](#政策与条款)
- [联系与沟通](#联系与沟通)

---

## 技术支持与问题反馈

如果您在使用 Cloud 过程中遇到任何问题、异常报错或有新功能建议，请通过以下方式联系我们：

1. **GitHub Issues (推荐)**：
   - [提交缺陷报告 (Bug Report)](https://github.com/cddchen/Cloud/issues/new?template=bug_report.md)
   - [提交功能建议 (Feature Request)](https://github.com/cddchen/Cloud/issues/new?template=feature_request.md)
2. **技术支持邮箱**：
   `cddch1n@icloud.com`

---

## 快速入门与服务端配置

Cloud 采用 **客户端-服务端直连架构**。移动端应用（iOS / Android）作为控制终端，通过`公网/局域网/Tailscale组网`等形式连接您本地工作站或云服务器上运行的 `cloud host`，基于`claude agent sdk`直接传输相关数据，不通过任何第三方服务。

### 1. 服务端环境要求与模型授权
- **操作系统**：macOS, Linux
- **运行时环境**：Node.js >= 22.0.0
- **核心前置依赖**：**Claude Code**（主机端必须安装并可运行 Claude Code）
- **模型授权方式（灵活支持）**：
  - **官方订阅**：支持直接使用 Claude 官方订阅账号（Pro / Team 等）在主机端登录使用；
  - **第三方 API / 代理**：完全支持通过环境变量配置自定义 API Key 或反向代理中转（如 `ANTHROPIC_API_KEY`、`ANTHROPIC_BASE_URL` 等），无缝适配第三方模型服务商或企业内网网关。

### 2. 启动 Host 服务
在您的开发工作站或服务器上配置环境变量并启动 Host：

```bash
# 1. 通过命令行工具参数启动
# port不设置默认8787
# token不设置默认随机6位数
# --global不设置默认局域网
npx @cddchen/cloud@latest start --port=8787 --token=your-secure-random-token --global
# 2. 通过环境变量设置
export HOST_AUTH_TOKEN="your-secure-random-token"
export HOST_PORT=3000
npx @cddchen/cloud@latest start --global
```

### 3. 移动端配对连接
1. 打开手机端 **Cloud** 应用（可前往 [App Store](https://apps.apple.com/app/id6813359140) 官方下载或通过 [TestFlight](https://testflight.apple.com/join/BxQvuzYG) 安装）；
2. 进入 **连接设置 (Connection Settings)** 页面；
3. 输入您的 Host 访问地址（例如局域网 IP `http://192.168.1.100:3000` 或 Tailscale 节点地址）；
4. 填入设置的 `token`；
5. 点击 **测试并连接**，状态变为“已连接”后，工作区与历史会话将自动同步。

---

## 常见问题与故障排查

### Q1: 移动端提示“连接失败”或“网络超时”？
- **局域网连通性**：确认手机与 Host 服务端位于同一 Wi-Fi，或已组建虚拟内网（如 Tailscale / WireGuard）。
- **防火墙与端口**：确认服务端防火墙已放行对应端口（默认 3000）。
- **iOS 本地网络权限**：首次启动 iOS 客户端时，请确保已授予“本地网络访问”权限（设置 -> 隐私与安全性 -> 本地网络 -> Cloud）。

### Q2: 提示“鉴权失败 (Authentication Failed)”？
- 移动端填写的访问 Token 必须与 Host 端启动时配置的 `HOST_AUTH_TOKEN` 严格一致；
- 请检查是否包含多余的首尾空格或特殊换行符。

### Q3: 任务执行中途息屏或网络切换，会话会丢失吗？
- **不会**。Cloud 服务端作为权威状态源（Authoritative State），持有 Agent 运行时的完整状态机；
- 移动端支持断线自动恢复重连，重新打开 App 或恢复网络后，系统通过增量 Action 重放（Replay）与快照对齐，自动同步至当前最新会话进度。

### Q4: 敏感操作审批机制是如何运作的？
- 当 Agent 尝试执行危险命令（例如删除文件、修改重要代码或执行高风险 Bash 命令）时，服务端会触发挂起拦截；
- 您的移动端会即时收到审批弹窗（Approval Sheet），您可以选择“批准执行”或“拒绝并给出补充指示”。未经您的明确授权，Agent 无法越权执行。

### Q5: 主机端必须使用 Claude Code 吗？支持哪些授权方式？
- **是的**。Cloud 服务端运行深度依赖本机已配置好的 **Claude Code** 环境。
- **授权方式高度自由**：
  1. **官方订阅**：直接使用 Claude 官方 Pro / Team / Enterprise 等订阅账号在主机端登录；
  2. **第三方 API / 代理**：完全支持配置自定义 API Key 与第三方中转代理（配置环境变量如 `ANTHROPIC_API_KEY`、`ANTHROPIC_BASE_URL`），不受官方账号或网页端限制。

---

## 安全与隐私保障

- **端到端纯直连**：您的代码文件、终端指令、模型对话均仅在您的手机与您的私有服务端之间直接传输，**绝不经过任何第三方转存服务器**。
- **凭据本地硬件级保护**：访问 Token 等凭据仅保存在手机端系统的安全存储中（iOS Keychain / Android Keystore）。
- **无追踪、无分析**：本应用不包含任何第三方广告 SDK 或行为追踪统计组件。

---

## 政策与条款

- [隐私政策 (Privacy Policy)](./PRIVACY.md)
- [服务条款 (Terms of Service)](./TERMS.md)
- [English Documentation](./README.md)

---

## 联系与沟通

- **开发者 / 维护者**：cddchen
- **官方 GitHub**：[https://github.com/cddchen/Cloud](https://github.com/cddchen/Cloud)
- **技术支持邮箱**：`cddch1n@icloud.com`
- **最新版本**：v1.0.0