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

# WeCom CLI

企业微信命令行工具，支持多级命令结构。既可作为 CLI 使用，也可作为 Python 库导入。

## 安装

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

## 使用

### 全局约定

- 所有命令都支持 `--json/-j` 参数，以 JSON 格式输出结果
- 文档操作可通过 `--docid/-d` 或 `--name/-n` 指定文档（二选一）
- 纯文本输出，便于 LLM 阅读和管道处理

### Python 库使用

```python
from wecom_cli.api.auth import get_access_token
from wecom_cli.api.doc.mng import create_doc
from wecom_cli.api.doc.smart.record import get_records

token = get_access_token()
result = create_doc(token, doc_type=10, doc_name="我的文档")
records = get_records(token, docid="DOC_ID", sheet_id="SHEET_ID",
                       key_type="CELL_VALUE_KEY_TYPE_FIELD_TITLE")
```

#### 自定义配置文件路径

```python
from wecom_cli.config.config import init_config, reset_config

# 指定自定义配置文件路径（文件不存在时自动创建含 auth + proxy 空模板）
init_config("/path/to/my-config.toml")

# 后续所有配置操作（包括 auth、registry）自动使用该路径
from wecom_cli.api.auth import get_access_token
token = get_access_token()

# 重置为默认配置路径
reset_config()
```

### 查看帮助

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

### 配置管理

```bash
# 初始化配置
wecom-cli config init

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

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

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

# JSON 输出
wecom-cli config get auth.corpid -j

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

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

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

# 查看 Token 状态
wecom-cli config token

# 代理配置
wecom-cli config proxy --http http://proxy:8080 --https https://proxy:8443
```

### 文档管理

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

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

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

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

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

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

### 智能表格子表操作

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

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

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

# 查询子表信息
wecom-cli doc smart sheet query --name/-n "文档名称" --sheet-id/-s "123abc"
```

### 智能表格字段操作

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

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

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

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

# 更新字段
wecom-cli doc smart field update --docid/-d "DOCID" --sheet-id/-s "s1" \
  --field-id/-f "fld1" --title/-t "新名称" --type/-T FIELD_TYPE_TEXT
```

### 智能表格记录操作

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

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

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

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

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

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

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

# 自动分页 + JSON 输出
wecom-cli doc smart record query --docid/-d "DOCID" --sheet-id/-s "s1" --all/-a -j

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

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

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

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

# 多条件 AND 组合（默认）
wecom-cli doc smart record query --docid/-d "DOCID" --sheet-id/-s "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/-d "DOCID" --sheet-id/-s "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"]}}'
```

### 版本信息

```bash
wecom-cli version
wecom-cli version -j
```

## 参数短选项速查表

| 参数 | 短选项 | 说明 |
|------|--------|------|
| --json | -j | JSON 格式输出 |
| --docid | -d | 文档 ID |
| --name | -n | 文档名称 |
| --sheet-id | -s | 子表 ID |
| --field-id | -f | 字段 ID |
| --field-title | -F | 字段标题 |
| --title | -t | 标题 |
| --type | -T | 类型 |
| --record-id | -r | 记录 ID |
| --record | -r | 记录 JSON |
| --key-type | -k | Key 类型 |
| --offset | -o | 偏移量 |
| --limit | -l | 分页大小 |
| --property | -p | 属性 |
| --filter | 无 | 过滤条件 |
| --all | -a | 获取全部 |
| --new-name | -N | 新名称 |
| --index | -i | 位置索引 |
| --admin | -a | 管理员 |
| --http | -h | HTTP 代理 |
| --https | -S | HTTPS 代理 |
| --json-value | -J | JSON 值 |
| --all-type | -A | 所有类型 |

## 技术栈

- Python 3.12+
- Typer（CLI 框架）
- httpx（HTTP 客户端）
- tomli-w（TOML 写入）
- pytest（测试）
- ruff（代码检查与格式化）

## 开发

```bash
uv sync
uv run wecom-cli --help
uv run pytest
uv run ruff check .
uv run ruff format .
```

## 开发流程

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