Metadata-Version: 2.4
Name: yswj-internal-cli
Version: 0.1.2
Summary: Command-line client for 元生无界内部管理系统
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: keyring<26,>=25.7

# 元生无界内部管理系统 CLI

命令名：`yswj-internal`。CLI 通过系统开放 API 读取数据，权限仍由 API Key 和服务端账号权限控制。

## 安装

需要 Python 3.10 或更新版本。建议用 `pipx` 安装隔离环境：

```bash
pipx install yswj-internal-cli
```

也可以在虚拟环境中安装：

```bash
python -m pip install yswj-internal-cli
```

在本仓库开发时，也可以从本地目录安装：

```bash
pipx install ./cli
```

给 AI 助手配置时，请先阅读 [一键配置卡](src/yswj_internal_cli/AI_ONE_CLICK.md)；详细流程见 [AI 配置指南](src/yswj_internal_cli/AI_SETUP.md)。安装后的 Python 包中也包含这两份文档。

macOS 或 Windows 用户在系统页面复制自己的 API Key 后，可让 AI 在本机执行一条命令完成安装和配置：

```bash
uvx --from yswj-internal-cli==0.1.2 yswj-internal setup --from-clipboard
```

需要验证已授权模块时，可加 `--verify projects` 等参数。验证最多请求一条记录，不打印业务数据。其他系统可运行 `yswj-internal setup`，在本地终端的隐藏提示中输入 Key。

## 配置

先在系统的“API Key 管理”页面申请 Key，再设置站点地址和密钥：

```bash
yswj-internal --profile prod config set-server http://39.107.72.34:6611 --activate
yswj-internal --profile prod config set-key
yswj-internal config show
```

`set-key` 会隐藏输入内容。若系统密钥库可用，Key 会保存到系统密钥库；否则保存到本地配置文件，并在 macOS/Linux 上限制为当前用户可读写。配置文件位于 `~/.config/yswj-internal/config.json`，可用 `YSWJ_INTERNAL_CONFIG` 覆盖。

当前线上地址可直连，但使用 HTTP。安装和本机配置不要求 OpenVPN；验证或读取数据会明文传输 API Key，请通过受信任的 VPN 或 HTTPS 入口发送含 Key 的请求。配置 HTTP 地址时 CLI 会显示提醒。

脚本环境也可以通过 `YSWJ_INTERNAL_PROFILE`、`YSWJ_INTERNAL_BASE_URL` 和 `YSWJ_INTERNAL_API_KEY` 临时覆盖配置。不要把 Key 放在 URL、代码仓库或命令行参数中。

## 数据命令

列表默认输出表格；需要程序处理时选择 JSON，需要电子表格时选择 CSV。

```bash
yswj-internal leads list
yswj-internal --profile prod leads list --all --updated-since 2026-11-01T00:00:00+08:00 --format json
yswj-internal contacts get 201 --format json
yswj-internal projects export --format csv --output projects.csv --updated-since 2026-11-01T00:00:00+08:00
yswj-internal activities list --created-since 2026-11-01T00:00:00+08:00 --limit 50
```

支持 `leads`、`channels`、`contacts`、`activities`、`follow-up-tasks` 和 `projects`。普通列表默认只取 100 条，最多 500 条；全量导出默认每页 500 条并顺序翻页，减少请求次数。全量读取仅在显式使用 `--all` 或 `export` 时进行。商机、渠道、联系人、待跟进任务和项目支持 `--updated-since`；跟进记录支持 `--created-since`。时间必须包含时区；定期同步建议优先使用增量时间筛选。

`export` 会顺序读取所有页并写入指定文件；CSV 按页流式写盘，避免大批数据占满内存，交互终端会显示读取进度。大数据集建议使用 CSV 和增量时间筛选。联系人私密字段、项目财务字段以及各数据范围仍遵循该 Key 的权限；CLI 不会扩大 Key 权限。

## 命令帮助

```bash
yswj-internal --help
yswj-internal leads list --help
yswj-internal config --help
```
