补充项目文档与工作区配置

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.vscode/settings.json

+{
+  "python.analysis.extraPaths": [
+    ".",
+    "./distribution-server"
+  ]
+}

AGENTS.md

+# 仓库说明
+
+## 仓库结构
+
+本仓库包含两个程序，依赖和包元数据统一由根目录的 `pyproject.toml` 和
+`uv.lock` 管理：
+
+- `updater/`：可复用的 Python 更新库，导入名为 `updater`。通用逻辑位于
+  `updater/core/`，Windows 可执行文件替换逻辑位于
+  `updater/platforms/windows/`。
+- `distribution-server/`：局域网分发管理 Web 应用。后端分为 `api/` 和
+  `core/`，静态前端位于 `frontend/`，测试位于 `tests/`。
+
+不要在子目录新增 `pyproject.toml`。运行依赖和包元数据统一维护在仓库根目录
+的 `pyproject.toml`。
+
+## Python 版本和依赖
+
+- 使用 Python 3.12 或更高版本。updater 当前声明
+  `requires-python = ">=3.12"`。
+- `program-updater` 基础 wheel 没有第三方运行时依赖。FastAPI、
+  `python-multipart` 和 Uvicorn 属于可选的 `server` 依赖组。
+- 使用 `uv sync --extra server --extra test` 准备开发环境。
+- 不要把分发服务器依赖加入 updater 的基础依赖。
+
+## 测试和检查
+
+从仓库根目录分别运行两个程序的测试：
+
+```bash
+uv run --extra server --extra test python -m unittest discover -s updater/tests -v
+uv run --extra server --extra test python -m unittest discover -s distribution-server/tests -t . -v
+```
+
+修改打包配置、导入路径或发布元数据后，还要运行 `uv lock --check`、Python
+编译检查和 `git diff --check`。
+
+## 启动分发服务器
+
+在仓库根目录运行：
+
+```bash
+uv run --extra server python -m distribution-server.server
+```
+
+Web 应用模块和 server 模块都支持用 `python -m` 启动。管理页面是由 FastAPI
+同源提供的静态 HTML/CSS/JavaScript，不需要单独构建前端。
+
+## 构建 updater wheel
+
+发布包名为 `program-updater`，安装后的 Python 导入名为 `updater`。在仓库根
+目录构建 wheel：
+
+```bash
+uv build --wheel
+```
+
+wheel 输出到 `dist/`。发布前检查 wheel 元数据，并确认其中包含 `updater/`
+包文件。
+
+wheel 包含 Windows helper 的 Python 源码，但不包含 helper 可执行文件。需要
+自更新的目标程序应在 Windows 上使用 PyInstaller 构建 helper，并将其嵌入目标
+程序。
+
+## Changelog 和版本号
+
+发布日志文件为 `dist/CHANGELOG.txt`。每条记录的标题必须标明制品类型：
+
+- `[WHEEL]`：记录可复用 Python wheel 的变更。
+- `[EXE]`：记录打包后的应用可执行文件变更，并注明应用 ID、目标平台和架构。
+
+只有实际构建或发布了应用可执行文件时，才添加 `[EXE]` 记录。发布 wheel
+不代表下游应用 exe 已经重新构建。
+
+版本号格式为 `YYMMDD.FEATURE.BUGFIX`：
+
+- `YYMMDD` 是发布日期，例如 `261028` 表示 2026-10-28。
+- 增加功能时递增 `FEATURE`，新功能版本的 `BUGFIX` 从 `0` 开始。
+- 仅修复 bug 时递增 `BUGFIX`。
+- 同一版本同时包含新功能和 bug 修复时，按实际变更递增对应计数。
+- 新发布日期从 `.0.0` 开始。
+
+根目录 `pyproject.toml` 中的版本、wheel 文件名和 changelog 版本必须一致。
+版本变更需要时同步更新 `uv.lock`，然后重新构建 wheel。每条记录只描述该制品
+类型中实际包含的变更。

README.md

+
+# Program Updater Monorepo
+
+仓库根目录的 [`pyproject.toml`](./pyproject.toml) 和 `uv.lock` 统一管理依赖。源码按程序并列组织：
+
+- [`updater/`](./updater/)：供 Windows/PyInstaller 应用嵌入的客户端与 helper。
+- [`distribution-server/`](./distribution-server/)：局域网分发后台，包含 `api/`、`core/`、`frontend/` 和自己的 `tests/`。
+
+默认安装只包含 updater 运行依赖；管理 Web 的 FastAPI/Uvicorn 通过 `server` extra 启用，不会进入目标应用的基础安装。
+
+## 启动 Web 与测试
+
+需要 Python 3.12 和 uv。从仓库根目录使用 `python -m` 启动，不需要先设置环境变量；uv 会根据根 `pyproject.toml` 自动准备服务器依赖：
+
+```bash
+uv run --extra server python -m distribution-server.server
+```
+
+打开 `http://127.0.0.1:8000/`；服务默认监听 `0.0.0.0:8000`，可从局域网用服务器 IP 访问。默认设置位于 [`distribution-server/settings.py`](./distribution-server/settings.py)，要改端口、存储目录或允许网段时，直接编辑该文件。清单中的下载地址会根据客户端访问的 host 自动生成。
+
+也可以用 app 模块启动：
+
+```bash
+uv run --extra server python -m distribution-server.app
+```
+
+运行两个项目各自的测试：
+
+```bash
+uv sync --extra server --extra test
+uv run --extra server --extra test python -m unittest discover -s updater/tests -v
+uv run --extra server --extra test python -m unittest discover -s distribution-server/tests -t . -v
+```
+
+Updater 的应用集成和 PyInstaller 构建说明见 [`updater/README.md`](./updater/README.md)；分发服务器运行说明见 [`distribution-server/README.md`](./distribution-server/README.md)。