# 快速开始

从零到第一次对话，一共三步：装好命令行工具、扫码授权一次、开口说话。
整个环境只需要授权一次，之后每次对话直接说事就行。

## 你需要准备

| 项 | 要求 |
|---|---|
| Node.js | 18 或更高版本 |
| 企业微信 | 一个能扫码的企业微信账号（手机上装着企业微信即可） |
| 网络 | 能访问企业微信服务；查帮助文档也需要联网 |

## 第一步：让助手检查环境

直接开口问它就行，它会自己跑前置检查：

> 「企业微信接一下」
> 「帮我看看企微能不能用」

助手会依次确认三件事：命令行工具装了没、版本够不够、有没有授权。任何一步不通过，它会停下来告诉你卡在哪，
**不会带着半个环境硬往下做**。

工具没装或版本太低时，它会提示安装：

```bash
npm install -g @wecom/cli
```

装完再让它检查一次。

> **实测**：界面里让助手接入企业微信时，它的执行顺序是「查版本 → 查授权状态 → 引导授权」，
> 三步都正确，没有编造不存在的命令。

## 第二步：扫码授权（只做一次）

没授权时，助手会引导你完成授权。它会打印一个授权链接和二维码，**你用企业微信扫一下**，
授权就完成了（等待时间上限 5 分钟）。

- 二维码在终端里显示不出来时，可以让助手把二维码存成图片文件再给你看。
- 授权成功后助手会再查一次状态，**只有确认是「已授权」才会继续做事**。

**关于「登录」**：企业微信的命令行工具没有 `login` 这个命令，授权靠的是「初始化」这一步。
你不必记这些——但如果看到助手或别处的文档提到 `wecom-cli auth login`，那是不存在的写法。

> **实测**：授权信息以「机器人 + 授权真人」两重身份存在。实测账号里，机器人代表真人（王轶）工作；
> 它创建的待办，创建人显示的是**机器人身份**，不是你本人。这一点后面会反复影响你能改什么、不能改什么。

## 第三步：第一次对话

授权完就可以直接说事了。几个安全的起手式（都是纯读取，不会改任何东西）：

> 「我今天有什么安排？」
> 「我有哪些待办？」
> 「我最近有哪些会？」
> 「微盘里最近有什么文件？」
> 「张三是谁？」

想试写入的话，从**只影响你自己**的动作开始：

> 「帮我记个待办：明天下午三点前把周报发出去」

助手会创建这条待办，并回显标题、参与人、截止时间。你在企业微信的待办里就能看到它。
这条只给你自己记，不分派给别人，所以助手会直接执行、不会追问。

**一旦涉及别人，行为就变了**：分派给同事、发消息、发邮件、改文档权限——助手会先把「对谁、做什么、
内容是什么」复述一遍，等你明确同意。详见 [99 风险与确认](99-风险与确认.md)。

## 第一次就会遇到的三件事

**1. 有些能力要单独开通。**
企业微信的机器人权限**按品类逐项开通**：通讯录是一项，文档是一项，微盘、会议、邮件、群聊各是一项。
没开通的品类，助手第一次调用就会被拒，它会把企业微信官方的开通指引**原样转给你**（包含链接，
一字不改），然后停下来。**它不会反复重试，也不会换个方法绕过去**——那是权限问题，重试没用。

实测账号最初只开了基础品类，后来才补齐了通讯录、文档、微盘、会议、邮件；
**群聊会话品类始终没开通**，所以 [04 群聊历史](04-群聊历史.md) 的能力完全没验过。

**2. 它只能改「它自己建的」东西。**
读是全的，写是窄的。你自己在企业微信里建的文档、日程、待办，助手**改不了**。
它会说明这条边界，然后给替代方案（「我另建一份」/「这个得你在客户端改」），而不是反复重试到失败。

**3. 它不给你看内部编号。**
成员编号、会话编号、文档编号这些内部标识只在它自己的调用链里流转，回复里一律用姓名、群名、文档标题。
你主动要也不会给——但它会换个方式帮你把事办成。文档链接、微盘分享链接这类**可点击的链接是可以给的**。

## 常见起步问题

| 现象 | 多半是什么 |
|---|---|
| 助手说命令不存在 | 工具没装，或没装成全局。执行 `npm install -g @wecom/cli` |
| 助手说版本太低 | 需要 1.2.0 及以上，重新安装即可 |
| 扫码后仍显示未授权 | 授权没走完（超时或中途退出），让助手重新引导一次 |
| 某类事情一直做不了，助手贴了一段官方指引 | 该品类未开通，按那段指引去开通。**别让助手重试** |
| 助手说「这份是你自己建的，我改不了」 | 正常边界，见上文第 2 条 |
| 查帮助也失败 | 查帮助本身需要联网（不需要授权）。离线机器上连帮助都查不了 |

## 下一步

- 想知道每类事情怎么说：回 [README 的「按能力查」](README.md#按能力查)
- 想知道什么时候会被问一句：看 [99 风险与确认](99-风险与确认.md)
- 想从最稳的能力开始用：[07 待办](07-待办.md) 和 [05 日程](05-日程.md) 是实测覆盖最完整的两个

## 📋 验证状态

| 项 | 状态 |
|---|---|
| 环境检查与授权引导（界面内，模拟真人） | ✅ 已实测：执行顺序为「查版本 → 查授权状态 → 引导授权」，未编造不存在的命令 |
| 首次扫码授权 | ✅ 已实测：实测账号于 2026-08-31 完成扫码授权，后续补齐了通讯录 / 文档 / 微盘 / 会议 / 邮件品类 |
| 助手能被正常创建并对话 | ✅ 已实测：人格与原则文件逐字节完整加载，15 个技能全部被发现，会话可用、自动问候正常 |
| 「你说一句话 → 助手真的执行完」的完整链路 | ⚠️ **未实测**。本机内存不足导致实例反复启动失败，界面里的 AI 审批也未配置（自动审批被拒），端到端跑不通 |
| 群聊会话品类的授权 | ❌ 未开通，未实测 |