ATCLib CLI

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

安装与登录

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 创建任务，再逐个上传条目文件，文件齐全后自动处理）。

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> 查询。

常用命令

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 安装状态：

atclib skill status
atclib --json skill status

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

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

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

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

目标已存在时覆盖安装：

atclib skill install --target repo --yes

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

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

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