Metadata-Version: 2.4
Name: chukonu-cli
Version: 0.1.0
Summary: Chukonu search CLI — OAuth-gated access to se4ai general search and patent search via api-gateway.
Author: chukonu-team
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/chukonu-team/chukonu-cli
Project-URL: Repository, https://github.com/chukonu-team/chukonu-cli
Project-URL: Issues, https://github.com/chukonu-team/chukonu-cli/issues
Keywords: search,patent,chukonu,se4ai,cli,oauth
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13
Requires-Dist: filelock>=3.13
Requires-Dist: platformdirs>=4
Requires-Dist: tomli>=2; python_version < "3.11"
Requires-Dist: tomli-w>=1.0
Dynamic: license-file

# chukonu-cli

Python CLI for Chukonu 搜索网关 (api-gateway)，基于 [Typer](https://github.com/fastapi/typer)。

## 安装

```bash
python -m venv .venv
.venv/bin/pip install -e .
```

## 命令

| 命令 | 说明 |
|---|---|
| `chukonu-cli auth login [--provider {google,wechat}]` | OAuth Authorization Code Flow + PKCE + loopback 回调 |
| `chukonu-cli auth logout [--provider X] [--all] [--remote]` | 清理凭据，可同时在网关撤销 refresh token |
| `chukonu-cli auth status [--json]` | 查看登录状态；未登录 exit 1 |
| `chukonu-cli doctor [--json]` | 健康检查 (config / 凭据 / 网关 / token / 上游) |
| `chukonu-cli api <METHOD> <PATH> [flags]` | 通用 API 调用，自动注入 Bearer |
| `chukonu-cli search <query> [flags]` | 通用搜索，薄封装 `POST /se4ai/api/search` |
| `chukonu-cli patent {keyword,similar,advanced,get,stats}` | 专利搜索 |

## 文件布局

- 配置：`~/.chukonu-cli/config.toml`
- 文件锁：`~/.chukonu-cli/locks/`
- 明文凭据：`~/.local/share/chukonu-cli/credentials.json` (0600)

## 登录安全模型

CLI ↔ 网关采用 OAuth 2.0 Authorization Code Flow + PKCE (RFC 7636, S256)：

1. CLI 生成高熵 `code_verifier` 与 `code_challenge = BASE64URL(SHA256(verifier))`
2. CLI 启动 `127.0.0.1:<port>` loopback HTTP server 作为 `redirect_uri`
3. 浏览器访问 `{gateway}/auth/{provider}/login?redirect_uri=...&state=...&code_challenge=...&code_challenge_method=S256`
4. 网关重定向到上游 provider，用户授权后回网关 `/auth/{provider}/callback`
5. 网关仅回 `?code=<一次性码>&state=...` 给 loopback (**access_token 不再进浏览器 URL**)
6. CLI 立刻 `POST /auth/token` 带上 `code` + `code_verifier` + `redirect_uri` 换取 session (access/refresh token)
7. 凭据写入 `credentials.json` (明文，0600)

支持的 provider：
- `google` —— 标准 OIDC，网关验 id_token (RS256 via JWKS)，subject = Google `sub`
- `wechat` —— 微信开放平台网站应用 `snsapi_login` 扫码，网关调 `sns/oauth2/access_token` 拿 openid/unionid，subject 优先 unionid 回退 openid

两条路径在 CLI 侧完全对称，凭据文件可同时保留多个 provider，`current` 字段决定默认使用哪个。

## 切换默认 provider

编辑 `~/.chukonu-cli/config.toml`：

```toml
default_provider = "wechat"
```

或每次用 `--provider wechat` 临时覆盖。

## Skills

`skills/chukonu-search-general/` 与 `skills/chukonu-search-patent/` 为 AI Agent (例如 Claude Code) 接入搜索能力。

## 作为 Claude Code 插件安装

本仓库本身即是一个 Claude Code 插件 marketplace，内含 `chukonu-cli` 插件（含 `chukonu-search-general` / `chukonu-search-patent` 两个 skill）。

前置：已 `pip install -e .` 或 `pip install chukonu-cli`，并完成 `chukonu-cli auth login`。

```bash
# 在 Claude Code 中
claude plugin marketplace add chukonu-team/chukonu-cli
claude plugin install chukonu-cli@chukonu
```

安装后 skill 会以 `chukonu-cli:chukonu-search-general` 与 `chukonu-cli:chukonu-search-patent` 暴露，Claude 会按需自动调用。

本地开发调试：

```bash
claude plugin marketplace add /absolute/path/to/chukonu-cli
claude plugin install chukonu-cli@chukonu
# 修改 SKILL.md 后
/plugin marketplace update chukonu
```
