# tailocv-cli

**Repository Path**: self_5/tailocv-cli

## Basic Information

- **Project Name**: tailocv-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TailorCV-CLI

🚀 **TailorCV-CLI** 是一款专为开发者设计的、纯命令行（CLI）驱动的自动化简历定制生成智能体（Agent）。

不同于传统高冗余的 RAG（检索增强生成）系统，本项目采用创新的 **“多级知识蒸馏 (Multi-level Knowledge Distillation)”** 与 **“级联 Agent 检索 (Cascading Agent Retrieval)”** 架构，旨在以极致精简 of Token 消耗，实现高精度、无幻觉的人岗匹配与定制化简历生成。

---

## 🌟 核心特性

- **🎮 纯命令行极客体验**：无前端 UI，基于 `Typer` + `Rich` 构建高颜值的交互式终端输出，完美契合开发者的自动化工作流。
- **🔍 资产自动收割与扫描**：
  - **本地扫描 (LocalScanner)**：支持定义多个根目录，应用 `.gitignore` 规则智能过滤冗余文件（如 `node_modules/`, `venv/`, `.git/`）。
  - **远程扫描 (RemoteScanner)**：支持指定单 Git 仓库或 GitHub/Gitee 平台账号**全量探测**（自动拉取公开及私有仓库）。
- **⚡ 扫描器性能与健壮性优化**：
  - **按需独立扫描**：支持通过 `--local-only` 或 `--remote-only` 单独执行本地或远程资产扫描。
  - **只读列表探测**：提供 `--list-repos` 选项，仅拉取并展示排除过滤后的待克隆仓库列表，**不触发真实的 `git clone` 下载**，极大节约网络带宽与执行耗时。
  - **错误隔离与容错**：网络调用采用异常隔离设计（try-except），单平台或单接口出错（如 404/401）不中断扫描流程，异常以摘要形式友好呈现。
  - **精确过滤与分页**：支持使用 `exclude_repos` 配置排除指定仓库；分页逻辑无缝适配，防止大批量仓库时的丢失。
- **💡 极致省流（Token 优化）**：
  - 摒弃向量库，采用 **L1-单体资源摘要** -> **L2-主题聚合索引** -> **L3-全局索引（< 500 Tokens）** 的三层蒸馏结构。
  - Resume Agent 启动时仅载入轻量级的 L3 索引，必要时通过工具（Function Calling）自主下钻调用 L2/L1，相较于传统 RAG 降低 80%+ 无效 Token 消耗。

---

## 📐 系统架构与目录结构

### 架构概览

```text
                               ┌──────────────────┐
                               │   用户 CLI 入口  │
                               │     (main.py)    │
                               └────────┬─────────┘
                                        │
                       ┌────────────────┴────────────────┐
                       ▼                                 ▼
           ┌───────────────────────┐         ┌───────────────────────┐
           │     kb 知识库管理     │         │     resume 简历生成   │
           │  (src/commands/kb.py) │         │(src/commands/resume.py│
           └───────────┬───────────┘         └───────────┬───────────┘
                       │                                 │
           ┌───────────▼───────────┐         ┌───────────▼───────────┐
           │     扫描与提取层      │         │     简历 Agent 层     │
           │  (src/core/scanner.py)│         │(src/core/resume_agent)│
           └───────────┬───────────┘         └───────────┬───────────┘
                       │                                 │
  ┌────────────────────┼─────────────────────────────────┼────────────────────┐
  │ 存储载体           ▼                                 ▼                    │
  │ 本地文件系统   knowledge_base/                                            │
  │                ├── L1/ <hash>.json   (单文件/单仓库结构化 JSON 摘要)       │
  │                ├── L2/               (按 经历/项目/技能 聚合的 JSON)       │
  │                └── L3/ global_index.json (全局索引硬约束 < 500 Tokens)     │
  └───────────────────────────────────────────────────────────────────────────┘
```

### 目录结构

```text
tailocv-cli/
├── main.py                 # CLI 唯一入口
├── config.example.yaml     # 配置模版文件
├── .env.example            # 环境变量模版文件
├── memory-bank/            # 系统设计与开发进度文档（PRD, Architecture, Progress）
├── src/
│   ├── commands/
│   │   ├── kb.py           # 知识库管理命令组 (scan, extract, aggregate, index, build-all)
│   │   └── resume.py       # 简历定制命令组 (analyze, generate)
│   ├── core/
│   │   ├── config_loader.py# YAML 配置载入与校验
│   │   ├── scanner.py      # 本地文件/远程仓库扫描器（核心逻辑）
│   │   ├── llm_client.py   # LLM 封装（指数退避重试、Structured Output）
│   │   └── ...
│   └── models/
│       ├── config.py       # 全局配置的 Pydantic v2 模型
│       └── knowledge.py    # L1 / L2 / L3 / 简历生成的统一数据契约模型
└── tests/                  # 完备的单元测试与 Mock 测试
```

---

## 🛠️ 快速开始

### 1. 环境安装

```bash
# 克隆项目并进入
cd tailocv-cli

# 创建并激活虚拟环境
python -m venv venv
source venv/bin/activate  # macOS/Linux

# 安装依赖
pip install -r requirements.txt
```

### 2. 参数配置

复制模版文件进行配置：

```bash
# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填写您的 API Key（如 GEMINI_API_KEY）

# 配置文件源
cp config.example.yaml config.yaml
# 编辑 config.yaml 文件，指定您要扫描的本地笔记目录、代码库，或远程 GitHub/Gitee 账户
```

`.env` 变量配置示例：
```env
GEMINI_API_KEY="AIzaSy..."
GITHUB_TOKEN="github_pat_..."
GITEE_TOKEN="gitee_pat_..."
```

---

## 📖 命令行指南

### 1. 资产扫描调试 (`kb scan`)
仅用于本地文件或远程仓库的匹配测试，**不会调用大模型**，不消耗 Token。

```bash
# 扫描本地和远程配置下的所有数据资产（默认行为）
python main.py kb scan

# 仅扫描本地定义的笔记与项目
python main.py kb scan --local-only

# 仅扫描远程 Git 仓库，且不发生真实的 clone 行为，只列出检测到的仓库
python main.py kb scan --remote-only --list-repos
```

### 2. 简历生成与诊断 (`resume`)
根据具体的岗位职责需求描述（JD），动态匹配知识库资产，自主决策下钻拉取细节信息，最终渲染出 STAR 原则重构的简历。

```bash
# 预诊断与分析（输出人岗匹配度，展示 Agent 的“下钻检索计划”，不生成简历）
python main.py resume analyze --jd path/to/jd.txt

# 全量定制简历生成（诊断并输出定制化 Markdown 简历）
python main.py resume generate --jd path/to/jd.txt --out resume.md
```

---

## 🧪 运行测试

本地测试集集成了完备 of Mock 功能，支持在没有真实网络的情况下验证 GitHub/Gitee API 获取和分页过滤的逻辑。

```bash
# 运行全部单元测试
pytest

# 运行除需要网络的 slow 测试之外的所有测试
pytest -m "not slow" -v
```

---

## 🔒 安全与隐私

- **API 凭证隔离**：`.env` 与 `config.yaml` 已经写入忽略文件，API Token 仅通过系统环境变量读取，绝不硬编码。
- **本地化存储**：三层知识库蒸馏所产生的数据全部以 JSON 形式保存在您本地的 `knowledge_base/` 目录下，不会上传至任何第三方云端。
- **防止幻觉**：LLM 润色基于您的真实工作资产进行，在 Prompt 层面施加了强有力的反幻觉硬约束，严禁凭空捏造未掌握的技术或经历。