wecom-cli 0.1.1

企业微信命令行工具

WeCom CLI

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

安装

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

使用

全局选项

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

# 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

查看帮助

wecom-cli --help

配置管理

# 设置字符串值
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 等）

文档管理

# 创建文档
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

智能表格子表操作

# 添加子表
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 命令必填）

智能表格字段操作

# 添加字段
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}]}'

智能表格记录操作

# 添加记录
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 组合。

# 文本包含筛选
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 同时使用。

版本信息

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

开发

# 安装依赖
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