Metadata-Version: 2.4
Name: yswj-internal-cli
Version: 0.3.0
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)。执行查询、导出和写入任务时，另请提供 [AI CLI 使用指南](src/yswj_internal_cli/AI_USAGE.md)，其中包含命令、字段定义和返回结构。由当前源码构建的安装包会包含这三份文档。

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

```bash
uvx --from yswj-internal-cli==0.3.0 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`、`performance`、`performance-tasks` 和 `mail`。常规业务资源及绩效列表每次最多读取 500 条；常规业务资源可使用 `--all` 或 `export` 翻页。邮件列表使用服务端分页。详细命令、字段、返回结构及权限行为见 [AI CLI 使用指南](src/yswj_internal_cli/AI_USAGE.md)。

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

## 写入命令

API Key 默认只读。在系统页面为具体数据模块分别授予新建、修改或删除权限后，CLI 才可执行对应命令；当前账号的网页端业务规则仍然生效。写入内容使用 UTF-8 JSON 文件，`--input -` 可从标准输入读取，但不要将业务数据放进命令参数。

```bash
# leads.json 内容示例：{"name":"新客户商机","company":"示例公司"}
yswj-internal leads create --input leads.json

# change.json 内容示例：{"name":"更新后的商机名"}
yswj-internal leads update 101 --input change.json

# 项目经理提交修改审批，change.json 可包含 status 和 reason
yswj-internal projects request-change 501 --input change.json

# 管理员或项目经理上级可按网页规则直接修改项目
yswj-internal projects update 501 --input change.json

# 删除需要输入记录 ID 确认；非交互脚本需显式指定 --yes
yswj-internal leads delete 101
```

所有资源均可 `create`、`update`。只有商机、渠道、联系人和跟进记录可 `delete`；项目和待跟进任务通过 `update` 修改 `status`。项目经理不能直接修改项目，须使用 `request-change` 提交审批。联系人电话、微信、邮箱和项目合同编号的写入还需单独的敏感字段权限；写入权限不自动授予读取这些字段的权限。删除商机或渠道会影响关联跟进记录和联系人关联，执行前请核对目标。

写入接口的字段、状态码和副作用见 [开放 API 规范](../docs/api-v1.md)。

## 命令帮助

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