Metadata-Version: 2.4
Name: atclib-cli
Version: 0.4.0
Summary: OAuth command-line client for the KiSpace content library
Requires-Python: >=3.13
Requires-Dist: agent-skill-dist>=0.1.1
Requires-Dist: av>=18.0.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: keyring>=25.6.0
Requires-Dist: mypy>=2.3.0
Requires-Dist: pillow>=12.0.0
Requires-Dist: platformdirs>=4.3.0
Requires-Dist: ruff>=0.16.1
Requires-Dist: typer>=0.24.2
Provides-Extra: dev
Requires-Dist: pytest>=9.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# ATCLib CLI

`atclib` 是琦琦内容生产库的 OAuth 命令行客户端。它使用 OAuth 2.0 Device Authorization 登录，可查询、创建、上传并发布素材和后处理内容。

## 安装与登录

```bash
uv tool install .
atclib login --client-id oc_example
atclib whoami
```

默认服务为 `https://atclib.kispace.cn`。可用 `ATCLIB_SERVER_URL` 或任意命令的 `--server` 临时覆盖。

管理员须在平台创建公开 OAuth Client：名称 `atclib-cli`、Token 端点认证选择“公开客户端”、开启 PKCE，并允许以下 scopes：

`profile:read materials:read materials:write post_process_contents:read post_process_contents:write knowledge_bases:read`

平台要求注册 redirect URI；Device Flow 不会使用它，可登记 `http://127.0.0.1:8765/oauth/callback`。将平台生成的 `client_id` 提供给 CLI 用户。

刷新令牌保存在系统密钥链；本地配置只保存服务地址和 client ID。`atclib logout` 会撤销并删除本地令牌。

## 知识库

知识库是一个包含 `manifest.json`、`index.md`、`references.jsonl` 与词条 Markdown 的本地目录。登记与同步均通过异步任务执行（两阶段上传：先传 manifest/references 创建任务，再逐个上传条目文件，文件齐全后自动处理）。

```bash
atclib kb list
atclib kb register ./kb/产品手册          # 两阶段上传登记（等待处理完成后退出）
atclib kb sync 1 ./kb/产品手册            # 重新上传并整体替换知识库快照
atclib kb tasks                          # 分页列出我的知识库任务（默认每页 5 条）
atclib kb task 12                        # 任务详情：状态、缺失文件、错误信息
atclib kb manifest 1
atclib kb tree 1 --path docs --depth 2
atclib kb entry 1 docs/intro.md          # 解析后的词条（含正文 markdown）
atclib kb entry 1 docs/intro.md -o ./intro.md
atclib kb content 1 docs/api.md -o ./api.md   # 原始文件内容
atclib kb pull 1 -o ./kb-export           # 导出整个知识库为本地 markdown 目录
atclib kb unregister 1
```

任务默认等待处理完成（超时 300 秒）；`--timeout 0` 表示只创建任务不等待，稍后用 `atclib kb task <id>` 查询。

## 常用命令

```bash
atclib material list --q "选题"
atclib material category-list
atclib material create "产品访谈" --category cat_123 --content-file ./interview.md --publish
atclib material create "原始图片" --kind image --category cat_123 --file ./cover.png
atclib material upload material_123 ./appendix.pdf
atclib material publish material_123

atclib content create "访谈摘要" --method "人工摘要" --material material_123 --category cat_123 \
  --content-file ./summary.md --publish
atclib content list --q "摘要"
```

附件支持单文件与 multipart 直传；上传中断后可用 `material upload-resume` 或 `content upload-resume` 加上资源 ID、会话 ID 和相同文件路径继续。所有命令都支持全局 `--json`，便于脚本处理。

## Agent skill

CLI wheel 内置了 `atclib-cli` agent skill。安装后，Codex 或其他兼容 skill 目录约定的 agent 可以通过该 skill 获取当前版本 CLI 的操作说明。

查看 skill 安装状态：

```bash
atclib skill status
atclib --json skill status
```

安装到当前仓库 `.agents/skills/`：

```bash
atclib skill install --target repo
# ./.agents/skills/atclib-cli
```

安装到用户全局 Codex skills 目录：

```bash
atclib skill install --target global
# ${CODEX_HOME:-~/.codex}/skills/atclib-cli
```

目标已存在时覆盖安装：

```bash
atclib skill install --target repo --yes
```

也可以指定自定义 skills 根目录：

```bash
atclib skill install --output .agents/skills --yes
```

内置 skill 通过 `agent-skill-dist` 分发，随 ATCLib CLI wheel 一起发布，因此 CLI 升级后可以重新运行 `atclib skill install --yes` 同步 agent 使用的 skill。
