Metadata-Version: 2.4
Name: jvkit
Version: 0.0.5
Summary: AI-native CLI toolkit: document reading, note management, image organizing, storage analysis, and Markdown-to-academic-Word conversion
Requires-Python: >=3.12
Requires-Dist: mistune>=3.0.2
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pymupdf4llm>=1.27.2.3
Requires-Dist: python-docx>=1.2.0
Requires-Dist: python-pptx>=1.0.2
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: tabulate>=0.10.0
Requires-Dist: typer>=0.26.3
Description-Content-Type: text/markdown

# jv-cli — AI 协作者的基础设施

> 一个命令，搞定 AI 时代所有重复操作。

你用 Claude 写代码、用 Kimi 读文档、用 Codex 生成脚本 —— 但你的**系统提示词散落在各个对话框**，你的**项目规范靠复制粘贴**，你的**下载文件夹永远是一堆随机文件名**，你的**磁盘空间靠右键属性逐个查看**。

jv-cli 不是又一个"个人工具库"。它是**AI-native 的命令行基础设施** —— 每一个功能都回答一个真实的、每天重复三次以上的痛点。

---

## 痛点场景（你中了几条？）

| 痛点 | 以前的解法 | jv-cli 的解法 |
|------|-----------|--------------|
| 多 AI 工具的系统提示词散落各处 | Notion、Obsidian、各种文本文件 | `jv note` — 统一管理，一键复制到剪贴板 |
| AI 写代码不遵循项目规范 | 每次手动创建目录结构、复制规范文件 | `jv note init` — 笔记即模板，一键生成项目脚手架 |
| 和 AI 的多轮对话想复用上下文 | 复制粘贴、截图、或者重新描述 | `jv note update` — 追加模式，会话历史自动叠加 |
| 下载的图片全是 `IMG_20240601_123456.jpg` | 手动右键重命名，或者写脚本 | `jv rename` — 一键按文件夹独立编号 |
| 想知道哪个文件夹占了多少空间 | 右键属性逐个看，或者下载工具 | `jv usage` — 表格化输出，AI 直接读 |
| 需要把 PDF/Word/Excel/PPT 给 AI 分析 | 打开文件复制粘贴，或者装一堆转换工具 | `jv read` — 统一转 Markdown，中文零配置 |
| Markdown 写完了要交 Word 格式论文 | Pandoc 调半天格式，或者手动排版 | `jv mtow` — 一键生成中文学术论文格式 Word |

---

## 安装

```bash
pip install jv-cli
```

或者从源码：

```bash
git clone https://github.com/yourname/jv-cli.git
cd jv-cli
uv pip install -e .
```

---

## 六大核心能力

### 1. `jv note` — 知识资产管理（不只是笔记）

你以为它是笔记工具？它是你的**AI 协作文档中心**。

```bash
# 添加一条系统提示词
jv note add "react-component-prompt"

# 查看（同时标记使用频率，热度高的自然上浮）
jv note show 1

# 一键复制到剪贴板，直接贴给 Claude / Kimi / Codex
jv note copy 1

# 多轮对话追加记录（自动加 --- 分隔线）
jv note update 1 --content "第二轮优化建议..."

# 按分组查看所有 prompts
jv note list --group prompts

# 搜索
jv note search "React"
```

**为什么这是痛点？**

- Claude 的 Project 指令、Kimi 的常用语、Codex 的 system prompt —— 散落在三个平台
- `jv note` 把它们统一成本地文件（YAML frontmatter + Markdown），**你拥有数据所有权**
- `usage_count` 自动追踪使用频率，**高频 prompt 自然上浮，冷门下沉**
- `--no-bump` 让 AI 脚本调用时不污染数据，**区分人机交互**

#### `jv note init` — 笔记即模板，一键生成项目结构

你的笔记内容是一个 YAML 模板：

```yaml
directories:
  src: {}
  tests: {}
  docs: {}
files:
  - path: AGENTS.md
    note_id: 42        # 引用另一个笔记的内容
  - path: README.md
    content: "# {{project_name}}"
  - path: src/main.py
    content: |
      def main():
          print("Hello, {{project_name}}!")
```

```bash
# 一键生成项目脚手架
jv note init 6 --to ./my-project --name "my-project"
```

输出：
```
Initialized: D:/work/my-project
Project: my-project
Dirs: src, tests, docs
Files: AGENTS.md, README.md, src/main.py
```

**为什么这是痛点？**

- AI 写代码时从来不创建目录结构，或者创建得不规范
- 每次新项目都要手动复制 `AGENTS.md`、`.gitignore`、`pyproject.toml`
- `jv note init` 让**笔记成为模板仓库**，项目规范一键落地

---

### 2. `jv read` — 文档转 Markdown（中文零配置）

```bash
# PDF → Markdown
jv read paper.pdf -o paper.md

# Word → Markdown
jv read report.docx -o report.md

# Excel → Markdown（每个 Sheet 一个表格）
jv read data.xlsx -o data.md

# PPT → Markdown（每页一个二级标题）
jv read slides.pptx -o slides.md
```

**为什么不是 MarkItDown？**

| | MarkItDown | jv read |
|--|-----------|---------|
| 中文支持 | ❌ 需装字体、设 `PYTHONUTF8=1` | ✅ 开箱即用，UTF-8 默认 |
| Windows 终端 | ❌ GBK 直接崩溃 | ✅ 不受影响 |
| 安装体积 | ❌ `markitdown[all]` 几十MB+ | ✅ 轻量依赖 |
| 输出到文件 | stdout，需重定向 | ✅ `-o` 一键 |

---

### 3. `jv usage` — 目录存储分析（AI 友好）

```bash
# 分析当前目录
jv usage

# 递归子目录，深度 2
jv usage ~/Downloads --depth 2

# 按文件类型分组
jv usage . --by-type

# 升序（小的在上面）
jv usage . --asc
```

输出：
```
Name                   Size  Type
---------------------------------------
src/               165.0 KB  folder
README.md            1.9 KB  .md
pyproject.toml        519 B  .toml
---------------------------------------
Total              203.4 MB
```

**为什么这是痛点？**

- Windows 右键属性只能看一个文件夹
- `du` 输出是纯文本，AI 不好解析
- `jv usage` 输出**表格化结构**，直接贴给 AI："帮我分析哪个文件夹可以清理"

---

### 4. `jv rename` — 图片批量重命名

```bash
# 当前目录图片按文件夹独立编号
jv rename

# 递归处理子目录
jv rename ./pics --depth 2

# 预览（不实际执行）
jv rename ./pics -n

# 从 10 开始编号
jv rename ./pics --start 10

# 固定 3 位序号
jv rename ./pics -p 3

# 自定义格式
jv rename ./pics -f "img_{n}{ext}"
```

**为什么这是痛点？**

- 浏览器下载的图片全是 `IMG_20240601_123456.jpg`
- 做前端时下载一批素材图，需要按顺序编号再写代码引用
- 手动重命名 50 张图？不可能。写脚本？懒得写。
- `jv rename` 一键搞定，**纯数字文件保护不覆盖**

---

### 5. `jv sortimg` — 图片按扩展名归类

```bash
# 按扩展名归到子文件夹
jv sortimg ./pics

# 递归处理
jv sortimg ./pics --depth 2

# 预览
jv sortimg ./pics -n
```

输出效果：
```
pics/
├── jpg/
│   ├── 1.jpg
│   └── 2.jpg
├── png/
│   ├── 3.png
│   └── 4.png
└── webp/
    └── 5.webp
```

---

### 6. `jv mtow` — Markdown 转中文学术论文 Word

```bash
# 默认 academic 格式
jv mtow convert paper.md -o paper.docx

# 查看支持的格式规则
jv mtow info
```

格式规则（academic 类型）：
- 页面：A4，页边距 上2.5/下2.5/左3.2/右3.2cm
- 正文：宋体+Times New Roman 小四号(12pt)，1.5倍行距，首行缩进2字符
- 一级标题：黑体小二号(18pt)，居中，2倍行距
- 二级标题：黑体小三号(15pt)，左对齐
- 三级标题：黑体四号(14pt)，左对齐
- 页眉：隶书三号(16pt)，居中，带下横线
- 页脚：小五号页码，居中
- 支持：公式占位符、列表、表格、代码块、引用标注 `[1]` 上角标

**为什么这是痛点？**

- Pandoc 能转 Word，但没有中文学术论文格式预设
- 手动调格式：字体、字号、行距、缩进、页眉页脚 —— 2小时起步
- `jv mtow` 一键生成，**配置驱动**（`config.py`），换 `--type` 即可支持其他领域格式

---

## 设计理念：AI-Native

### 每一个输出都为了被 AI 解析

- `jv usage` → 表格，AI 直接读
- `jv note list` → 表格，AI 直接选 ID
- `jv read` → 标准 Markdown，AI 直接理解结构
- `jv mtow` → 从 Markdown 生成，AI 写的论文直接转 Word

### 每一个命令都支持 `--output/-o`

AI 调用时不依赖终端输出，直接写文件：

```bash
jv read report.pdf -o /tmp/report.md
# AI 读取 /tmp/report.md，分析内容，生成回复
```

### 每一个命令都支持 `--json`

脚本化、程序化、AI 自动化：

```bash
jv note list --json | jq '.[] | select(.group=="prompts")'
```

---

## 技术栈

- **Python 3.12+**
- **Typer** — CLI 框架
- **python-docx** — Word 生成
- **pymupdf4llm** — PDF 解析
- **openpyxl** — Excel 解析
- **mistune** — Markdown 解析

---

## 开发状态

jv-cli 目前处于**活跃开发阶段**，核心功能已稳定可用。欢迎试用、提 issue、贡献代码。

```bash
# 本地开发
git clone https://github.com/yourname/jv-cli.git
cd jv-cli
uv sync
uv pip install -e .
```

---

## License

MIT
