> ## Documentation index
> Fetch the complete documentation index at: https://tgcloud.docs7.io/llms.txt
> Ask it with GET https://tgcloud.docs7.io/ask?q=<keywords or question>. Short keywords rank best.
> Use these to discover all available pages before exploring further.

# 工具

> tgcloud-mcp 的全部 16 个工具

# 工具

每个工具都接收 `project_dir`，即 tgcloud 项目的绝对路径（`create_project` 改为接收 `parent_dir` 和 `name`）。

<CardGroup cols={2}>
  <Card title="生命周期" icon="hammer" href="#lifecycle">
    create、init、login、add、upgrade
  </Card>
  <Card title="同步" icon="refresh" href="#sync">
    status、diff、push、deploy、pull、fetch、reset
  </Card>
  <Card title="数据" icon="database" href="#data">
    运行 handler 或 endpoint，migrate
  </Card>
  <Card title="Webhook" icon="link" href="#webhook">
    状态与同步，包括沉默的机器人
  </Card>
</CardGroup>

## 生命周期 {#lifecycle}

| 工具 | CLI | 说明 |
|---|---|---|
| `create_project` | `npm create @tgcloud/bot` | 新建项目（`parent_dir`、`name`） |
| `init_project` | `tgcloud init` | 在现有目录中生成脚手架，能识别 Mini App |
| `login_bot` | `tgcloud login` | 用 CLI access token（`app<id>:<secret>`）绑定；令牌经 stdin，输出中掩码 |
| `add_module` | `tgcloud add` | 新模块：`handlers/<type>`、`endpoints/<name>`、`lib/<path>` |
| `upgrade` | `tgcloud upgrade` | 把 0.2.0 之前的布局移入 `tgcloud/`。默认 `dry_run: true`；真正执行需要 `confirm: true` |

## 同步 {#sync}

| 工具 | CLI | 说明 |
|---|---|---|
| `status` | `tgcloud status` | 本地相对快照的变化（离线），含静态文件差异和 webhook 是否同步 |
| `diff` | `tgcloud diff` | 逐行 diff（离线） |
| `push` | `tgcloud push` | 原子部署。不构建前端，不迁移数据库。`force: true` 需要 `confirm: true` |
| `deploy` | `npm run build` + `tgcloud push` | 若 `package.json` 有 build 脚本则先构建再 push。`skip_build: true` 只 push |
| `pull` | `tgcloud pull` | 云端 → 快照和工作文件。不写入 Mini App 构建目录 |
| `fetch` | `tgcloud fetch` | 云端 → 只更新快照 |
| `reset` | `tgcloud reset` | 丢弃本地模块修改；需要 `confirm: true` |

## 数据 {#data}

| 工具 | CLI | 说明 |
|---|---|---|
| `run_handler` | `tgcloud run` | 不部署即可运行 handler 或 endpoint。`args` 与 `ctx` 为 JSON5。`args` 是第一个参数（载荷：handler 为 `Message`，endpoint 为输入）；`ctx` 是第二个（handler 的 `ctx.update` 是原始 Update，含 `update_id`；endpoint 为 `initData`） |
| `migrate` | `tgcloud migrate` | 默认 `dry_run: true` 只预览。应用时需要 `dry_run: false` 和 `confirm: true`。`apply: "safe"` 即 `--safe`；应用时默认 `apply: "yes"` 即 `--yes`。`local: true` 即 `--local` |

## Webhook {#webhook}

| 工具 | CLI | 说明 |
|---|---|---|
| `webhook_status` | `tgcloud webhook` | URL、allowed_updates、积压、投递错误、是否与 handlers 同步 |
| `webhook_sync` | `tgcloud webhook sync` | 重新指向平台。`drop_pending: true` 需要 `confirm: true` |

新增或删除 handler 后，webhook 可能不同步。`push` 不保证刷新。这种部署之后调用 `webhook_sync`。

## 流程

- **机器人没反应**：`webhook_status` → `status` / `diff` → `push` → `webhook_sync`
- **已部署日志**：没有下载命令；先看 `webhook_status` 的最后投递错误，再用 `run_handler` 复现（它的 `console.*` 是本地输出，不是已部署机器人的）
- **push 时修订冲突**：`fetch` → `diff` → `push`（或带 `confirm` 的 `force`）
- **改 schema**：编辑 `schema.js` → `push` → `migrate`（dry-run）→ 带 `confirm` 的 `migrate`。没有删除时用 `apply: "safe"`
- **Mini App 前端**：用 `deploy`，不要只 `push`