mirror of
https://github.com/tradecatlabs/vibe-coding-cn.git
synced 2026-08-13 02:48:05 +00:00
feat: Comprehensive documentation update and claude-skills module enhancement
This commit is contained in:
tukuaiai
+46
-69
@@ -1,90 +1,67 @@
|
||||
# 📦 通用库与外部集成 (Libs)
|
||||
# 📦 通用库与外部集成 (libs)
|
||||
|
||||
`libs/` 目录存放项目的通用库代码和外部集成模块，用于项目内部模块化和工具复用。
|
||||
`libs/` 用来放两类东西：
|
||||
|
||||
1. **内部可复用的胶水代码**：小而稳、低耦合、可替换（`common/`）
|
||||
2. **第三方工具与外部集成**：尽量保持原样、只做最薄适配（`external/`）
|
||||
|
||||
`database/` 预留未来的数据持久化层（当前仅占位）。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
libs/
|
||||
├── README.md # 本文件
|
||||
├── common/ # 通用功能模块
|
||||
├── README.md
|
||||
├── common/
|
||||
│ ├── README.md
|
||||
│ ├── __init__.py
|
||||
│ ├── models/ # 数据模型定义
|
||||
│ ├── models/
|
||||
│ │ └── __init__.py
|
||||
│ └── utils/ # 工具函数
|
||||
│ └── backups/ # 备份工具
|
||||
├── database/ # 数据库相关模块（预留）
|
||||
│ └── utils/
|
||||
│ └── backups/
|
||||
│ ├── README.md
|
||||
│ ├── 快速备份.py
|
||||
│ └── 一键备份.sh
|
||||
├── database/
|
||||
│ ├── README.md
|
||||
│ └── .gitkeep
|
||||
└── external/ # 外部集成与第三方工具
|
||||
├── prompts-library/ # 提示词库管理工具
|
||||
├── my-nvim/ # Neovim 配置
|
||||
└── XHS-image-to-PDF-conversion/ # 小红书图片转 PDF
|
||||
└── external/
|
||||
├── README.md
|
||||
├── prompts-library/
|
||||
├── my-nvim/
|
||||
├── XHS-image-to-PDF-conversion/
|
||||
└── .gitkeep
|
||||
```
|
||||
|
||||
## 各子目录详解
|
||||
## 子目录职责与边界
|
||||
|
||||
### `common/` - 通用功能模块
|
||||
### `common/`：内部通用模块
|
||||
|
||||
存放项目内部共享的通用代码：
|
||||
- 入口：[`common/README.md`](./common/README.md)
|
||||
- 只放 **可复用** 的基础能力：模型、工具函数、脚本等
|
||||
- 不要把业务逻辑、项目临时代码塞进来
|
||||
- 约定：新增/调整能力时，同步更新 `libs/common/README.md`
|
||||
|
||||
- `models/` - 数据模型定义，如 Pydantic 模型、数据类等
|
||||
- `utils/` - 工具函数，如文件处理、格式转换等
|
||||
- `utils/backups/` - 备份相关工具函数
|
||||
### `database/`：数据库适配层（预留）
|
||||
|
||||
### `database/` - 数据库模块（预留）
|
||||
- 入口：[`database/README.md`](./database/README.md)
|
||||
- 目标是把“存储细节”关进盒子里：连接、迁移、查询适配、事务边界
|
||||
- 约定：实现前先写清楚目录结构与边界（见 `libs/database/README.md`）
|
||||
|
||||
预留的数据库适配层，用于未来扩展数据持久化功能。
|
||||
### `external/`：第三方工具与外部集成
|
||||
|
||||
### `external/` - 外部集成
|
||||
- 入口：[`external/README.md`](./external/README.md)
|
||||
- 尽量保持第三方代码原样，避免“魔改后不可升级”
|
||||
- 每个工具目录至少包含：`README.md`（用途/入口/依赖）与许可证/来源说明
|
||||
- 约定：新增外部工具时，同步更新 `libs/external/README.md`
|
||||
|
||||
#### `prompts-library/` - 提示词库管理工具
|
||||
## 常用入口
|
||||
|
||||
Excel ↔ Markdown 提示词互转工具：
|
||||
- 提示词批量管理：[`external/prompts-library/`](./external/prompts-library/)（配合 `../prompts/` 使用）
|
||||
- 备份工具：优先使用仓库根目录的 `backups/`（当前与 `libs/common/utils/backups/` 内容一致）
|
||||
|
||||
```bash
|
||||
cd libs/external/prompts-library
|
||||
pip install -r requirements.txt
|
||||
python main.py
|
||||
```
|
||||
## 贡献约定（最小要求）
|
||||
|
||||
功能：
|
||||
- Excel 转 Markdown：批量将表格提示词转为 .md 文件
|
||||
- Markdown 转 Excel：将 .md 文件汇总到表格中
|
||||
- 支持分类、标签、版本管理
|
||||
|
||||
#### `my-nvim/` - Neovim 配置
|
||||
|
||||
个人 Neovim 配置，基于 LazyVim，包含：
|
||||
- LSP 配置
|
||||
- 代码补全
|
||||
- 文件导航
|
||||
- Git 集成
|
||||
|
||||
#### `XHS-image-to-PDF-conversion/` - 小红书图片转 PDF
|
||||
|
||||
将小红书图片合并为 PDF 的工具：
|
||||
|
||||
```bash
|
||||
cd libs/external/XHS-image-to-PDF-conversion
|
||||
pip install -r requirements.txt
|
||||
python pdf.py
|
||||
```
|
||||
|
||||
## 使用原则
|
||||
|
||||
1. **分层边界**: `common/` 只放通用代码，业务逻辑放其他地方
|
||||
2. **单一职责**: 每个模块只做一件事
|
||||
3. **依赖记录**: 新增外部依赖时更新对应的 `requirements.txt`
|
||||
4. **文档同步**: 新增模块时更新本 README
|
||||
|
||||
## 新增模块指南
|
||||
|
||||
```bash
|
||||
# 新增通用模块
|
||||
mkdir -p libs/common/新模块名
|
||||
touch libs/common/新模块名/__init__.py
|
||||
|
||||
# 新增外部集成
|
||||
mkdir -p libs/external/工具名
|
||||
echo "# 工具说明" > libs/external/工具名/README.md
|
||||
```
|
||||
1. 新增模块先定义职责边界，再写代码/文档
|
||||
2. 新增依赖记录安装方式与最低版本（必要时补充到 `documents/工具集.md`）
|
||||
3. 目录结构/职责变化时，更新对应 README，保证“文档即真相源”
|
||||
|
||||
+27
-14
@@ -1,27 +1,40 @@
|
||||
# 🔧 通用功能模块 (Common)
|
||||
# 🔧 libs/common：通用模块
|
||||
|
||||
存放项目内部共享的通用代码，包括数据模型和工具函数。
|
||||
`libs/common/` 放的是项目内部可复用的“胶水代码”：**小而稳、低耦合、可替换**。这里的目标不是堆功能，而是为仓库提供少量可靠的基础能力。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
common/
|
||||
libs/common/
|
||||
├── README.md
|
||||
├── __init__.py
|
||||
├── models/ # 数据模型定义
|
||||
├── models/ # 预留：数据模型（当前仅占位）
|
||||
│ └── __init__.py
|
||||
└── utils/ # 工具函数
|
||||
└── backups/ # 备份工具
|
||||
└── utils/
|
||||
└── backups/ # 基于 .gitignore 的快速备份工具
|
||||
├── README.md
|
||||
├── 快速备份.py
|
||||
└── 一键备份.sh
|
||||
```
|
||||
|
||||
## 子模块
|
||||
## 现有内容
|
||||
|
||||
- `models/` - Pydantic 模型、数据类等
|
||||
- `utils/` - 文件处理、格式转换等工具函数
|
||||
- `utils/backups/` - 备份相关工具
|
||||
- `utils/backups/`：快速备份工具（当前与仓库根目录 [`backups/`](../../backups/) 内容一致，用于避免脚本散落各处）
|
||||
|
||||
## 使用
|
||||
## 约束与约定
|
||||
|
||||
```python
|
||||
from libs.common.models import YourModel
|
||||
from libs.common.utils import your_function
|
||||
1. **不放业务逻辑**：`common/` 只提供基础能力与工具
|
||||
2. **接口要稳**：一旦被引用，就把它当作公开 API 对待
|
||||
3. **可审计输出**：脚本/工具的输出要可复盘（明确输入、输出路径、失败原因）
|
||||
4. **新增即文档**：新增模块/目录必须同步更新本 README 与 `libs/README.md`
|
||||
|
||||
## 使用方式（当前推荐）
|
||||
|
||||
本目录的内容目前主要以“脚本/工具”形式存在，推荐直接运行：
|
||||
|
||||
```bash
|
||||
# 备份当前仓库（建议优先使用根目录 backups/ 入口）
|
||||
python3 backups/快速备份.py
|
||||
```
|
||||
|
||||
更多参数与说明见：[`../../backups/README.md`](../../backups/README.md)。
|
||||
|
||||
+16
-14
@@ -1,22 +1,24 @@
|
||||
# 🗄️ 数据库模块 (Database)
|
||||
# 🗄️ libs/database：数据库适配层（预留）
|
||||
|
||||
预留的数据库适配层，用于未来扩展数据持久化功能。
|
||||
`libs/database/` 预留给未来的“存储适配层”。目标是把数据库的细节（连接、迁移、事务、查询）封装在一个清晰边界内，避免业务代码到处散落 SQL/ORM。
|
||||
|
||||
## 规划用途
|
||||
## 设计边界（先写清楚再实现）
|
||||
|
||||
- 数据库连接管理
|
||||
- ORM 模型定义
|
||||
- 数据迁移脚本
|
||||
- 查询工具函数
|
||||
- 这里负责：连接管理、迁移脚本、ORM/SQL 模型、统一的查询/事务封装
|
||||
- 这里不负责：业务规则、HTTP/API 逻辑、领域对象的复杂编排
|
||||
|
||||
## 待实现
|
||||
|
||||
当前为占位目录，后续可添加：
|
||||
## 推荐目录结构（落地时按需取舍）
|
||||
|
||||
```
|
||||
database/
|
||||
libs/database/
|
||||
├── README.md
|
||||
├── __init__.py
|
||||
├── connection.py # 连接管理
|
||||
├── models.py # ORM 模型
|
||||
└── migrations/ # 迁移脚本
|
||||
├── connection.py # 连接与池化
|
||||
├── migrations/ # 迁移脚本（Alembic/Flyway/自研均可）
|
||||
├── repositories/ # 数据访问层（可选）
|
||||
└── models/ # ORM 模型或 SQL schema（可选）
|
||||
```
|
||||
|
||||
## 何时开始实现
|
||||
|
||||
当仓库出现“需要长期保存/查询的数据”且 **文件系统不够用** 时，再把这一层落地；否则保持为空，避免过早引入复杂度。
|
||||
|
||||
Vendored
+21
-19
@@ -1,29 +1,31 @@
|
||||
# 🔌 外部集成模块 (External)
|
||||
# 🔌 libs/external：外部集成与第三方工具
|
||||
|
||||
存放第三方工具、外部依赖和集成模块。
|
||||
`libs/external/` 用来收纳第三方工具、外部依赖与集成模块。核心原则是：
|
||||
|
||||
- **尽量原样保留**：避免“魔改后不可升级”
|
||||
- **隔离依赖与风险**：外部工具的依赖不要污染主仓库
|
||||
- **可追溯**：来源、许可证、用法要写清楚
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
external/
|
||||
├── prompts-library/ # 提示词库管理工具（Excel ↔ MD 互转）
|
||||
├── my-nvim/ # Neovim 配置
|
||||
└── XHS-image-to-PDF-conversion/ # 小红书图片转 PDF
|
||||
libs/external/
|
||||
├── README.md
|
||||
├── prompts-library/ # 提示词库管理工具（Excel ↔ Markdown）
|
||||
├── my-nvim/ # Neovim 配置（含 nvim-config/）
|
||||
├── XHS-image-to-PDF-conversion/ # 图片合并 PDF 工具
|
||||
└── .gitkeep
|
||||
```
|
||||
|
||||
## 工具说明
|
||||
## 工具清单（入口与文档）
|
||||
|
||||
| 工具 | 用途 | 使用方法 |
|
||||
|------|------|----------|
|
||||
| `prompts-library` | 提示词 Excel/MD 互转 | `python main.py` |
|
||||
| `my-nvim` | Neovim 配置 | 复制到 `~/.config/nvim` |
|
||||
| `XHS-image-to-PDF-conversion` | 图片合并 PDF | `python pdf.py` |
|
||||
- `prompts-library/`：提示词 Excel ↔ Markdown 批量互转与索引生成（详见 [`prompts-library/README.md`](./prompts-library/README.md)）
|
||||
- `my-nvim/`：个人 Neovim 配置（详见 [`my-nvim/README.md`](./my-nvim/README.md)）
|
||||
- `XHS-image-to-PDF-conversion/`：图片合并 PDF（详见 [`XHS-image-to-PDF-conversion/README.md`](./XHS-image-to-PDF-conversion/README.md)）
|
||||
|
||||
## 新增外部工具
|
||||
## 新增外部工具（最小清单）
|
||||
|
||||
```bash
|
||||
mkdir -p libs/external/工具名
|
||||
echo "# 工具说明" > libs/external/工具名/README.md
|
||||
```
|
||||
|
||||
新增时请注明来源、许可证和依赖。
|
||||
1. 创建目录：`libs/external/<tool-name>/`
|
||||
2. 必备文件：`README.md`（用途/入口/依赖/输入输出）、许可证与来源说明（如 `LICENSE` / `SOURCE.md`）
|
||||
3. 依赖约束：尽量使用工具自带的虚拟环境/容器化方式，不影响仓库其他部分
|
||||
4. 文档同步：在本 README 增加一行工具说明，保证可发现性
|
||||
|
||||
Reference in New Issue
Block a user