jvkit 0.0.3

AI-native CLI toolkit: document reading, note management, image organizing, storage analysis, and Markdown-to-academic-Word conversion

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

---

安装

pip install jv-cli

或者从源码：

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

---

六大核心能力

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

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

# 添加一条系统提示词
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 模板：

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}}!")

# 一键生成项目脚手架
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（中文零配置）

# 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 友好）

# 分析当前目录
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 — 图片批量重命名

# 当前目录图片按文件夹独立编号
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 — 图片按扩展名归类

# 按扩展名归到子文件夹
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

# 默认 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 调用时不依赖终端输出，直接写文件：

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

每一个命令都支持 --json

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

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、贡献代码。

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

---

License

MIT