# VS Code Copilot Agent 教程：把单文件脚本打成可安装的命令行工具

## 身份和范围

本站原创 fixture 与人工参考；实际运行：真正 wheel 构建、干净安装/运行/卸载。目标代理模型、账号会话、付费 API、第三方 PR、推送和发布均未执行。公开包不含 .env；需要时仅在自己的临时练习目录从文本模板创建。

## 本地命令

```sh
python3 -m venv .build-venv
.build-venv/bin/python -m pip install build==1.4.0
.build-venv/bin/python -m build --wheel
```

## 七步原生操作

### 1. 保留单文件脚本与三种文本输入

textstats.before.py 是原始单文件，fixtures 包含中文带空格路径、空文件和英文短文本。统计 whitespaceWords 指按空白切词，不把它宣称中文分词器。

### 2. 在 VS Code 中选择 Copilot Agent

打开独立练习目录，选择 Copilot 的 Agent 模式与可用模型，要求迁为 src 布局、console entry point，并保持 UTF-8 和原统计口径。按界面确认终端权限，不授予发布或远端推送。

### 3. 建立包元数据和命令入口

检查 pyproject.toml 的 build-system、project name/version、requires-python 及 [project.scripts]，qr-textstats 指向 qr_textstats.cli:main。目录名与导入名必须对应，不能只把脚本移动后仍依赖当前工作目录。

### 4. 把读参和输出放进 main

参考 cli.py 用 argparse 接收 Path，read_text(encoding="utf-8") 后输出 JSON。检查中文字符、空输入和带空格路径；路径作为参数传入，不能把 shell 空格拆成两个文件。

### 5. 构建真正 wheel 而不发布

在独立构建 venv 安装固定 setuptools/wheel/build，python -m build --wheel 生成 wheel。不要把手工 ZIP 改成 .whl；也不上传 PyPI，本题只检验本地可安装包。

### 6. 换干净环境和目录验证安装

再建第二个全新 venv，只安装 wheel，在源码目录之外执行 qr-textstats。三种输入必须得到正确 JSON；随后 pip uninstall 卸载，确认命令不可再用，避免当前 src 路径掩盖打包缺文件。

### 7. 交付源码、wheel 与真实日志

保存 wheel 的文件清单和 package-result.json，区分 VS Code Agent 会话与本站实际打包运行。包内参考可复现安装、运行、卸载，目标 Copilot 没有在本站被调用。

## 验收产物

src 布局、pyproject.toml 与 project.scripts 入口；实际 wheel、干净虚拟环境安装/工作目录外调用/卸载记录和三类 fixture 验收

## 门槛

- 需要 VS Code、Copilot Agent 可用模型与终端权限；Free/付费方案额度不同，不宣称无限。
- 需本机 Python、venv 和固定构建依赖；安装仅在独立练习虚拟环境。
- 本地构建安装不等于 PyPI 发布；本轮不上传包、不创建远端仓库。

## 官方来源

- https://code.visualstudio.com/docs/agents/overview
- https://docs.github.com/en/copilot/get-started/plans
- https://packaging.python.org/en/latest/guides/creating-command-line-tools/
- https://packaging.python.org/en/latest/tutorials/packaging-projects/

静态配图冻结于本次输入。修改输入需重新运行并自行重渲染；不把旧截图当新结果。

日志路径说明：execution.txt为实际执行输出的公开副本，仅将本机绝对目录替换为 <exercise>；测试结果、版本和计数未改。