# dcarpai-cli

**Repository Path**: andershsueh/dcarpai-cli

## Basic Information

- **Project Name**: dcarpai-cli
- **Description**: dcarpai-cli
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dcarpai-cli

![version](https://img.shields.io/badge/version-v0.0.1-blue)
![go](https://img.shields.io/badge/Go-1.24+-00ADD8)
![license](https://img.shields.io/badge/license-MulanPSL--2.0-lightgrey)

懂车拍(DongChePai)命令行工具 —— 把懂车拍平台的认证与业务查询能力 CLI 化。

第一个里程碑聚焦**认证态获取**(登录/状态/登出)与**待审核订单查询**,为后续把"约-传-审-提"更多业务能力搬上终端打下基础。

## 功能

```
dcarpai
├── auth                认证与登录态管理
│   ├── login           弹出浏览器完成登录,生成本地 API Key(ak-xxxx)
│   ├── status          查看当前登录状态与用户信息
│   └── logout          退出登录并清理本地凭证
└── orders              订单与审核任务
    └── pending         列出当前用户的待审核订单(默认 JSON)
```

## Dual-surface 帮助系统(面向人类与 AI Agent)

dcarpai-cli 采用 [Dual-surface CLI Design](https://gitee.com/andershsueh/gitee-cli)——同一份 CLI 长两张脸:

- **`--help`**:面向人类,短、干净,3 秒能扫到要点。
- **`--agent-help`**:面向 AI Agent,长、结构化,覆盖 11 个维度(前置/后置条件、幂等性、原子性、副作用、常见错误、编排提示、解析提示等)。

```bash
# 人类:简短帮助
dcarpai orders pending --help

# Agent:结构化文档
dcarpai orders pending --agent-help

# Agent:机器可解析 JSON
dcarpai orders pending --agent-help --output json

# 全命令覆盖矩阵
dcarpai --agent-help
```

**可达性三法则**:`--agent-help` 无条件可达——不因缺参数而不可达,不因没登录而不可达,不因探测本身而产生副作用。`auth login` 等 operational 命令的 `--agent-help` 打印 n/a 信号后立即退出,**绝不真的弹出浏览器**。

覆盖状态:`orders pending` 提供完整 agent-help;`auth login/status/logout` 为 operational 命令,标 n/a。

## 快速开始

### 安装(从源码构建)

需要 Go 1.24+ 与本地 Chrome 浏览器(login 命令通过 chromedp 驱动 Chrome)。

```bash
cd dcarpai-cli
go build -o dcarpai .
```

### 登录

```bash
./dcarpai auth login
```

浏览器会自动弹出懂车拍登录页,完成登录(邮箱 + 验证码)后,CLI 自动抓取 token 并生成 API Key:

```
登录成功!
  用户:     薛余恒
  登录终端: mgnt_login
  环境:     test

═══════════════════════════════════════════════════════
  你的 API Key(仅显示一次,请严格保管,切勿泄漏):

    ak-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
═══════════════════════════════════════════════════════
```

将 API Key 设为环境变量(推荐):

```bash
export DCARPAI_KEY=ak-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

之后所有命令自动复用本地登录态,**无需重复登录**。

### 查看登录状态

```bash
./dcarpai auth status
```

### 列出待审核订单

```bash
# 默认输出 JSON(便于管道消费)
./dcarpai orders pending --page 1 --size 20

# 人类可读汇总
./dcarpai orders pending --size 20 --output text
```

JSON 输出为后端 `POST /system/approve/taskList(tagPage=1)` 的原始响应,含 `total` 与 `rows`(每条订单的完整字段)。

### 退出登录

```bash
./dcarpai auth logout
```

## API Key 与凭证设计(路线 B)

`dcarpai auth login` 生成的 `ak-xxxx` 是**本地映射指针**,而非真实 token:

- **真实 token**(JWT)锁在 `~/.dcarpai/credentials.json`,文件权限 `0600`。
- `ak-xxxx` 写入 `~/.dcarpai/settings.json` 或环境变量 `DCARPAI_KEY`,仅作为"用户已登录"的标志,**本身泄漏无害**。
- CLI 运行时通过环境变量 / settings 确认持有指针,再从 `credentials.json`(0600)取出真实 token 调用接口。

凭证读取优先级:
1. 环境变量 `DCARPAI_KEY`
2. `~/.dcarpai/settings.json` 的 `api_key`
3. 本地 `credentials.json` 存在即视为已登录

### token 有效期

懂车拍后端 token 有效期 **24 小时**,且**每次请求自动滑动续期**(重置回 24h)。因此**只要每天用一次,token 永不过期**;连续 24 小时不使用才需要重新 `auth login`。详见 `raw/` 下的分析文档。

## 全局选项

| 选项 | 默认 | 说明 |
|------|------|------|
| `--env` | `test` | 环境(test/dev/prod),dev/prod 需配合 `--gateway` |
| `--gateway` | (按 env 推导) | 覆盖网关地址 |
| `--output` | `text` | 输出格式(json/text);`orders pending` 默认 json |
| `--agent-help` | `false` | 显示面向 AI Agent 的结构化帮助(见上) |
| `-h, --help` | - | 面向人类的简短帮助 |

## 本地文件

| 路径 | 权限 | 内容 |
|------|------|------|
| `~/.dcarpai/credentials.json` | 0600 | 真实 token + 用户信息(敏感) |
| `~/.dcarpai/settings.json` | 0600 | API Key、环境、服务器地址 |
| `~/.dcarpai/chrome-profile/` | - | Chrome 用户数据(保留登录态,免重复输验证码) |

## 服务器配置(切换测试/生产服)

服务器地址存在 `~/.dcarpai/settings.json`,**切换环境只改配置不改源码**:

```json
{
  "app_srv_ip": "118.145.176.200",
  "app_srv_port": "8084"
}
```

- 首次运行时 CLI 自动创建该文件,默认填入测试服地址(`118.145.176.200:8084`)。
- 接入生产服时,把 `app_srv_ip` 改成生产服 IP(端口不同则一并改 `app_srv_port`)即可,所有命令(login/status/logout/orders)立即指向新服务器。
- 也可用 `--gateway` 临时覆盖网关地址(不改配置文件)。

CLI 运行时优先级:`--gateway` 覆盖 > settings.json 的 `app_srv_ip/port` > 默认测试服地址。

## 项目结构

```
dcarpai-cli/
├── main.go                 # 入口
├── cmd/                    # cobra 命令树(参数解析与编排)
│   ├── root.go             # 根命令 + persistent flags + --agent-help 注册
│   ├── common.go           # authClient/handleAPIError/printJSON 公共 helper
│   ├── agent_help.go       # Dual-surface:AgentHelpNA/AgentHelpAwareArgs/PrintAgentHelp
│   ├── auth*.go            # auth login/status/logout
│   └── orders*.go          # orders pending
├── internal/               # 业务实现
│   ├── config/             # 环境与网关地址解析、settings 读写
│   ├── auth/               # 登录态获取、凭证持久化、网关 HTTP 客户端
│   └── orders/             # 待审核订单查询
├── mvp/                    # 早期 MVP(独立 module,登录链路验证依据,保留参考)
└── raw/                    # 分析文档
```

## 技术栈

- Go 1.24+
- [cobra](https://github.com/spf13/cobra) v1.10.2 —— 命令行框架
- [chromedp](https://github.com/chromedp/chromedp) —— Chrome DevTools Protocol,驱动浏览器抓取登录 token

## 后端接口

| 命令 | 接口 | 说明 |
|------|------|------|
| `auth login` | 浏览器抓取 | 复用现有登录页,监听网络请求抓 Authorization token |
| `auth status` | `GET /system/user/new/login/info` | 当前登录用户信息 |
| `auth logout` | `DELETE /auth/logout` | 注销服务端会话 |
| `orders pending` | `POST /system/approve/taskList` | 当前用户作为审核人的待审核任务(`tagPage=1`) |

> 后端约定:Authorization 头直接放 token(不带 Bearer 前缀)。鉴权失败返回 HTTP 200 + body `{"code":401,...}`。

## 说明

- `mvp/` 是早期单文件版 CLI(独立 `go.mod`,模块名 `dcp-cli`),已跑通认证链路,作为新实现的参考保留,不编入当前二进制。
- `raw/` 存放懂车拍系统与后端鉴权机制的分析文档。

## 开发

```bash
go build -o dcarpai .          # 构建
go vet ./...                    # 静态检查
go run . --help                 # 直接运行
```

## 版本

- **v0.0.1**(当前):认证三件套(login/status/logout)+ 待审核订单查询(pending)+ Dual-surface 帮助系统。

## License

木兰宽松许可证 v2(MulanPSL-2.0)。