ooodc
a7883dbed9
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段 - 强制每个任务都必须有唯一 id，且由用户负责生成 - 修改合并模式逻辑，merge=true 下保留未提及的旧任务 - 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress） - 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled - 优化状态转换校验，允许特定状态间合法切换 - 简化任务变更消息，移除详细的新增/更新/移除统计 - 更新文档和示例，明确 id 必须由用户生成和使用 - 修复和补充测试，增强状态转换和合并模式验证 - 调整任务时间戳生成逻辑，统一使用当前时间及索引 - 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
163 lines
7.8 KiB
Markdown
163 lines
7.8 KiB
Markdown
# im +chat-create
|
|
|
|
> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
|
|
|
|
Create a group chat. Supports both user identity (`--as user`) and bot identity (`--as bot`). You can specify the group name, description, members (users/bots), owner, chat type (private/public), and group mode. Set `--chat-mode topic` to create a topic chat.
|
|
|
|
This skill maps to the shortcut: `lark-cli im +chat-create` (internally calls `POST /open-apis/im/v1/chats`).
|
|
|
|
- `--as bot` requires the `im:chat:create` scope.
|
|
- `--as user` requires the `im:chat:create_by_user` scope.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Create a private group (default)
|
|
lark-cli im +chat-create --name "My Group"
|
|
|
|
# Create a public group (name is required and must be at least 2 characters)
|
|
lark-cli im +chat-create --name "Public Group" --type public
|
|
|
|
# Create a topic chat
|
|
lark-cli im +chat-create --name "Topic Group" --chat-mode topic
|
|
|
|
# Specify the group owner
|
|
lark-cli im +chat-create --name "My Group" --owner ou_xxx
|
|
|
|
# Invite user members (comma-separated open_ids, up to 50)
|
|
lark-cli im +chat-create --name "My Group" --users "ou_aaa,ou_bbb"
|
|
|
|
# Invite bot members (comma-separated app IDs, up to 5)
|
|
lark-cli im +chat-create --name "My Group" --bots "cli_aaa,cli_bbb"
|
|
|
|
# Invite both users and bots
|
|
lark-cli im +chat-create --name "My Group" --users "ou_aaa" --bots "cli_aaa"
|
|
|
|
# Make the creating bot a group manager (bot identity only)
|
|
lark-cli im +chat-create --name "My Group" --set-bot-manager --as bot
|
|
|
|
# JSON output
|
|
lark-cli im +chat-create --name "My Group" --format json
|
|
|
|
# Create a group with bot identity
|
|
lark-cli im +chat-create --name "My Group" --users "ou_aaa" --as bot
|
|
|
|
# Create a group with user identity
|
|
lark-cli im +chat-create --name "My Group" --users "ou_aaa,ou_bbb" --as user
|
|
|
|
# Preview the request without creating anything
|
|
lark-cli im +chat-create --name "My Group" --dry-run
|
|
```
|
|
|
|
## Parameters
|
|
|
|
| Parameter | Required | Limits | Description |
|
|
|------|------|------|------|
|
|
| `--name <name>` | Required for public groups | Max 60 characters; at least 2 characters for public groups | Group name (`"(no subject)"` for private groups if omitted) |
|
|
| `--description <text>` | No | Max 100 characters | Group description |
|
|
| `--users <ids>` | No | Up to 50, format `ou_xxx` | Comma-separated user open_ids |
|
|
| `--bots <ids>` | No | Up to 5, format `cli_xxx` | Comma-separated bot app IDs |
|
|
| `--owner <open_id>` | No | Format `ou_xxx` | Owner open_id (defaults to the bot when using `--as bot`, or the authorized user when using `--as user`) |
|
|
| `--type <type>` | No | `private` (default) or `public` | Group type. Default to `private`; pass `public` only when the user explicitly asks for a discoverable/public group. |
|
|
| `--chat-mode <mode>` | No | `group` (default) or `topic` | Group mode; `topic` creates a topic chat (not the same as `group_message_type=thread`). When the user asks for a topic chat, pass `topic` explicitly — do not rely on the default. |
|
|
| `--set-bot-manager` | No | - | Set the creating bot as a group manager (only effective with `--as bot`) |
|
|
| `--format json` | No | - | Output as JSON |
|
|
| `--as <identity>` | No | `bot` or `user` | Identity type |
|
|
| `--dry-run` | No | - | Preview the request without executing it |
|
|
|
|
> **`--chat-mode topic` vs "normal group with topic-message mode"**: `--chat-mode topic` here creates a 话题群 — the entire group is a topic chat. This is different from "normal group (`chat_mode=group`) + topic-message mode (`group_message_type=thread`)". This CLI exposes only `chat_mode`; `group_message_type` is intentionally not surfaced.
|
|
|
|
## AI Usage Guidance
|
|
|
|
### When using `--as bot`
|
|
|
|
Bot may fail to invite users who are mutually invisible to it during group creation (error 232043). To avoid this, use the **two-step flow** below instead of passing other users' open_ids in `--users`.
|
|
|
|
1. **Get the current user's open_id:** Run `lark-cli contact +search-user --query "<name or email>"` to retrieve it.
|
|
2. **Create the group — by default include the current user:**
|
|
|
|
```bash
|
|
lark-cli im +chat-create --name "<group name>" \
|
|
--users "<current user open_id>" --as bot
|
|
```
|
|
|
|
**Default behavior:** Always add the current user to the group, unless the user explicitly says "do not add me" or "bot-only group" — only then omit `--users`.
|
|
|
|
3. **Add other members via user identity** (requires the current user to be in the group):
|
|
|
|
```bash
|
|
lark-cli im chat.members create \
|
|
--params '{"chat_id":"<chat_id from step 2>","member_id_type":"open_id","succeed_type":1}' \
|
|
--data '{"id_list":["ou_aaa","ou_bbb"]}' \
|
|
--as user
|
|
```
|
|
|
|
`succeed_type=1` ensures reachable users are added successfully; unreachable ones are returned in `invalid_id_list` instead of failing the whole request.
|
|
|
|
4. **Check `invalid_id_list`** in the response. If non-empty, report to the user which members could not be added.
|
|
|
|
### When using `--as user`
|
|
|
|
User identity does not have the bot visibility limitation, so you can create the group and invite members in one step:
|
|
|
|
```bash
|
|
lark-cli im +chat-create --name "<group name>" --users "ou_aaa,ou_bbb" --as user
|
|
```
|
|
|
|
The authorized user is automatically the group creator and member.
|
|
|
|
## Output Fields
|
|
|
|
| Field | Description |
|
|
|------|------|
|
|
| `chat_id` | The new group's ID (`oc_xxx` format) |
|
|
| `name` | Group name |
|
|
| `chat_type` | Group type (`private` / `public`) |
|
|
| `owner_id` | Owner ID (may be empty when a bot creates the group and `--owner` is not specified) |
|
|
| `external` | Whether the group is external |
|
|
| `share_link` | Group share link (omitted if retrieval fails) |
|
|
|
|
## Usage Scenarios
|
|
|
|
### Scenario 1: Create a group and specify the owner
|
|
|
|
```bash
|
|
lark-cli im +chat-create --name "Project Discussion Group" --owner ou_xxx
|
|
```
|
|
|
|
### Scenario 2: Create a group and invite users and a bot
|
|
|
|
```bash
|
|
lark-cli im +chat-create --name "Project Discussion Group" \
|
|
--owner ou_xxx \
|
|
--users "ou_aaa,ou_bbb" \
|
|
--bots "cli_aaa"
|
|
```
|
|
|
|
### Scenario 3: Create a group and send a welcome message
|
|
|
|
```bash
|
|
CHAT_ID=$(lark-cli im +chat-create --name "New Group" --format json | jq -r '.data.chat_id')
|
|
lark-cli im +messages-send --chat-id "$CHAT_ID" --text "Welcome, everyone!"
|
|
```
|
|
|
|
## Common Errors and Troubleshooting
|
|
|
|
| Symptom | Root Cause | Solution |
|
|
|---------|---------|---------|
|
|
| Permission denied (99991672) | The app does not have `im:chat:create` (bot) or `im:chat:create_by_user` (user) permission enabled | Enable the required permission for the app in the Open Platform console |
|
|
| `--name is required for public groups and must be at least 2 characters` | A public group was created without a name or with a name shorter than 2 characters | Provide a name with at least 2 characters |
|
|
| `--name exceeds the maximum of 60 characters` | The group name is too long | Shorten the name to 60 characters or fewer |
|
|
| `--description exceeds the maximum of 100 characters` | The group description is too long | Shorten the description to 100 characters or fewer |
|
|
| `--users exceeds the maximum of 50` | Too many user members were provided | Split the operation into batches and add more members later |
|
|
| `--bots exceeds the maximum of 5` | Too many bot members were provided | Invite at most 5 bots at once |
|
|
| `invalid user id: expected open_id (ou_xxx)` | Invalid user ID format | Use the `ou_xxx` format for users |
|
|
| `invalid bot id: expected app ID (cli_xxx)` | Invalid bot ID format | Use the `cli_xxx` format for bots |
|
|
| `invalid --owner: expected open_id (ou_xxx)` | Invalid owner ID format | Use the `ou_xxx` format for the owner |
|
|
| `bot is invisible to user` (232043) | The bot and target users are mutually invisible | Follow the two-step flow in AI Usage Guidance above — do not pass other users in `--users` during creation |
|
|
|
|
## References
|
|
|
|
- [lark-im](../SKILL.md) - all IM commands
|
|
- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters
|