proj2md-py 2.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. proj2md_py-2.2.0/LICENSE +21 -0
  2. proj2md_py-2.2.0/PKG-INFO +282 -0
  3. proj2md_py-2.2.0/README.md +252 -0
  4. proj2md_py-2.2.0/proj2md.py +1247 -0
  5. proj2md_py-2.2.0/proj2md_py.egg-info/PKG-INFO +282 -0
  6. proj2md_py-2.2.0/proj2md_py.egg-info/SOURCES.txt +10 -0
  7. proj2md_py-2.2.0/proj2md_py.egg-info/dependency_links.txt +1 -0
  8. proj2md_py-2.2.0/proj2md_py.egg-info/entry_points.txt +3 -0
  9. proj2md_py-2.2.0/proj2md_py.egg-info/requires.txt +3 -0
  10. proj2md_py-2.2.0/proj2md_py.egg-info/top_level.txt +1 -0
  11. proj2md_py-2.2.0/pyproject.toml +48 -0
  12. proj2md_py-2.2.0/setup.cfg +4 -0
proj2md_py-2.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 苍天在上晚自习
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
proj2md_py-2.2.0/PKG-INFO ADDED
@@ -0,0 +1,282 @@
1
+ Metadata-Version: 2.4
2
+ Name: proj2md-py
3
+ Version: 2.2.0
4
+ Summary: 项目源码一键拼接工具：把整个项目合并成单个 Markdown 文档，方便投喂网页端 AI
5
+ Author: Avlorayne
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/Avlorayne/proj2md.py
8
+ Project-URL: Repository, https://github.com/Avlorayne/proj2md.py
9
+ Project-URL: Issues, https://github.com/Avlorayne/proj2md.py/issues
10
+ Keywords: markdown,ai,chatgpt,claude,gemini,cli,uv,llm,context
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.8
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Operating System :: OS Independent
22
+ Classifier: Topic :: Software Development :: Documentation
23
+ Classifier: Topic :: Text Processing :: Markup :: Markdown
24
+ Requires-Python: >=3.8
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Provides-Extra: clip
28
+ Requires-Dist: pyperclip; extra == "clip"
29
+ Dynamic: license-file
30
+
31
+ <div align="center">
32
+
33
+ # proj2md.py
34
+ **简体中文** | [English](./README_EN.md)
35
+
36
+ 🗂 **项目源码一键拼接工具** —— 把整个项目合并成一份 Markdown，直接投喂给网页端 AI
37
+ `(ChatGPT / Claude / Gemini / Grok / DeepSeek / GLM / Kimi …) `
38
+
39
+ [![PyPI](https://img.shields.io/pypi/v/proj2md-py)](https://pypi.org/project/proj2md-py/)
40
+ [![Python](https://img.shields.io/pypi/pyversions/proj2md-py)](https://pypi.org/project/proj2md-py/)
41
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
42
+ `Python 3.8+` · 零第三方依赖 · 单文件脚本 [proj2md](./proj2md.py) · v2.2.0
43
+
44
+ </div>
45
+
46
+ ---
47
+
48
+ ## 目录
49
+
50
+ - [✨ 功能特性](#-功能特性)
51
+ - [🚀 快速开始](#-快速开始)
52
+ - [📖 常用示例](#-常用示例)
53
+ - [⚙️ 命令行参数](#-命令行参数)
54
+ - [🙈 忽略规则](#-忽略规则)
55
+ - [🧠 智能排序](#-智能排序)
56
+ - [📄 生成文档结构](#-生成文档结构)
57
+ - [🌐 多语言界面](#-多语言界面)
58
+ - [🪟 配置文件](#-配置文件)
59
+ - [📏 体积与 Token 预算](#-体积与-token-预算)
60
+ - [💡 使用技巧与 FAQ](#-使用技巧与-faq)
61
+ - [📜 许可证](#-许可证)
62
+
63
+ ## ✨ 功能特性
64
+
65
+ - 🗂 **一键拼接**：遍历整个项目，把代码 / 配置 / 文档合并为单个 `.md` 文件
66
+ - 📑 **结构化输出**：元信息 + 目录树 + 文件索引表 + 语法高亮代码块 + 附录
67
+ - 🔗 **文件索引**：每个文件带锚点链接和「起始行号」，AI 与人都能快速定位
68
+ - 🧠 **智能排序**：README、配置清单、入口文件优先，AI 先读到最关键的内容
69
+ - 🔢 **精确引用**：`--line-numbers` 为正文加行号，AI 可用 `路径:行号` 引用代码
70
+ - 📏 **体积可控**：单文件行数 / 单文件大小 / 总预算 / 按 Token 自动分卷
71
+ - 🙈 **五层忽略规则**：隐藏目录 → 目录黑名单 → 文件黑名单 → 通配符 → 扩展名白名单，且 `--include-pattern` 可强制穿透
72
+ - 🌐 **多语言界面**：自动跟随系统语言，支持 `--lang zh / en` 手动切换（帮助、报告、生成的文档说明全部跟随）
73
+ - 🎯 **需求直达**：`--prompt` 把你的任务放在合集最前面，AI 第一眼看到
74
+ - 📋 **剪贴板**：`--clip` 跨平台复制（pyperclip / PowerShell / pbcopy / wl-copy / xclip / xsel）
75
+ - 🈶 **编码友好**：自动识别 UTF-8 / GBK / Big5 / Latin-1；终端不支持中文时自动降级 ASCII
76
+ - 🪟 **配置文件**：`proj2md.json` 持久化所有参数，`--init-config` 一键生成模板
77
+ - 👀 **dry-run 预览**：先看会拼接哪些文件，再决定是否生成
78
+
79
+ ## 🚀 快速开始
80
+
81
+ ### 方式一：uv 安装（推荐）
82
+
83
+ 已发布到 PyPI（包名 `proj2md-py`，终端命令为 `proj2md`）：
84
+
85
+ ```bash
86
+ # 免安装，临时运行（uv 0.3+ 自带 uvx）
87
+ uvx proj2md-py --prompt "帮我找出潜在 bug 并给出修复建议"
88
+ # 或全局安装，之后直接使用 proj2md 命令
89
+ uv tool install proj2md-py
90
+
91
+ # 拼接当前目录 -> project_bundle.md
92
+ proj2md
93
+ # 拼接指定项目，并复制到剪贴板
94
+ proj2md /path/to/project --clip
95
+ # 附带你的需求一起投喂
96
+ proj2md --prompt "帮我找出潜在 bug 并给出修复建议"
97
+ ```
98
+
99
+ > `pip` 用户：`pip install proj2md-py`，或 `pip install "proj2md-py[clip]"` 一并装上剪贴板支持。
100
+
101
+ ### 方式二：直接运行脚本
102
+
103
+ 无需安装，克隆仓库后直接运行（唯一可选依赖 `pyperclip`，仅 `--clip` 需要）：
104
+
105
+ ```bash
106
+ python proj2md.py
107
+ python proj2md.py /path/to/project --clip
108
+ ```
109
+
110
+ 生成后，把 `project_bundle.md` 的内容整个粘贴给网页端 AI 即可 —— Markdown 代码块会自动语法高亮。
111
+
112
+ ## 📖 常用示例
113
+
114
+ > 以下示例使用安装后的 `proj2md` 命令；用源码运行的话，把 `proj2md` 换成 `python proj2md.py` 即可。
115
+
116
+ ```bash
117
+ proj2md --only-ext py md # 只拼接 Python 与 Markdown
118
+ proj2md --ext proto graphql # 在默认范围上追加扩展名
119
+ proj2md --exclude-dir tests docs # 额外排除目录
120
+ proj2md --include-pattern "src/*" # 强制包含（优先级最高）
121
+ proj2md --include-hidden # 不忽略 . 开头的文件夹
122
+ proj2md --include-pattern ".github/*" # 只捞回某个隐藏目录
123
+ proj2md --line-numbers # 正文带行号，AI 引用更精准
124
+ proj2md --max-file-lines 300 # 单文件超过 300 行则截断
125
+ proj2md --max-total-kb 200 # 总体积预算 200KB
126
+ proj2md --split-tokens 60000 # 过大时切成多个分卷
127
+ proj2md --lang en # 界面切英文
128
+ proj2md --dry-run # 只预览，不写文件
129
+ proj2md --init-config # 生成配置模板
130
+ ```
131
+ ## ⚙️ 命令行参数
132
+
133
+ **输入与输出**
134
+
135
+ | 参数 | 说明 |
136
+ |---|---|
137
+ | `root`（位置参数） | 项目根目录，默认当前目录 |
138
+ | `-o, --output <file>` | 输出文件路径（默认 `project_bundle.md`） |
139
+ | `--stdout` | 输出到标准输出，不写文件 |
140
+ | `--clip` | 生成后复制到系统剪贴板 |
141
+
142
+ **文件范围**
143
+
144
+ | 参数 | 说明 |
145
+ |---|---|
146
+ | `--ext <ext...>` | 在默认扩展名白名单上**追加** |
147
+ | `--only-ext <ext...>` | 只包含指定扩展名（**替换**默认范围） |
148
+ | `--any-text` | 包含所有非二进制文本文件 |
149
+ | `--include-hidden` | 不忽略 `.` 开头的文件夹 |
150
+ | `--exclude-dir <dir...>` | 追加排除的目录 |
151
+ | `--exclude-file <name...>` | 追加排除的文件名 |
152
+ | `--exclude-pattern <pat...>` | 追加排除的通配符，如 `*.min.js tests/*` |
153
+ | `--include-pattern <pat...>` | 强制包含（最高优先级，可穿透一切忽略规则） |
154
+
155
+ **体积控制**
156
+
157
+ | 参数 | 说明 |
158
+ |---|---|
159
+ | `--max-file-lines <n>` | 单文件最多保留 n 行，超出截断（0 = 不限） |
160
+ | `--max-file-kb <kb>` | 超过此大小的文件直接跳过（默认 512） |
161
+ | `--max-total-kb <kb>` | 合集总大小预算（KB） |
162
+ | `--split-tokens <n>` | 按 Token 预估切成多个 `.partN.md` 分卷 |
163
+
164
+ **输出内容**
165
+
166
+ | 参数 | 说明 |
167
+ |---|---|
168
+ | `--line-numbers` | 正文每行前加行号 |
169
+ | `--prompt <text>` | 在合集最前附上你的需求 |
170
+ | `--prompt-file <file>` | 从文件读取需求（UTF-8） |
171
+ | `--no-tree` / `--no-index` | 不输出目录结构 / 文件索引 |
172
+ | `--no-ai-header` | 不输出「给 AI 的阅读说明」 |
173
+ | `--no-smart-order` | 禁用智能排序 |
174
+
175
+ **其他**
176
+
177
+ | 参数 | 说明 |
178
+ |---|---|
179
+ | `--lang <auto\|zh\|en>` | 界面语言（默认 auto 跟随系统） |
180
+ | `--config <file>` / `--no-config` | 指定 / 忽略配置文件 |
181
+ | `--init-config` | 生成 `proj2md.json` 模板后退出 |
182
+ | `--dry-run` | 只预览将拼接的文件与统计 |
183
+ | `--quiet` | 静默模式，只输出结果路径 |
184
+ | `--version` / `-h, --help` | 版本号 / 帮助 |
185
+
186
+ ## 🙈 忽略规则
187
+
188
+ 按顺序生效，任一命中即跳过：
189
+ 1. **隐藏目录**（默认开）：`.` 开头的文件夹整目录忽略 → `--include-hidden` 关闭
190
+ 2. **目录黑名单**：内置 `node_modules`、`__pycache__`、`venv`、`dist`、`build` 等 + `--exclude-dir`
191
+ 3. **文件黑名单**：锁文件 `package-lock.json`、`poetry.lock` 等 + `--exclude-file`
192
+ 4. **通配符黑名单**：`*.min.js`、`*.png`、`*.zip`、`*.log` 等 + `--exclude-pattern`
193
+ 5. **扩展名白名单**：仅收录白名单内扩展名 → `--ext` / `--only-ext` / `--any-text` 调整
194
+ > ⭐ `--include-pattern` 优先级最高：即使命中上述任何规则也强制包含，且能穿透隐藏目录忽略。
195
+
196
+ 另外：
197
+ - 输出文件、配置文件、脚本自身会被自动排除，不会拼进结果；
198
+ - 疑似二进制 / 无法解码 / 超限的文件不会丢失，统一记录在文末附录；
199
+ - 点开头的**文件**（如 `.gitignore`）不受隐藏目录规则影响，正常收录。
200
+
201
+ ## 🧠 智能排序
202
+
203
+ 合集内的文件按以下优先级排列，让 AI 优先读到最关键的内容：
204
+
205
+ | 优先级 | 文件类型 |
206
+ |:---:|---|
207
+ | 0 | `README*` |
208
+ | 1 | 项目清单与配置：`package.json`、`pyproject.toml`、`requirements.txt`、`Dockerfile`、`.gitignore` 等 |
209
+ | 2 | 入口文件（`main` / `app` / `index` / `server` / `cli`…）及 `config` / `settings` |
210
+ | 3 | 其余文件（按路径排序） |
211
+
212
+ ## 📄 生成文档结构
213
+
214
+ ```
215
+ # 项目代码合集：<项目名>
216
+ ├─ 元信息（生成时间 / 文件数 / 行数 / Token 预估）
217
+ ├─ 📖 给 AI 的阅读说明（约定引用格式等）
218
+ ├─ 🎯 我的需求（--prompt，若有）
219
+ ├─ 🗂 目录结构（树状图）
220
+ ├─ 📑 文件索引（锚点链接 + 起始行号）
221
+ ├─ 📄 源代码正文（### 序号. 相对路径 + 语法高亮代码块）
222
+ ├─ 📎 附录：未包含的文件
223
+ ├─ 📎 附录：已忽略的隐藏目录
224
+ └─ END 统计页脚
225
+ ```
226
+
227
+ 即使源码里含有 ` ``` ` 代码块也不会破坏结构 —— 围栏长度会自适应加长。
228
+
229
+ ## 🌐 多语言界面
230
+
231
+ 语言解析优先级：**`--lang` 参数 > 配置文件 `language` 字段 > 系统自动探测 > 英文兜底**。
232
+
233
+ ```bash
234
+ proj2md --lang en # 本次运行全英文（含 --help 与报告）
235
+ proj2md --lang zh # 强制中文
236
+ proj2md --lang auto # 跟随系统（覆盖配置文件设置）
237
+
238
+ ```
239
+ - `auto`（默认）：依次探测环境变量（`LC_ALL` / `LANG`…）→ `locale` 模块 → Windows API，凡 `zh` 开头即中文，否则英文；
240
+ - 也可以在 `proj2md.json` 中写 `"language": "zh"` 持久化；
241
+ - 切换的不只是控制台输出 —— 生成的 `.md` 文档内的标题、AI 阅读说明、索引表头、附录等也会跟随语言。
242
+ ## 🪟 配置文件
243
+ ```bash
244
+ proj2md --init-config # 生成 proj2md.json 模板
245
+ ```
246
+ 按需修改后再次运行即自动读取（无需额外参数）：
247
+ ```json
248
+ {
249
+ "language": "auto",
250
+ "output": "project_bundle.md",
251
+ "exts": [],
252
+ "line_numbers": true,
253
+ "max_file_lines": 400,
254
+ "exclude_dirs": ["docs", "benchmarks"],
255
+ "include_patterns": [],
256
+ "split_tokens": 0,
257
+ "clip": false
258
+ }
259
+ ```
260
+ 优先级：**命令行参数 > 配置文件 > 内置默认** ；不需要的键可直接删除。
261
+ ## 📏 体积与 Token 预算
262
+
263
+ Token 为粗略估算（中文 ≈ 1.1 token/字，其他 ≈ 3.8 字符/token），生成后会给出提示：
264
+
265
+ | 预估 Token | 建议 |
266
+ |---|---|
267
+ | < 30k | ✅ 体量适中，直接投喂 |
268
+ | 30k – 100k | ⚠️ 部分 AI 输入框有长度限制，建议裁剪 |
269
+ | 100k – 200k | ⚠️ 需长上下文模型，或用 `--split-tokens` 分卷 |
270
+ | > 200k | ❌ 建议裁剪（`--exclude-dir` / `--max-file-lines` / `--only-ext`）或分卷 |
271
+
272
+ ## 💡 使用技巧与 FAQ
273
+
274
+ - **让 AI 精确引用代码**：投喂时在 `--prompt` 里要求它用 `相对路径:行号` 格式引用；配合 `--line-numbers` 效果最佳。
275
+ - **分卷投喂顺序**：`--split-tokens` 生成 `xxx.part1.md`、`xxx.part2.md`…，请按顺序投喂，最后一卷才附带附录。
276
+ - **AI 忘了项目结构？** 把文档中的「目录结构 / 文件索引」两节再粘贴一次即可，无需重发全部代码。
277
+ - **Windows 终端中文乱码？** 脚本会自动把中文符号降级为 ASCII；也可以先执行 `chcp 65001` 切到 UTF-8。
278
+ - **`--clip` 失败？** `pip install pyperclip`，或直接打开输出文件手动复制。
279
+ - **想彻底自定义收录范围？** `--any-text` 收录所有文本文件，配合 `--include-hidden` 就是"全量模式"。
280
+
281
+ ## 📜 许可证
282
+ [MIT](./LICENSE) © 2025
proj2md_py-2.2.0/README.md ADDED
@@ -0,0 +1,252 @@
1
+ <div align="center">
2
+
3
+ # proj2md.py
4
+ **简体中文** | [English](./README_EN.md)
5
+
6
+ 🗂 **项目源码一键拼接工具** —— 把整个项目合并成一份 Markdown，直接投喂给网页端 AI
7
+ `(ChatGPT / Claude / Gemini / Grok / DeepSeek / GLM / Kimi …) `
8
+
9
+ [![PyPI](https://img.shields.io/pypi/v/proj2md-py)](https://pypi.org/project/proj2md-py/)
10
+ [![Python](https://img.shields.io/pypi/pyversions/proj2md-py)](https://pypi.org/project/proj2md-py/)
11
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
12
+ `Python 3.8+` · 零第三方依赖 · 单文件脚本 [proj2md](./proj2md.py) · v2.2.0
13
+
14
+ </div>
15
+
16
+ ---
17
+
18
+ ## 目录
19
+
20
+ - [✨ 功能特性](#-功能特性)
21
+ - [🚀 快速开始](#-快速开始)
22
+ - [📖 常用示例](#-常用示例)
23
+ - [⚙️ 命令行参数](#-命令行参数)
24
+ - [🙈 忽略规则](#-忽略规则)
25
+ - [🧠 智能排序](#-智能排序)
26
+ - [📄 生成文档结构](#-生成文档结构)
27
+ - [🌐 多语言界面](#-多语言界面)
28
+ - [🪟 配置文件](#-配置文件)
29
+ - [📏 体积与 Token 预算](#-体积与-token-预算)
30
+ - [💡 使用技巧与 FAQ](#-使用技巧与-faq)
31
+ - [📜 许可证](#-许可证)
32
+
33
+ ## ✨ 功能特性
34
+
35
+ - 🗂 **一键拼接**：遍历整个项目，把代码 / 配置 / 文档合并为单个 `.md` 文件
36
+ - 📑 **结构化输出**：元信息 + 目录树 + 文件索引表 + 语法高亮代码块 + 附录
37
+ - 🔗 **文件索引**：每个文件带锚点链接和「起始行号」，AI 与人都能快速定位
38
+ - 🧠 **智能排序**：README、配置清单、入口文件优先，AI 先读到最关键的内容
39
+ - 🔢 **精确引用**：`--line-numbers` 为正文加行号，AI 可用 `路径:行号` 引用代码
40
+ - 📏 **体积可控**：单文件行数 / 单文件大小 / 总预算 / 按 Token 自动分卷
41
+ - 🙈 **五层忽略规则**：隐藏目录 → 目录黑名单 → 文件黑名单 → 通配符 → 扩展名白名单，且 `--include-pattern` 可强制穿透
42
+ - 🌐 **多语言界面**：自动跟随系统语言，支持 `--lang zh / en` 手动切换（帮助、报告、生成的文档说明全部跟随）
43
+ - 🎯 **需求直达**：`--prompt` 把你的任务放在合集最前面，AI 第一眼看到
44
+ - 📋 **剪贴板**：`--clip` 跨平台复制（pyperclip / PowerShell / pbcopy / wl-copy / xclip / xsel）
45
+ - 🈶 **编码友好**：自动识别 UTF-8 / GBK / Big5 / Latin-1；终端不支持中文时自动降级 ASCII
46
+ - 🪟 **配置文件**：`proj2md.json` 持久化所有参数，`--init-config` 一键生成模板
47
+ - 👀 **dry-run 预览**：先看会拼接哪些文件，再决定是否生成
48
+
49
+ ## 🚀 快速开始
50
+
51
+ ### 方式一：uv 安装（推荐）
52
+
53
+ 已发布到 PyPI（包名 `proj2md-py`，终端命令为 `proj2md`）：
54
+
55
+ ```bash
56
+ # 免安装，临时运行（uv 0.3+ 自带 uvx）
57
+ uvx proj2md-py --prompt "帮我找出潜在 bug 并给出修复建议"
58
+ # 或全局安装，之后直接使用 proj2md 命令
59
+ uv tool install proj2md-py
60
+
61
+ # 拼接当前目录 -> project_bundle.md
62
+ proj2md
63
+ # 拼接指定项目，并复制到剪贴板
64
+ proj2md /path/to/project --clip
65
+ # 附带你的需求一起投喂
66
+ proj2md --prompt "帮我找出潜在 bug 并给出修复建议"
67
+ ```
68
+
69
+ > `pip` 用户：`pip install proj2md-py`，或 `pip install "proj2md-py[clip]"` 一并装上剪贴板支持。
70
+
71
+ ### 方式二：直接运行脚本
72
+
73
+ 无需安装，克隆仓库后直接运行（唯一可选依赖 `pyperclip`，仅 `--clip` 需要）：
74
+
75
+ ```bash
76
+ python proj2md.py
77
+ python proj2md.py /path/to/project --clip
78
+ ```
79
+
80
+ 生成后，把 `project_bundle.md` 的内容整个粘贴给网页端 AI 即可 —— Markdown 代码块会自动语法高亮。
81
+
82
+ ## 📖 常用示例
83
+
84
+ > 以下示例使用安装后的 `proj2md` 命令；用源码运行的话，把 `proj2md` 换成 `python proj2md.py` 即可。
85
+
86
+ ```bash
87
+ proj2md --only-ext py md # 只拼接 Python 与 Markdown
88
+ proj2md --ext proto graphql # 在默认范围上追加扩展名
89
+ proj2md --exclude-dir tests docs # 额外排除目录
90
+ proj2md --include-pattern "src/*" # 强制包含（优先级最高）
91
+ proj2md --include-hidden # 不忽略 . 开头的文件夹
92
+ proj2md --include-pattern ".github/*" # 只捞回某个隐藏目录
93
+ proj2md --line-numbers # 正文带行号，AI 引用更精准
94
+ proj2md --max-file-lines 300 # 单文件超过 300 行则截断
95
+ proj2md --max-total-kb 200 # 总体积预算 200KB
96
+ proj2md --split-tokens 60000 # 过大时切成多个分卷
97
+ proj2md --lang en # 界面切英文
98
+ proj2md --dry-run # 只预览，不写文件
99
+ proj2md --init-config # 生成配置模板
100
+ ```
101
+ ## ⚙️ 命令行参数
102
+
103
+ **输入与输出**
104
+
105
+ | 参数 | 说明 |
106
+ |---|---|
107
+ | `root`（位置参数） | 项目根目录，默认当前目录 |
108
+ | `-o, --output <file>` | 输出文件路径（默认 `project_bundle.md`） |
109
+ | `--stdout` | 输出到标准输出，不写文件 |
110
+ | `--clip` | 生成后复制到系统剪贴板 |
111
+
112
+ **文件范围**
113
+
114
+ | 参数 | 说明 |
115
+ |---|---|
116
+ | `--ext <ext...>` | 在默认扩展名白名单上**追加** |
117
+ | `--only-ext <ext...>` | 只包含指定扩展名（**替换**默认范围） |
118
+ | `--any-text` | 包含所有非二进制文本文件 |
119
+ | `--include-hidden` | 不忽略 `.` 开头的文件夹 |
120
+ | `--exclude-dir <dir...>` | 追加排除的目录 |
121
+ | `--exclude-file <name...>` | 追加排除的文件名 |
122
+ | `--exclude-pattern <pat...>` | 追加排除的通配符，如 `*.min.js tests/*` |
123
+ | `--include-pattern <pat...>` | 强制包含（最高优先级，可穿透一切忽略规则） |
124
+
125
+ **体积控制**
126
+
127
+ | 参数 | 说明 |
128
+ |---|---|
129
+ | `--max-file-lines <n>` | 单文件最多保留 n 行，超出截断（0 = 不限） |
130
+ | `--max-file-kb <kb>` | 超过此大小的文件直接跳过（默认 512） |
131
+ | `--max-total-kb <kb>` | 合集总大小预算（KB） |
132
+ | `--split-tokens <n>` | 按 Token 预估切成多个 `.partN.md` 分卷 |
133
+
134
+ **输出内容**
135
+
136
+ | 参数 | 说明 |
137
+ |---|---|
138
+ | `--line-numbers` | 正文每行前加行号 |
139
+ | `--prompt <text>` | 在合集最前附上你的需求 |
140
+ | `--prompt-file <file>` | 从文件读取需求（UTF-8） |
141
+ | `--no-tree` / `--no-index` | 不输出目录结构 / 文件索引 |
142
+ | `--no-ai-header` | 不输出「给 AI 的阅读说明」 |
143
+ | `--no-smart-order` | 禁用智能排序 |
144
+
145
+ **其他**
146
+
147
+ | 参数 | 说明 |
148
+ |---|---|
149
+ | `--lang <auto\|zh\|en>` | 界面语言（默认 auto 跟随系统） |
150
+ | `--config <file>` / `--no-config` | 指定 / 忽略配置文件 |
151
+ | `--init-config` | 生成 `proj2md.json` 模板后退出 |
152
+ | `--dry-run` | 只预览将拼接的文件与统计 |
153
+ | `--quiet` | 静默模式，只输出结果路径 |
154
+ | `--version` / `-h, --help` | 版本号 / 帮助 |
155
+
156
+ ## 🙈 忽略规则
157
+
158
+ 按顺序生效，任一命中即跳过：
159
+ 1. **隐藏目录**（默认开）：`.` 开头的文件夹整目录忽略 → `--include-hidden` 关闭
160
+ 2. **目录黑名单**：内置 `node_modules`、`__pycache__`、`venv`、`dist`、`build` 等 + `--exclude-dir`
161
+ 3. **文件黑名单**：锁文件 `package-lock.json`、`poetry.lock` 等 + `--exclude-file`
162
+ 4. **通配符黑名单**：`*.min.js`、`*.png`、`*.zip`、`*.log` 等 + `--exclude-pattern`
163
+ 5. **扩展名白名单**：仅收录白名单内扩展名 → `--ext` / `--only-ext` / `--any-text` 调整
164
+ > ⭐ `--include-pattern` 优先级最高：即使命中上述任何规则也强制包含，且能穿透隐藏目录忽略。
165
+
166
+ 另外：
167
+ - 输出文件、配置文件、脚本自身会被自动排除，不会拼进结果；
168
+ - 疑似二进制 / 无法解码 / 超限的文件不会丢失，统一记录在文末附录；
169
+ - 点开头的**文件**（如 `.gitignore`）不受隐藏目录规则影响，正常收录。
170
+
171
+ ## 🧠 智能排序
172
+
173
+ 合集内的文件按以下优先级排列，让 AI 优先读到最关键的内容：
174
+
175
+ | 优先级 | 文件类型 |
176
+ |:---:|---|
177
+ | 0 | `README*` |
178
+ | 1 | 项目清单与配置：`package.json`、`pyproject.toml`、`requirements.txt`、`Dockerfile`、`.gitignore` 等 |
179
+ | 2 | 入口文件（`main` / `app` / `index` / `server` / `cli`…）及 `config` / `settings` |
180
+ | 3 | 其余文件（按路径排序） |
181
+
182
+ ## 📄 生成文档结构
183
+
184
+ ```
185
+ # 项目代码合集：<项目名>
186
+ ├─ 元信息（生成时间 / 文件数 / 行数 / Token 预估）
187
+ ├─ 📖 给 AI 的阅读说明（约定引用格式等）
188
+ ├─ 🎯 我的需求（--prompt，若有）
189
+ ├─ 🗂 目录结构（树状图）
190
+ ├─ 📑 文件索引（锚点链接 + 起始行号）
191
+ ├─ 📄 源代码正文（### 序号. 相对路径 + 语法高亮代码块）
192
+ ├─ 📎 附录：未包含的文件
193
+ ├─ 📎 附录：已忽略的隐藏目录
194
+ └─ END 统计页脚
195
+ ```
196
+
197
+ 即使源码里含有 ` ``` ` 代码块也不会破坏结构 —— 围栏长度会自适应加长。
198
+
199
+ ## 🌐 多语言界面
200
+
201
+ 语言解析优先级：**`--lang` 参数 > 配置文件 `language` 字段 > 系统自动探测 > 英文兜底**。
202
+
203
+ ```bash
204
+ proj2md --lang en # 本次运行全英文（含 --help 与报告）
205
+ proj2md --lang zh # 强制中文
206
+ proj2md --lang auto # 跟随系统（覆盖配置文件设置）
207
+
208
+ ```
209
+ - `auto`（默认）：依次探测环境变量（`LC_ALL` / `LANG`…）→ `locale` 模块 → Windows API，凡 `zh` 开头即中文，否则英文；
210
+ - 也可以在 `proj2md.json` 中写 `"language": "zh"` 持久化；
211
+ - 切换的不只是控制台输出 —— 生成的 `.md` 文档内的标题、AI 阅读说明、索引表头、附录等也会跟随语言。
212
+ ## 🪟 配置文件
213
+ ```bash
214
+ proj2md --init-config # 生成 proj2md.json 模板
215
+ ```
216
+ 按需修改后再次运行即自动读取（无需额外参数）：
217
+ ```json
218
+ {
219
+ "language": "auto",
220
+ "output": "project_bundle.md",
221
+ "exts": [],
222
+ "line_numbers": true,
223
+ "max_file_lines": 400,
224
+ "exclude_dirs": ["docs", "benchmarks"],
225
+ "include_patterns": [],
226
+ "split_tokens": 0,
227
+ "clip": false
228
+ }
229
+ ```
230
+ 优先级：**命令行参数 > 配置文件 > 内置默认** ；不需要的键可直接删除。
231
+ ## 📏 体积与 Token 预算
232
+
233
+ Token 为粗略估算（中文 ≈ 1.1 token/字，其他 ≈ 3.8 字符/token），生成后会给出提示：
234
+
235
+ | 预估 Token | 建议 |
236
+ |---|---|
237
+ | < 30k | ✅ 体量适中，直接投喂 |
238
+ | 30k – 100k | ⚠️ 部分 AI 输入框有长度限制，建议裁剪 |
239
+ | 100k – 200k | ⚠️ 需长上下文模型，或用 `--split-tokens` 分卷 |
240
+ | > 200k | ❌ 建议裁剪（`--exclude-dir` / `--max-file-lines` / `--only-ext`）或分卷 |
241
+
242
+ ## 💡 使用技巧与 FAQ
243
+
244
+ - **让 AI 精确引用代码**：投喂时在 `--prompt` 里要求它用 `相对路径:行号` 格式引用；配合 `--line-numbers` 效果最佳。
245
+ - **分卷投喂顺序**：`--split-tokens` 生成 `xxx.part1.md`、`xxx.part2.md`…，请按顺序投喂，最后一卷才附带附录。
246
+ - **AI 忘了项目结构？** 把文档中的「目录结构 / 文件索引」两节再粘贴一次即可，无需重发全部代码。
247
+ - **Windows 终端中文乱码？** 脚本会自动把中文符号降级为 ASCII；也可以先执行 `chcp 65001` 切到 UTF-8。
248
+ - **`--clip` 失败？** `pip install pyperclip`，或直接打开输出文件手动复制。
249
+ - **想彻底自定义收录范围？** `--any-text` 收录所有文本文件，配合 `--include-hidden` 就是"全量模式"。
250
+
251
+ ## 📜 许可证
252
+ [MIT](./LICENSE) © 2025