Metadata-Version: 2.4
Name: wecom-cli
Version: 0.1.1
Summary: 企业微信命令行工具
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: rich>=15.0.0
Requires-Dist: tomli-w>=1.2.0
Requires-Dist: typer>=0.24.0
Description-Content-Type: text/markdown

# WeCom CLI

企业微信命令行工具，支持多级命令结构。

## 安装

```bash
cd wecom-cli
uv sync
source .venv/bin/activate
```

## 使用

### 全局选项

所有命令都支持 `--json` 选项，用于以 JSON 格式输出结果：

```bash
# JSON 输出
wecom-cli --json version
wecom-cli --json config get auth.corpid
wecom-cli --json doc list

# 默认输出（带格式化）
wecom-cli version
wecom-cli config get auth.corpid
wecom-cli doc list
```

### 查看帮助

```bash
wecom-cli --help
```

### 配置管理

```bash
# 设置字符串值
wecom-cli config set auth.corpid 'wwa'

# 设置 JSON 值
wecom-cli config set b.a --json '{
  "a": 1,
  "b": 2
}'

# 获取配置项
wecom-cli config get auth

# JSON 输出
wecom-cli --json config get auth

# 显示所有配置
wecom-cli config show

# 列出所有配置项
wecom-cli config list

# 删除配置项
wecom-cli config set auth.corpid ""
wecom-cli config set auth.corpid --json "null"
```

**键路径语法**：
- 使用点 `.` 分隔嵌套键，如 `auth.corpid`
- 键路径不能为空、不能以点开头或结尾、不能有连续的点

**JSON 值**：
- 使用 `--json` 标志指示值为 JSON 格式
- 支持所有 JSON 数据类型：字符串、数字、布尔值、null、数组、对象
- JSON 格式错误时会显示友好的错误信息

**注意**：
- 配置文件存储在 `~/.config/wecom-cli/config.toml`，文件权限为 600（仅用户可读写）
- token 会自动缓存并在过期前 5 分钟自动刷新
- 代理为可选配置，未配置时直连企微 API
- 代理 URL 必须以 `http://` 或 `https://` 开头
- 如果同时配置 HTTP 和 HTTPS 代理，优先使用 HTTPS 代理
- 敏感信息在显示时自动脱敏（如 `apiKey`、`corpsecret` 等）

### 文档管理

```bash
# 创建文档
wecom-cli doc add --name "文档名称" --type doc

# JSON 输出
wecom-cli --json doc add --name "文档名称" --type doc

# 删除文档
wecom-cli doc delete --name "文档名称"

# 重命名文档
wecom-cli doc rename --name "旧名称" --new-name "新名称"

# 获取分享链接
wecom-cli doc share --name "文档名称"

# 列出所有文档
wecom-cli doc list

# JSON 输出
wecom-cli --json doc list
```

### 智能表格子表操作

```bash
# 添加子表
wecom-cli doc smart sheet add --name "文档名称" --title "子表标题"
wecom-cli doc smart sheet add --docid "DOCID" --title "子表标题" --index 3

# JSON 输出
wecom-cli --json doc smart sheet add --name "文档名称" --title "子表标题"

# 删除子表
wecom-cli doc smart sheet delete --name "文档名称" --sheet-id "123abc"
wecom-cli doc smart sheet delete --docid "DOCID" --sheet-id "123abc"

# JSON 输出
wecom-cli --json doc smart sheet delete --name "文档名称" --sheet-id "123abc"

# 更新子表标题
wecom-cli doc smart sheet update --name "文档名称" --sheet-id "123abc" --title "新标题"
wecom-cli doc smart sheet update --docid "DOCID" --sheet-id "123abc" --title "新标题"

# JSON 输出
wecom-cli --json doc smart sheet update --name "文档名称" --sheet-id "123abc" --title "新标题"

# 查询子表信息
wecom-cli doc smart sheet query --name "文档名称" --sheet-id "123abc"
wecom-cli doc smart sheet query --docid "DOCID" --sheet-id "123abc"

# JSON 输出
wecom-cli --json doc smart sheet query --name "文档名称" --sheet-id "123abc"
```

**参数说明**：
- `--docid`：直接提供文档 ID
- `--name`：通过文档名称从注册表查找文档 ID（与 --docid 二选一）
- `--title`：子表标题（add/update 命令必填）
- `--index`：子表位置（add 命令可选，不指定则添加到末尾）
- `--sheet-id`：子表 ID（delete/update/query 命令必填）

### 智能表格字段操作

```bash
# 添加字段
wecom-cli doc smart field add --docid "DOCID" --sheet-id "s1" \
  --title "名称" --type FIELD_TYPE_TEXT

# 添加带属性的字段
wecom-cli doc smart field add --docid "DOCID" --sheet-id "s1" \
  --title "数量" --type FIELD_TYPE_NUMBER \
  --property 'property_number={"decimal_places":2,"use_separate":true}'

# 删除字段
wecom-cli doc smart field delete --docid "DOCID" --sheet-id "s1" \
  --field-id "fld1" --field-id "fld2"

# 查询字段
wecom-cli doc smart field query --docid "DOCID" --sheet-id "s1"
wecom-cli doc smart field query --docid "DOCID" --sheet-id "s1" \
  --field-id "fld1" --offset 0 --limit 10

# 更新字段
wecom-cli doc smart field update --docid "DOCID" --sheet-id "s1" \
  --field-id "fld1" --title "新名称" --type FIELD_TYPE_TEXT
wecom-cli doc smart field update --docid "DOCID" --sheet-id "s1" \
  --field-id "fld2" --type FIELD_TYPE_NUMBER \
  --property 'property_number={"decimal_places":3}'

# JSON 输出
wecom-cli --json doc smart field add --docid "DOCID" --sheet-id "s1" \
  --title "名称" --type FIELD_TYPE_TEXT
```

**字段类型**：
- FIELD_TYPE_TEXT, FIELD_TYPE_NUMBER, FIELD_TYPE_CHECKBOX, FIELD_TYPE_DATE_TIME
- FIELD_TYPE_IMAGE, FIELD_TYPE_ATTACHMENT, FIELD_TYPE_USER, FIELD_TYPE_URL
- FIELD_TYPE_SELECT, FIELD_TYPE_SINGLE_SELECT, FIELD_TYPE_PROGRESS
- FIELD_TYPE_PHONE_NUMBER, FIELD_TYPE_EMAIL, FIELD_TYPE_LOCATION
- FIELD_TYPE_CURRENCY, FIELD_TYPE_PERCENTAGE, FIELD_TYPE_BARCODE
- FIELD_TYPE_CREATED_USER, FIELD_TYPE_MODIFIED_USER
- FIELD_TYPE_CREATED_TIME, FIELD_TYPE_MODIFIED_TIME
- FIELD_TYPE_REFERENCE, FIELD_TYPE_WWGROUP, FIELD_TYPE_AUTONUMBER

**字段属性格式**：`--property 属性名=JSON值`
- 示例：`--property 'property_number={"decimal_places":2}'`
- 示例：`--property 'property_select={"options":[{"text":"选项1","style":1}]}'`

### 智能表格记录操作

```bash
# 添加记录
wecom-cli doc smart record add --docid "DOCID" --sheet-id "s1" \
  --record '{"values":{"名称":[{"type":"text","text":"测试"}]}}'

# 添加多条记录
wecom-cli doc smart record add --docid "DOCID" --sheet-id "s1" \
  --record '{"values":{"名称":[{"type":"text","text":"记录1"}]}}' \
  --record '{"values":{"名称":[{"type":"text","text":"记录2"}]}}'

# 使用字段 ID 作为 key
wecom-cli doc smart record add --docid "DOCID" --sheet-id "s1" \
  --key-type CELL_VALUE_KEY_TYPE_FIELD_ID \
  --record '{"values":{"fld1":[{"type":"text","text":"测试"}]}}'

# 删除记录
wecom-cli doc smart record delete --docid "DOCID" --sheet-id "s1" \
  --record-id "rec1" --record-id "rec2"

# 查询记录
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1"

# 查询指定记录
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1" \
  --record-id "rec1"

# 分页查询
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1" \
  --offset 0 --limit 100

# 自动分页获取全部记录
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1" --all

# 自动分页 + JSON 输出（获取全部记录的完整数据）
wecom-cli --json doc smart record query --docid "DOCID" --sheet-id "s1" --all

# 排序查询
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1" \
  --sort '{"field_title":"名称","desc":true}'

# 更新记录
wecom-cli doc smart record update --docid "DOCID" --sheet-id "s1" \
  --record '{"record_id":"rec1","values":{"名称":[{"type":"text","text":"新值"}]}}'

# JSON 输出
wecom-cli --json doc smart record query --docid "DOCID" --sheet-id "s1"
```

#### 记录过滤查询（filter_spec）

查询记录支持通过 `--filter` 选项传入过滤条件，每个 `--filter` 是一个 JSON 格式的 Condition，
多个条件通过 `--filter-conjunction` 指定 AND 或 OR 组合。

```bash
# 文本包含筛选
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1" \
  --filter '{"field_id":"f1","field_type":"FIELD_TYPE_TEXT","operator":"OPERATOR_CONTAINS","string_value":{"value":["hello"]}}'

# 数字大于筛选
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1" \
  --filter '{"field_id":"f2","field_type":"FIELD_TYPE_NUMBER","operator":"OPERATOR_IS_GREATER","number_value":{"value":10}}'

# 日期为今天
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1" \
  --filter '{"field_id":"f3","field_type":"FIELD_TYPE_DATE_TIME","operator":"OPERATOR_IS","date_time_value":{"type":"DATE_TIME_TYPE_TODAY"}}'

# 为空判断
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1" \
  --filter '{"field_id":"f4","field_type":"FIELD_TYPE_TEXT","operator":"OPERATOR_IS_EMPTY"}'

# 多条件 AND 组合（默认）
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1" \
  --filter '{"field_id":"f1","field_type":"FIELD_TYPE_TEXT","operator":"OPERATOR_CONTAINS","string_value":{"value":["hello"]}}' \
  --filter '{"field_id":"f2","field_type":"FIELD_TYPE_NUMBER","operator":"OPERATOR_IS_GREATER","number_value":{"value":10}}'

# 多条件 OR 组合
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1" \
  --filter-conjunction CONJUNCTION_OR \
  --filter '{"field_id":"f1","field_type":"FIELD_TYPE_TEXT","operator":"OPERATOR_IS","string_value":{"value":["A"]}}' \
  --filter '{"field_id":"f1","field_type":"FIELD_TYPE_TEXT","operator":"OPERATOR_IS","string_value":{"value":["B"]}}'
```

**支持的操作符**：
- OPERATOR_IS（等于）、OPERATOR_IS_NOT（不等于）
- OPERATOR_CONTAINS（包含）、OPERATOR_DOES_NOT_CONTAIN（不包含）
- OPERATOR_IS_GREATER（大于）、OPERATOR_IS_GREATER_OR_EQUAL（大于或等于）
- OPERATOR_IS_LESS（小于）、OPERATOR_IS_LESS_OR_EQUAL（小于或等于）
- OPERATOR_IS_EMPTY（为空）、OPERATOR_IS_NOT_EMPTY（不为空）

**值类型**：
- `string_value`：文本/网址/电话/邮箱/单选/多选 - `{"value":["文本值"]}`
- `number_value`：数字/进度 - `{"value": 123}`
- `bool_value`：复选框 - `{"value": true}`
- `user_value`：人员/创建人/编辑人 - `{"value": ["成员ID"]}`
- `date_time_value`：日期 - `{"type":"DATE_TIME_TYPE_TODAY"}` 或 `{"type":"DATE_TIME_TYPE_DETAIL_DATE","value":["1715846245084"]}`

**日期类型**：
- DATE_TIME_TYPE_DETAIL_DATE（具体时间，需提供毫秒时间戳）
- DATE_TIME_TYPE_TODAY, DATE_TIME_TYPE_TOMORROW, DATE_TIME_TYPE_YESTERDAY
- DATE_TIME_TYPE_CURRENT_WEEK, DATE_TIME_TYPE_LAST_WEEK, DATE_TIME_TYPE_CURRENT_MONTH
- DATE_TIME_TYPE_THE_PAST_7_DAYS, DATE_TIME_TYPE_THE_NEXT_7_DAYS
- DATE_TIME_TYPE_LAST_MONTH, DATE_TIME_TYPE_THE_PAST_30_DAYS, DATE_TIME_TYPE_THE_NEXT_30_DAYS

**注意**：`--filter` 不支持和 `--sort` 同时使用。

### 版本信息

```bash
wecom-cli version

# JSON 输出
wecom-cli --json version
```

## 项目结构

```
wecom-cli/
├── src/
│   └── wecom_cli/
│       ├── __init__.py
│       ├── cli.py                 # 主CLI入口
│       ├── config.py              # 配置文件管理（TOML）
│       ├── doc_registry.py        # 文档注册表
│       ├── output.py              # 输出工具模块
│       ├── api/                   # 企业微信 API 封装
│       │   ├── client.py          # HTTP 客户端
│       │   ├── auth.py            # Token 管理
│       │   └── doc.py             # 文档/子表/字段/记录 API
│       └── commands/
│           ├── config/            # 配置管理命令
│           │   └── config_app.py
│           └── doc/
│               ├── doc_app.py      # doc命令入口
│               ├── add.py          # add命令实现
│               ├── delete.py       # delete命令实现
│               ├── rename.py       # rename命令实现
│               ├── share.py        # share命令实现
│               └── smart/
│                   ├── smart_app.py
│                   ├── create.py   # create命令实现
│                   ├── field/      # 字段操作命令
│                   │   ├── field_app.py
│                   │   ├── add.py
│                   │   ├── delete.py
│                   │   ├── update.py
│                   │   └── query.py
│                   ├── record/     # 记录操作命令
│                   │   ├── record_app.py
│                   │   ├── add.py
│                   │   ├── delete.py
│                   │   ├── update.py
│                   │   └── query.py
│                   └── sheet/      # 子表操作命令
│                       ├── sheet_app.py
│                       ├── add.py
│                       ├── delete.py
│                       ├── update.py
│                       └── query.py
├── tests/
│   ├── test_config.py
│   ├── test_client.py
│   ├── test_auth.py
│   ├── test_config_commands.py
│   ├── test_cli.py
│   ├── test_output.py
│   ├── test_cli_json.py
│   ├── test_doc_json.py
│   ├── test_api_doc.py
│   ├── test_api_field_record.py
│   ├── test_field_commands.py
│   └── test_record_commands.py
├── pyproject.toml
├── README.md
└── .gitignore
```

## 开发

```bash
# 安装依赖
uv sync

# 运行 CLI（开发环境）
uv run wecom-cli --help

# 运行测试
uv run pytest

# 代码检查
uv run ruff check .

# 代码格式化
uv run ruff format .
```

## 技术栈

- Python 3.12+
- Typer（CLI 框架）
- Rich（终端输出）
- httpx（HTTP 客户端）
- pytest（测试）
- ruff（代码检查与格式化）

## 开发流程

详见 [AGENTS.md](./AGENTS.md)
