非强制上传模式下，要求HEAD游离且指向Tag

1、加强注释
2、上传时，添加-f参数才会强制上传，否则需要根据当前Tag标签信息来判断是否需要上传。
2026-06-29 14:44:06 +08:00 · 2026-06-28 20:56:56 +08:00 · 2026-06-28 20:16:16 +08:00 · 2026-06-28 19:32:57 +08:00 · 2026-06-26 17:16:44 +08:00 · 2026-06-24 09:58:32 +08:00
32 changed files with 23729 additions and 465 deletions
--- a/GitVer/GitVer.cpp
+++ b/GitVer/GitVer.cpp
@@ -14,6 +14,7 @@
 #include "gitver_types.h"
 #include "gitver_version.h"
 #include "gitver_setup.h"
+#include "gitver_upload.h"

 #ifdef _DEBUG
 #define new DEBUG_NEW
@@ -355,6 +356,7 @@ void PrintFullUsageExamples()
 		_T("  gitver nuitkapydbuild=<pid> [repodir=<path>可选] [-test可选] [params=\"<modulePy> <nuitka参数>\"可选]\n")
 		_T("  gitver pyinstaller=<pid> [repodir=<path>可选] [-test可选] [params=\"<mainPy|specFile> <pyinstaller参数>\"可选]\n")
 		_T("  gitver setup=n [pid=m可选] [repodir=<path>可选] [-test可选]\n")
+		_T("  gitver upload username=<用户名> [file=<上传文件>] [info=<配置.txt>] [url=<PMC基址>]\n")
 		_T("    setup=0: 使用 Inno Setup 脚本 (setup.iss)\n")
 		_T("    setup=1: 使用 NSIS 脚本 (setup.nsi)\n")
 		_T("    不指定 pid 时自动从 .rc / AssemblyInfo.cs / version_info.txt 读取版本\n")
@@ -381,6 +383,7 @@ void PrintFullUsageExamples()
 		_T("  gitver setup=0\n")
 		_T("  gitver setup=0 pid=5\n")
 		_T("  gitver setup=1 pid=5 repodir=E:\\Code\\MyProj\n")
+		_T("  gitver upload username=admin\n")
 		_T("params: 传递给 Nuitka/PyInstaller 的参数（含入口文件），用双引号括起来，如 params=\"main.py --standalone --output-dir=dist\"。\n")
 		_T("-test: 将产品版本号的 major 和 minor 都置为 0（用于测试版本构建）。\n")
 		_T("无参数时会读取当前分支最近三次 tag，并提示选择 major 加 1 或 minor 加 1，然后创建新 tag。\n")
@@ -399,6 +402,7 @@ void PrintShortCommandUsage()
 	_tprintf(_T("或：gitver nuitkabuild=<pid> [repodir=<path>可选] [params=\"<mainPy> <nuitka参数>\"可选]\n"));
 	_tprintf(_T("或：gitver nuitkapydbuild=<pid> [repodir=<path>可选] [params=\"<modulePy> <nuitka参数>\"可选]\n"));
 	_tprintf(_T("或：gitver pyinstaller=<pid> [repodir=<path>可选] [params=\"<mainPy|specFile> <pyinstaller参数>\"可选]\n"));
+	_tprintf(_T("或：gitver upload username=<用户名> [file=<上传文件>] [info=<配置.txt>] [url=<PMC基址>]\n"));
 }

 /// <summary>
@@ -507,6 +511,20 @@ LPCTSTR GetExitCodeHint(int nRetCode)
 		return _T("pyinstaller: write version_info.txt failed");
 	case 46:
 		return _T("pyinstaller: inject version into spec file failed");
+	case 47:
+		return _T("upload: missing required args");
+	case 48:
+		return _T("upload: file not found");
+	case 49:
+		return _T("upload: info invalid or env password missing");
+	case 50:
+		return _T("upload: login failed");
+	case 51:
+		return _T("upload: upload http failed");
+	case 52:
+		return _T("upload: version not found after upload");
+	case 53:
+		return _T("upload: network error");
 	default:
 		return _T("");
 	}
@@ -605,6 +623,8 @@ int HandleSetVerCommand(int argc, TCHAR* argv[])

 	CString strProductVersion;
 	CString strFileVersion;
+	CString strBranch;
+	SYSTEMTIME stFileVersionDate = { 0 };
 	VersionBuildErrorCodes errorCodes = { 5, 6, 9 };
 	int nVersionRet = BuildVersionsFromRepo(
 		lpRepoPath,
@@ -613,7 +633,9 @@ int HandleSetVerCommand(int argc, TCHAR* argv[])
 		strProductVersion,
 		strFileVersion,
 		DEFAULT_MAJOR_WHEN_NO_TAG,
-		DEFAULT_MINOR_WHEN_NO_TAG);
+		DEFAULT_MINOR_WHEN_NO_TAG,
+		&strBranch,
+		&stFileVersionDate);
 	if (nVersionRet != 0)
 	{
 		return nVersionRet;
@@ -633,10 +655,23 @@ int HandleSetVerCommand(int argc, TCHAR* argv[])
 	_tprintf(_T("ProductVersion=%s\n"), strProductVersion.GetString());
 	_tprintf(_T("FileVersion=%s\n"), strFileVersion.GetString());

+	CString strChangeLog;
+	if (!TryGetGitLogByBranchDate(lpRepoPath, strBranch, stFileVersionDate, strChangeLog))
+	{
+		strChangeLog = _T("无当日提交记录");
+	}
+
+	TCHAR szInfoPath[MAX_PATH] = { 0 };
+	_tcscpy_s(szInfoPath, lpRepoPath);
+	PathAppend(szInfoPath, _T("upload_info.txt"));
+	if (!WriteUploadInfoVersions(szInfoPath, strProductVersion, strFileVersion, strChangeLog))
+	{
+		_tprintf(_T("警告: 未能写入 upload_info.txt\n"));
+	}
+
 	return RewriteSetVerByProjectType(lpRepoPath, strProductVersion, strFileVersion);
 }

-/// <summary>
 /// <summary>
 /// 准备C++重写内容。
 /// </summary>
@@ -818,6 +853,14 @@ int HandleRewriteCommand(int argc, TCHAR* argv[])
 	return 0;
 }

+/// <summary>
+/// 程序入口：解析命令行参数并分发到各子命令处理函数。
+/// 无参数时进入交互式 tag 创建模式。
+/// </summary>
+/// <param name="argc">参数个数。</param>
+/// <param name="argv">参数数组。</param>
+/// <param name="envp">环境变量数组。</param>
+/// <returns>命令执行退出码，0 表示成功。</returns>
 int main(int argc, TCHAR* argv[], TCHAR* envp[])
 {
 	int nRetCode = 0;
@@ -871,6 +914,9 @@ int main(int argc, TCHAR* argv[], TCHAR* envp[])

 		if (argc >= 2 && _tcsnicmp(argv[1], _T("setver="), 7) == 0)
 		{
+#ifdef _DEBUG
+			Sleep(10000);
+#endif
 			DWORD dwStartTick = LogCommandStart(_T("setver"));
 			int nCmdRet = HandleSetVerCommand(argc, argv);
 			LogCommandEnd(_T("setver"), dwStartTick, nCmdRet);
@@ -905,6 +951,18 @@ int main(int argc, TCHAR* argv[], TCHAR* envp[])
 			return nCmdRet;
 		}

+		if (argc >= 2 && _tcsicmp(argv[1], _T("upload")) == 0)
+		{
+#ifdef _DEBUG
+			Sleep(10000);
+#endif
+			DWORD dwStartTick = LogCommandStart(_T("upload"));
+			int nCmdRet = HandleUploadCommand(argc, argv);
+			LogCommandEnd(_T("upload"), dwStartTick, nCmdRet);
+			PrintCommandFailedWithCode(_T("upload"), nCmdRet);
+			return nCmdRet;
+		}
+
 		_tprintf(_T("错误：未知命令：%s\n"), argv[1]);
 		PrintShortCommandUsage();

--- a/GitVer/GitVer.rc
+++ b/GitVer/GitVer.rc
--- a/GitVer/GitVer.vcxproj
+++ b/GitVer/GitVer.vcxproj
@@ -77,7 +77,7 @@
  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
    <OutDir>..\..\..\..\bin\$(ProjectName)\</OutDir>
    <IntDir>$(OutDir)$(Configuration)\</IntDir>
-    <TargetName>$(ProjectName)d</TargetName>
+    <TargetName>$(ProjectName)</TargetName>
  </PropertyGroup>
  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
    <OutDir>..\..\..\..\bin\$(ProjectName)\</OutDir>
@@ -153,9 +153,11 @@
    <ClInclude Include="GitVer_process.h" />
    <ClInclude Include="GitVer_rewrite.h" />
    <ClInclude Include="GitVer_setup.h" />
+    <ClInclude Include="GitVer_upload.h" />
    <ClInclude Include="GitVer_tag.h" />
    <ClInclude Include="GitVer_types.h" />
    <ClInclude Include="GitVer_version.h" />
+    <ClInclude Include="httplib.h" />
    <ClInclude Include="pch.h" />
    <ClInclude Include="Resource.h" />
    <ClInclude Include="targetver.h" />
@@ -169,6 +171,7 @@
    <ClCompile Include="GitVer_process.cpp" />
    <ClCompile Include="GitVer_rewrite.cpp" />
    <ClCompile Include="GitVer_setup.cpp" />
+    <ClCompile Include="GitVer_upload.cpp" />
    <ClCompile Include="GitVer_tag.cpp" />
    <ClCompile Include="GitVer_version.cpp" />
    <ClCompile Include="pch.cpp">
--- a/GitVer/GitVer.vcxproj.filters
+++ b/GitVer/GitVer.vcxproj.filters
@@ -57,6 +57,15 @@
    <ClInclude Include="GitVer_version.h">
      <Filter>头文件</Filter>
    </ClInclude>
+    <ClInclude Include="GitVer_setup.h">
+      <Filter>头文件</Filter>
+    </ClInclude>
+    <ClInclude Include="GitVer_upload.h">
+      <Filter>头文件</Filter>
+    </ClInclude>
+    <ClInclude Include="httplib.h">
+      <Filter>头文件</Filter>
+    </ClInclude>
  </ItemGroup>
  <ItemGroup>
    <ClCompile Include="GitVer.cpp">
@@ -89,6 +98,12 @@
    <ClCompile Include="GitVer_version.cpp">
      <Filter>源文件</Filter>
    </ClCompile>
+    <ClCompile Include="GitVer_setup.cpp">
+      <Filter>源文件</Filter>
+    </ClCompile>
+    <ClCompile Include="GitVer_upload.cpp">
+      <Filter>源文件</Filter>
+    </ClCompile>
  </ItemGroup>
  <ItemGroup>
    <ResourceCompile Include="GitVer.rc">
--- a/GitVer/GitVer_cli.cpp
+++ b/GitVer/GitVer_cli.cpp
@@ -5,11 +5,24 @@

 extern TCHAR g_szCurModuleDir[MAX_PATH];

+/// <summary>
+/// 打印无效仓库路径的错误信息。
+/// </summary>
+/// <param name="lpRepoPath">无效的路径字符串。</param>
 void PrintInvalidRepoPathError(LPCTSTR lpRepoPath)
 {
 	_tprintf(_T("错误: 无效的仓库路径 %s\n"), lpRepoPath == NULL ? _T("<null>") : lpRepoPath);
 }

+/// <summary>
+/// 解析 setver / nuitka / pyinstaller 等命令的 repodir= 与 -test 可选参数。
+/// </summary>
+/// <param name="argc">参数个数。</param>
+/// <param name="argv">参数数组。</param>
+/// <param name="nStartIndex">开始解析的下标。</param>
+/// <param name="lpRepoPath">输出：仓库路径，未指定时为当前模块目录。</param>
+/// <param name="bTestMode">输出：是否启用测试模式。</param>
+/// <returns>0 成功；3 多余参数；23 无效 repodir。</returns>
 int ParseSetVerOptions(int argc, TCHAR* argv[], int nStartIndex, LPCTSTR& lpRepoPath, BOOL& bTestMode)
 {
 	lpRepoPath = NULL;
@@ -53,6 +66,14 @@ int ParseSetVerOptions(int argc, TCHAR* argv[], int nStartIndex, LPCTSTR& lpRepo
 	return 0;
 }

+/// <summary>
+/// 解析 rewrite 命令的可选 PE 类型（1=exe，2=dll）与 -f 强制标志。
+/// </summary>
+/// <param name="argc">参数个数。</param>
+/// <param name="argv">参数数组（argv[0] 为 "rewrite"）。</param>
+/// <param name="nPEType">输出：PE 类型，默认 1。</param>
+/// <param name="bForceRewrite">输出：是否忽略重写失败。</param>
+/// <returns>0 成功；22 PE 类型无效或重复。</returns>
 int ParseRewriteOptions(int argc, TCHAR* argv[], int& nPEType, BOOL& bForceRewrite)
 {
 	nPEType = 1;
--- a/GitVer/GitVer_cli.h
+++ b/GitVer/GitVer_cli.h
@@ -1,5 +1,16 @@
 #pragma once

+/// <summary>
+/// 打印无效仓库路径的错误信息。
+/// </summary>
 void PrintInvalidRepoPathError(LPCTSTR lpRepoPath);
+
+/// <summary>
+/// 解析 setver 等命令的 repodir= 与 -test 可选参数。
+/// </summary>
 int ParseSetVerOptions(int argc, TCHAR* argv[], int nStartIndex, LPCTSTR& lpRepoPath, BOOL& bTestMode);
+
+/// <summary>
+/// 解析 rewrite 命令的 PE 类型与 -f 强制标志。
+/// </summary>
 int ParseRewriteOptions(int argc, TCHAR* argv[], int& nPEType, BOOL& bForceRewrite);
--- a/GitVer/GitVer_common.cpp
+++ b/GitVer/GitVer_common.cpp
@@ -2,6 +2,12 @@
 #include "gitver.h"
 #include "gitver_common.h"

+/// <summary>
+/// 将命令行参数拼接为便于日志输出的字符串（含引号转义）。
+/// </summary>
+/// <param name="argc">参数个数。</param>
+/// <param name="argv">参数数组。</param>
+/// <returns>空格分隔、已转义的参数字符串。</returns>
 CString BuildArgsForLog(int argc, TCHAR* argv[])
 {
 	CString strArgs;
@@ -16,6 +22,11 @@ CString BuildArgsForLog(int argc, TCHAR* argv[])
 	return strArgs;
 }

+/// <summary>
+/// 记录命令开始时间并输出开始日志。
+/// </summary>
+/// <param name="lpCommandName">命令名称。</param>
+/// <returns>当前 GetTickCount 值，供 LogCommandEnd 计算耗时。</returns>
 DWORD LogCommandStart(LPCTSTR lpCommandName)
 {
 	DWORD dwStartTick = GetTickCount();
@@ -23,6 +34,11 @@ DWORD LogCommandStart(LPCTSTR lpCommandName)
 	return dwStartTick;
 }

+/// <summary>
+/// 为命令行参数添加引号转义（含空格、制表符或双引号时加引号）。
+/// </summary>
+/// <param name="strArg">原始参数字符串。</param>
+/// <returns>可直接用于命令行的参数字符串。</returns>
 CString QuoteCmdArg(const CString& strArg)
 {
 	if (strArg.Find(_T(' ')) == -1 && strArg.Find(_T('\t')) == -1 && strArg.Find(_T('"')) == -1)
@@ -37,6 +53,12 @@ CString QuoteCmdArg(const CString& strArg)
 	return strQuoted;
 }

+/// <summary>
+/// 尝试将字符串解析为 0-65535 范围内的无符号整数。
+/// </summary>
+/// <param name="strValue">待解析字符串。</param>
+/// <param name="nValue">输出：解析结果。</param>
+/// <returns>解析成功返回 TRUE。</returns>
 BOOL TryParseUInt16(const CString& strValue, UINT& nValue)
 {
 	CString strTrimmed = strValue;
@@ -64,6 +86,15 @@ BOOL TryParseUInt16(const CString& strValue, UINT& nValue)
 	return TRUE;
 }

+/// <summary>
+/// 解析 argv[nIndex] 为 UInt16，失败时打印错误并返回指定错误码。
+/// </summary>
+/// <param name="argv">参数数组。</param>
+/// <param name="nIndex">要解析的参数下标。</param>
+/// <param name="lpArgName">参数名（用于错误提示）。</param>
+/// <param name="nValue">输出：解析结果。</param>
+/// <param name="nErrorCode">解析失败时的退出码。</param>
+/// <returns>0 成功，否则返回 nErrorCode。</returns>
 int ParseUInt16ArgOrError(TCHAR* argv[], int nIndex, LPCTSTR lpArgName, UINT& nValue, int nErrorCode)
 {
 	if (!TryParseUInt16(argv[nIndex], nValue))
@@ -75,6 +106,11 @@ int ParseUInt16ArgOrError(TCHAR* argv[], int nIndex, LPCTSTR lpArgName, UINT& nV
 	return 0;
 }

+/// <summary>
+/// 判断参数字符串是否像路径（含 \、/、: 或以 . 开头）。
+/// </summary>
+/// <param name="lpArg">待判断的参数字符串。</param>
+/// <returns>像路径则返回 TRUE。</returns>
 BOOL IsLikelyPathArg(LPCTSTR lpArg)
 {
 	if (lpArg == NULL)
--- a/GitVer/GitVer_common.h
+++ b/GitVer/GitVer_common.h
@@ -1,8 +1,31 @@
 #pragma once

+/// <summary>
+/// 将命令行参数拼接为便于日志输出的字符串。
+/// </summary>
 CString BuildArgsForLog(int argc, TCHAR* argv[]);
+
+/// <summary>
+/// 记录命令开始时间并输出开始日志，返回 tick 供计算耗时。
+/// </summary>
 DWORD LogCommandStart(LPCTSTR lpCommandName);
+
+/// <summary>
+/// 为命令行参数添加引号转义。
+/// </summary>
 CString QuoteCmdArg(const CString& strArg);
+
+/// <summary>
+/// 尝试将字符串解析为 0-65535 范围内的无符号整数。
+/// </summary>
 BOOL TryParseUInt16(const CString& strValue, UINT& nValue);
+
+/// <summary>
+/// 解析 argv[nIndex] 为 UInt16，失败时打印错误并返回指定错误码。
+/// </summary>
 int ParseUInt16ArgOrError(TCHAR* argv[], int nIndex, LPCTSTR lpArgName, UINT& nValue, int nErrorCode);
+
+/// <summary>
+/// 判断参数字符串是否像路径。
+/// </summary>
 BOOL IsLikelyPathArg(LPCTSTR lpArg);
--- a/GitVer/GitVer_nuitka.cpp
+++ b/GitVer/GitVer_nuitka.cpp
@@ -11,6 +11,15 @@ extern TCHAR g_szCurModuleDir[MAX_PATH];
 const UINT DEFAULT_MAJOR_WHEN_NO_TAG_FOR_NUITKA = 1;
 const UINT DEFAULT_MINOR_WHEN_NO_TAG_FOR_NUITKA = 0;

+/// <summary>
+/// 解析 nuitkabuild / nuitkapydbuild 命令的 repodir=、params= 与 -test 参数。
+/// </summary>
+/// <param name="argc">参数个数。</param>
+/// <param name="argv">参数数组。</param>
+/// <param name="lpRepoPath">输出：仓库路径。</param>
+/// <param name="strExtraArgs">输出：传给 Nuitka 的额外参数。</param>
+/// <param name="bTestMode">输出：是否测试模式。</param>
+/// <returns>0 成功；3 未知/重复参数；23 无效 repodir。</returns>
 static int ParseNuitkaOptions(int argc, TCHAR* argv[], LPCTSTR& lpRepoPath, CString& strExtraArgs, BOOL& bTestMode)
 {
 	lpRepoPath = NULL;
@@ -71,6 +80,14 @@ static int ParseNuitkaOptions(int argc, TCHAR* argv[], LPCTSTR& lpRepoPath, CStr
 	return 0;
 }

+/// <summary>
+/// 执行 Nuitka 构建命令并输出版本信息与构建结果。
+/// </summary>
+/// <param name="lpStartMessage">构建开始提示语。</param>
+/// <param name="strNuitkaCmd">完整 Nuitka 命令行。</param>
+/// <param name="strProductVersion">产品版本号（仅日志）。</param>
+/// <param name="strFileVersion">文件版本号（仅日志）。</param>
+/// <param name="lpRepoPath">工作目录。</param>
 static void RunNuitkaBuild(LPCTSTR lpStartMessage, CString& strNuitkaCmd, const CString& strProductVersion, const CString& strFileVersion, LPCTSTR lpRepoPath)
 {
 	_tprintf(_T("%s\n"), lpStartMessage);
@@ -86,6 +103,20 @@ static void RunNuitkaBuild(LPCTSTR lpStartMessage, CString& strNuitkaCmd, const
 	}
 }

+/// <summary>
+/// nuitkabuild / nuitkapydbuild 命令的公共实现：解析 pid、生成版本、调用 Nuitka。
+/// </summary>
+/// <param name="argc">参数个数。</param>
+/// <param name="argv">参数数组。</param>
+/// <param name="nCmdPrefixLen">argv[1] 中 "xxx=" 前缀长度。</param>
+/// <param name="bBuildModule">TRUE 时使用 --module 模式。</param>
+/// <param name="lpStartMessage">构建开始提示语。</param>
+/// <param name="lpUsageName">命令名（用于错误提示）。</param>
+/// <param name="nPidErrorCode">pid 无效时的退出码。</param>
+/// <param name="nBidErrorCode">获取 bid 失败时的退出码。</param>
+/// <param name="nTagErrorCode">获取 Tag 失败时的退出码。</param>
+/// <param name="nCommitErrorCode">获取提交信息失败时的退出码。</param>
+/// <returns>0 成功，否则为对应错误码。</returns>
 static int HandleNuitkaBuildCommandCore(
 	int argc,
 	TCHAR* argv[],
@@ -165,6 +196,12 @@ static int HandleNuitkaBuildCommandCore(
 	return 0;
 }

+/// <summary>
+/// 处理 nuitkabuild=pid 命令：standalone 可执行文件打包。
+/// </summary>
+/// <param name="argc">参数个数。</param>
+/// <param name="argv">参数数组。</param>
+/// <returns>0 成功，17-21 等为各类错误码。</returns>
 int HandleNuitkaBuildCommand(int argc, TCHAR* argv[])
 {
 	return HandleNuitkaBuildCommandCore(
@@ -180,6 +217,12 @@ int HandleNuitkaBuildCommand(int argc, TCHAR* argv[])
 		21);
 }

+/// <summary>
+/// 处理 nuitkapydbuild=pid 命令：Python 扩展模块（.pyd）打包。
+/// </summary>
+/// <param name="argc">参数个数。</param>
+/// <param name="argv">参数数组。</param>
+/// <returns>0 成功，24-28 等为各类错误码。</returns>
 int HandleNuitkaPydBuildCommand(int argc, TCHAR* argv[])
 {
 	return HandleNuitkaBuildCommandCore(
--- a/GitVer/GitVer_nuitka.h
+++ b/GitVer/GitVer_nuitka.h
@@ -1,4 +1,11 @@
 #pragma once

+/// <summary>
+/// 处理 nuitkabuild=pid 命令：standalone 可执行文件打包。
+/// </summary>
 int HandleNuitkaBuildCommand(int argc, TCHAR* argv[]);
+
+/// <summary>
+/// 处理 nuitkapydbuild=pid 命令：Python 扩展模块（.pyd）打包。
+/// </summary>
 int HandleNuitkaPydBuildCommand(int argc, TCHAR* argv[]);
--- a/GitVer/GitVer_process.cpp
+++ b/GitVer/GitVer_process.cpp
@@ -2,6 +2,13 @@
 #include "gitver.h"
 #include "gitver_process.h"

+/// <summary>
+/// 按顺序将文件中多处旧字符串替换为新字符串并写回。
+/// </summary>
+/// <param name="lpFile">目标文件路径。</param>
+/// <param name="vtOldContent">待查找的旧内容列表。</param>
+/// <param name="vtNewContent">对应的新内容列表。</param>
+/// <returns>全部替换成功返回 TRUE。</returns>
 BOOL ReplaceFileContent(LPCTSTR lpFile, std::vector<std::string>& vtOldContent, std::vector<std::string>& vtNewContent)
 {
 	if (vtOldContent.size() != vtNewContent.size())
@@ -69,9 +76,74 @@ BOOL ReplaceFileContent(LPCTSTR lpFile, std::vector<std::string>& vtOldContent,
 	return TRUE;
 }

-CString StartProcess(LPCTSTR program, LPCTSTR args, LPCTSTR lpCurrentDirectory)
+/// <summary>
+/// 将子进程管道输出的原始字节按指定代码页解码为 CString。
+/// </summary>
+/// <param name="strRawOutput">管道原始输出字节。</param>
+/// <param name="nOutputCodePage">解码代码页（CP_UTF8 或 CP_ACP 等）。</param>
+/// <returns>解码后的字符串。</returns>
+static CString DecodeProcessOutput(const std::string& strRawOutput, UINT nOutputCodePage)
 {
-	CString strValue = _T("");
+	if (strRawOutput.empty())
+	{
+		return CString();
+	}
+
+	if (nOutputCodePage == CP_UTF8)
+	{
+		int nWideSize = MultiByteToWideChar(CP_UTF8, 0, strRawOutput.data(), (int)strRawOutput.size(), NULL, 0);
+		if (nWideSize <= 0)
+		{
+			return CString();
+		}
+
+		CStringW strWide;
+		MultiByteToWideChar(CP_UTF8, 0, strRawOutput.data(), (int)strRawOutput.size(), strWide.GetBuffer(nWideSize), nWideSize);
+		strWide.ReleaseBuffer(nWideSize);
+
+#ifdef UNICODE
+		return CString(strWide);
+#else
+		int nGbkSize = WideCharToMultiByte(CP_ACP, 0, strWide, strWide.GetLength(), NULL, 0, NULL, NULL);
+		if (nGbkSize <= 0)
+		{
+			return CString();
+		}
+
+		std::string strGbk;
+		strGbk.resize(nGbkSize);
+		WideCharToMultiByte(CP_ACP, 0, strWide, strWide.GetLength(), &strGbk[0], nGbkSize, NULL, NULL);
+		return CString(strGbk.c_str(), (int)strGbk.size());
+#endif
+	}
+
+#ifdef UNICODE
+	int nSize = MultiByteToWideChar(nOutputCodePage, 0, strRawOutput.data(), (int)strRawOutput.size(), NULL, 0);
+	if (nSize <= 0)
+	{
+		return CString();
+	}
+
+	CString strValue;
+	MultiByteToWideChar(nOutputCodePage, 0, strRawOutput.data(), (int)strRawOutput.size(), strValue.GetBuffer(nSize), nSize);
+	strValue.ReleaseBuffer(nSize);
+	return strValue;
+#else
+	return CString(strRawOutput.c_str(), (int)strRawOutput.size());
+#endif
+}
+
+/// <summary>
+/// 启动子进程并捕获 stdout/stderr，按代码页解码后返回输出。
+/// </summary>
+/// <param name="program">可执行程序路径，NULL 时使用 args 中的命令。</param>
+/// <param name="args">命令行参数。</param>
+/// <param name="lpCurrentDirectory">工作目录。</param>
+/// <param name="nOutputCodePage">输出解码代码页，默认 CP_ACP。</param>
+/// <returns>子进程的标准输出/错误合并文本。</returns>
+CString StartProcess(LPCTSTR program, LPCTSTR args, LPCTSTR lpCurrentDirectory, UINT nOutputCodePage)
+{
+	std::string strRawOutput;
 	const int MY_PIPE_BUFFER_SIZE = 8912;
 	CString strMutableArgs = args == NULL ? _T("") : args;
 	LPTSTR lpArgs = strMutableArgs.IsEmpty() ? NULL : strMutableArgs.GetBuffer();
@@ -128,12 +200,7 @@ CString StartProcess(LPCTSTR program, LPCTSTR args, LPCTSTR lpCurrentDirectory)
 					break;
 				}

-				szPipeOut[dwStdLen] = '\0';
-#ifdef UNICODE
-				strValue.AppendFormat(_T("%hs"), szPipeOut);
-#else
-				strValue += szPipeOut;
-#endif
+				strRawOutput.append(szPipeOut, dwStdLen);
 			}

 			WaitForSingleObject(processInfo.hProcess, INFINITE);
@@ -160,6 +227,8 @@ CString StartProcess(LPCTSTR program, LPCTSTR args, LPCTSTR lpCurrentDirectory)
 		strMutableArgs.ReleaseBuffer();
 	}

+	CString strValue = DecodeProcessOutput(strRawOutput, nOutputCodePage);
+
 	_tprintf(_T("StartProcess program=%s args=%s cwd=%s output=%s\n"),
 		program == NULL ? _T("<null>") : program,
 		args == NULL ? _T("<null>") : args,
--- a/GitVer/GitVer_process.h
+++ b/GitVer/GitVer_process.h
@@ -1,4 +1,13 @@
 #pragma once

+/// <summary>
+/// 按顺序将文件中多处旧字符串替换为新字符串并写回。
+/// </summary>
 BOOL ReplaceFileContent(LPCTSTR lpFile, std::vector<std::string>& vtOldContent, std::vector<std::string>& vtNewContent);
-CString StartProcess(LPCTSTR program, LPCTSTR args, LPCTSTR lpCurrentDirectory);
+
+/// <summary>
+/// 启动子进程并捕获 stdout/stderr。
+/// nOutputCodePage 为管道原始字节的解码代码页，默认 CP_ACP（按系统 ANSI/GBK 直接使用）；
+/// CP_UTF8 时先按 UTF-8 解码为宽字符，MultiByte 工程再转为 GBK 存入 CString。
+/// </summary>
+CString StartProcess(LPCTSTR program, LPCTSTR args, LPCTSTR lpCurrentDirectory, UINT nOutputCodePage = CP_ACP);
--- a/GitVer/GitVer_pyinstaller.cpp
+++ b/GitVer/GitVer_pyinstaller.cpp
@@ -11,6 +11,15 @@ extern TCHAR g_szCurModuleDir[MAX_PATH];
 const UINT DEFAULT_MAJOR_WHEN_NO_TAG_FOR_PYINSTALLER = 1;
 const UINT DEFAULT_MINOR_WHEN_NO_TAG_FOR_PYINSTALLER = 0;

+/// <summary>
+/// 解析 pyinstaller 命令的 repodir=、params= 与 -test 参数。
+/// </summary>
+/// <param name="argc">参数个数。</param>
+/// <param name="argv">参数数组。</param>
+/// <param name="lpRepoPath">输出：仓库路径。</param>
+/// <param name="strExtraArgs">输出：传给 PyInstaller 的参数。</param>
+/// <param name="bTestMode">输出：是否测试模式。</param>
+/// <returns>0 成功；3 未知/重复参数；23 无效 repodir。</returns>
 static int ParsePyinstallerOptions(int argc, TCHAR* argv[], LPCTSTR& lpRepoPath, CString& strExtraArgs, BOOL& bTestMode)
 {
 	lpRepoPath = NULL;
@@ -71,7 +80,15 @@ static int ParsePyinstallerOptions(int argc, TCHAR* argv[], LPCTSTR& lpRepoPath,
 	return 0;
 }

-// 解析版本字符串 "a.b.c.d" → 四个分量
+/// <summary>
+/// 解析版本字符串 "a.b.c.d" 为四个无符号整数分量。
+/// </summary>
+/// <param name="lpVer">版本字符串。</param>
+/// <param name="v1">输出：第 1 段。</param>
+/// <param name="v2">输出：第 2 段。</param>
+/// <param name="v3">输出：第 3 段。</param>
+/// <param name="v4">输出：第 4 段。</param>
+/// <returns>格式正确返回 TRUE。</returns>
 static BOOL ParseVersionTuple(LPCTSTR lpVer, UINT& v1, UINT& v2, UINT& v3, UINT& v4)
 {
 	CString str(lpVer);
@@ -88,7 +105,11 @@ static BOOL ParseVersionTuple(LPCTSTR lpVer, UINT& v1, UINT& v2, UINT& v3, UINT&
 	return TRUE;
 }

-// 提取 params 中第一个空格分隔的 token（支持双引号括起的路径）
+/// <summary>
+/// 提取 params 字符串中第一个 token（支持双引号括起的路径）。
+/// </summary>
+/// <param name="strParams">完整 params 参数字符串。</param>
+/// <returns>第一个 token，空输入返回空字符串。</returns>
 static CString ExtractFirstToken(const CString& strParams)
 {
 	CString str = strParams;
@@ -105,7 +126,14 @@ static CString ExtractFirstToken(const CString& strParams)
 	return str.Left(nSpace);
 }

-// 生成 version_info.txt 到 lpDir 目录（PyInstaller VSVersionInfo 格式）
+/// <summary>
+/// 在指定目录生成 PyInstaller VSVersionInfo 格式的 version_info.txt。
+/// </summary>
+/// <param name="lpDir">输出目录。</param>
+/// <param name="lpProductVersion">产品版本号。</param>
+/// <param name="lpFileVersion">文件版本号。</param>
+/// <param name="strOutPath">输出：生成的文件完整路径。</param>
+/// <returns>成功返回 TRUE。</returns>
 static BOOL WriteVersionInfoFile(LPCTSTR lpDir, LPCTSTR lpProductVersion, LPCTSTR lpFileVersion, CString& strOutPath)
 {
 	UINT pv1 = 0, pv2 = 0, pv3 = 0, pv4 = 0;
@@ -165,8 +193,12 @@ static BOOL WriteVersionInfoFile(LPCTSTR lpDir, LPCTSTR lpProductVersion, LPCTST
 	return TRUE;
 }

-// 向 .spec 文件注入或更新 version= 参数
-// 若已有 version= 则更新其值，否则在 name= 参数后新增一行
+/// <summary>
+/// 向 .spec 文件注入或更新 version='version_info.txt' 参数。
+/// 已有 version= 则更新整行，否则在 name= 行后插入。
+/// </summary>
+/// <param name="lpSpecPath">.spec 文件路径。</param>
+/// <returns>成功返回 TRUE。</returns>
 static BOOL InjectVersionIntoSpec(LPCTSTR lpSpecPath)
 {
 	if (!PathFileExists(lpSpecPath))
@@ -260,8 +292,12 @@ static BOOL InjectVersionIntoSpec(LPCTSTR lpSpecPath)
 	return TRUE;
 }

-// 从 .spec 文件读取 version= 参数的值（单/双引号括起的路径）
-// 返回 FALSE 表示未找到、值为 None 或值为空
+/// <summary>
+/// 从 .spec 文件读取 version= 参数引号内的外部版本信息文件路径。
+/// </summary>
+/// <param name="lpSpecPath">.spec 文件路径。</param>
+/// <param name="strVersionPath">输出：version= 指向的路径。</param>
+/// <returns>找到有效引号路径返回 TRUE；None 或空值返回 FALSE。</returns>
 static BOOL ReadVersionPathFromSpec(LPCTSTR lpSpecPath, CString& strVersionPath)
 {
 	strVersionPath.Empty();
@@ -310,7 +346,13 @@ static BOOL ReadVersionPathFromSpec(LPCTSTR lpSpecPath, CString& strVersionPath)
 	return FALSE;
 }

-// 更新已有 version_info 文件的版本字段；若文件不存在则创建
+/// <summary>
+/// 更新已有 version_info 文件的版本字段；文件不存在时按模板创建。
+/// </summary>
+/// <param name="lpPath">version_info.txt 或内联 spec 路径。</param>
+/// <param name="lpProductVersion">产品版本号。</param>
+/// <param name="lpFileVersion">文件版本号。</param>
+/// <returns>成功返回 TRUE。</returns>
 static BOOL UpdateVersionInfoFile(LPCTSTR lpPath, LPCTSTR lpProductVersion, LPCTSTR lpFileVersion)
 {
 	UINT pv1 = 0, pv2 = 0, pv3 = 0, pv4 = 0;
@@ -462,7 +504,11 @@ static BOOL UpdateVersionInfoFile(LPCTSTR lpPath, LPCTSTR lpProductVersion, LPCT
 	return TRUE;
 }

-// 检查 spec 文件中 version= 是否为无引号标识符（表示 spec 内内联 VSVersionInfo 对象）
+/// <summary>
+/// 检查 .spec 中 version= 是否为无引号的 Python 标识符（内联 VSVersionInfo 对象名）。
+/// </summary>
+/// <param name="lpSpecPath">.spec 文件路径。</param>
+/// <returns>是内联版本块引用返回 TRUE。</returns>
 static BOOL HasInlineVersionInfoBlock(LPCTSTR lpSpecPath)
 {
 	if (!PathFileExists(lpSpecPath)) return FALSE;
@@ -504,8 +550,12 @@ static BOOL HasInlineVersionInfoBlock(LPCTSTR lpSpecPath)
 	return FALSE;
 }

-// 修改 spec 文件中 version= 的引号值（内联版本号字符串场景）
-// 当 version= 后是非外部文件路径的字符串字面量时，直接替换该值为新版本号
+/// <summary>
+/// 替换 .spec 文件中 version= 引号内的内联版本号字符串。
+/// </summary>
+/// <param name="lpSpecPath">.spec 文件路径。</param>
+/// <param name="lpNewValue">新版本号字符串。</param>
+/// <returns>找到并替换返回 TRUE。</returns>
 static BOOL UpdateVersionStringInSpec(LPCTSTR lpSpecPath, LPCTSTR lpNewValue)
 {
 	if (!PathFileExists(lpSpecPath))
@@ -581,6 +631,12 @@ static BOOL UpdateVersionStringInSpec(LPCTSTR lpSpecPath, LPCTSTR lpNewValue)
 	return TRUE;
 }

+/// <summary>
+/// 处理 pyinstaller=pid 命令：生成版本、处理 spec/version_info、调用 PyInstaller 打包。
+/// </summary>
+/// <param name="argc">参数个数。</param>
+/// <param name="argv">参数数组。</param>
+/// <returns>0 成功；40-46 等为各类错误码。</returns>
 int HandlePyinstallerBuildCommand(int argc, TCHAR* argv[])
 {
 #ifdef _DEBUG
--- a/GitVer/GitVer_pyinstaller.h
+++ b/GitVer/GitVer_pyinstaller.h
@@ -1,3 +1,6 @@
 #pragma once

+/// <summary>
+/// 处理 pyinstaller=pid 命令：生成版本信息并调用 PyInstaller 打包。
+/// </summary>
 int HandlePyinstallerBuildCommand(int argc, TCHAR* argv[]);
--- a/GitVer/GitVer_rewrite.cpp
+++ b/GitVer/GitVer_rewrite.cpp
@@ -14,6 +14,12 @@ LPCTSTR GetProjectCodeTypeName(int nCodeType);
 /// <summary>
 /// 替换指定范围内包含指定标记的整行内容。
 /// </summary>
+/// <param name="strContent">文件内容（原地修改）。</param>
+/// <param name="strToken">行内查找标记。</param>
+/// <param name="strNewLine">替换后的整行文本。</param>
+/// <param name="nRangeStart">搜索范围起始偏移。</param>
+/// <param name="nRangeEnd">搜索范围结束偏移。</param>
+/// <returns>找到并替换返回 TRUE。</returns>
 BOOL ReplaceWholeLineByTokenInRange(std::string& strContent, const std::string& strToken, const std::string& strNewLine, size_t nRangeStart, size_t nRangeEnd)
 {
 	if (nRangeStart == std::string::npos || nRangeEnd == std::string::npos || nRangeStart >= nRangeEnd)
@@ -54,11 +60,17 @@ BOOL ReplaceWholeLineByTokenInRange(std::string& strContent, const std::string&
 	return TRUE;
 }

+/// <summary>
+/// 在全文件范围内替换包含指定标记的整行。
+/// </summary>
 BOOL ReplaceWholeLineByToken(std::string& strContent, const std::string& strToken, const std::string& strNewLine)
 {
 	return ReplaceWholeLineByTokenInRange(strContent, strToken, strNewLine, 0, strContent.size());
 }

+/// <summary>
+/// 替换首个匹配行，并删除后续所有含同一标记的重复行。
+/// </summary>
 BOOL EnsureSingleLineByToken(std::string& strContent, const std::string& strToken, const std::string& strNewLine)
 {
 	std::string::size_type nPos = strContent.find(strToken);
@@ -127,6 +139,9 @@ BOOL EnsureSingleLineByToken(std::string& strContent, const std::string& strToke
 	return TRUE;
 }

+/// <summary>
+/// 若存在含标记的行则替换并去重，否则在文件末尾追加新行。
+/// </summary>
 BOOL EnsureSingleLineByTokenOrAppend(std::string& strContent, const std::string& strToken, const std::string& strNewLine)
 {
 	if (strContent.find(strToken) != std::string::npos)
@@ -147,6 +162,13 @@ BOOL EnsureSingleLineByTokenOrAppend(std::string& strContent, const std::string&
 	return TRUE;
 }

+/// <summary>
+/// 定位 .rc 文件中 VS_VERSION_INFO VERSIONINFO 块的 BEGIN…END 字节范围。
+/// </summary>
+/// <param name="strContent">.rc 文件内容。</param>
+/// <param name="nBlockStart">输出：块起始偏移。</param>
+/// <param name="nBlockEnd">输出：块结束偏移（不含末尾换行之后）。</param>
+/// <returns>找到完整块返回 TRUE。</returns>
 BOOL FindVersionInfoBlockRange(const std::string& strContent, size_t& nBlockStart, size_t& nBlockEnd)
 {
 	nBlockStart = std::string::npos;
@@ -210,6 +232,12 @@ BOOL FindVersionInfoBlockRange(const std::string& strContent, size_t& nBlockStar
 	return FALSE;
 }

+/// <summary>
+/// 检测文本文件 BOM 类型；UTF-16 BOM 视为不支持。
+/// </summary>
+/// <param name="strData">文件原始字节。</param>
+/// <param name="nBomLength">输出：BOM 长度（无 BOM 时为 0）。</param>
+/// <returns>支持的编码返回 TRUE，UTF-16 返回 FALSE。</returns>
 BOOL DetectSupportedTextBom(const std::string& strData, size_t& nBomLength)
 {
 	nBomLength = 0;
@@ -236,6 +264,13 @@ BOOL DetectSupportedTextBom(const std::string& strData, size_t& nBomLength)
 	return TRUE;
 }

+/// <summary>
+/// 以 ANSI/UTF-8（带 BOM 时保留前缀）读取文本文件。
+/// </summary>
+/// <param name="lpFile">文件路径。</param>
+/// <param name="strContent">输出：不含 BOM 的正文。</param>
+/// <param name="strBomPrefix">输出：原始 BOM 前缀，写回时需保留。</param>
+/// <returns>读取成功返回 TRUE。</returns>
 BOOL ReadTextFileAsAnsi(LPCTSTR lpFile, std::string& strContent, std::string& strBomPrefix)
 {
 	strContent.clear();
@@ -284,6 +319,13 @@ BOOL ReadTextFileAsAnsi(LPCTSTR lpFile, std::string& strContent, std::string& st
 	return TRUE;
 }

+/// <summary>
+/// 将文本内容与 BOM 前缀写回文件。
+/// </summary>
+/// <param name="lpFile">文件路径。</param>
+/// <param name="strContent">正文内容。</param>
+/// <param name="strBomPrefix">BOM 前缀（可为空）。</param>
+/// <returns>写入成功返回 TRUE。</returns>
 BOOL WriteTextFileAsAnsi(LPCTSTR lpFile, const std::string& strContent, const std::string& strBomPrefix)
 {
 	CFile myFile;
@@ -303,6 +345,13 @@ BOOL WriteTextFileAsAnsi(LPCTSTR lpFile, const std::string& strContent, const st
 	return TRUE;
 }

+/// <summary>
+/// 将 ProductVersion / FileVersion 写入 C++ .rc 文件的 VERSIONINFO 块。
+/// </summary>
+/// <param name="strRcFile">.rc 文件路径。</param>
+/// <param name="strProductVersion">产品版本号。</param>
+/// <param name="strFileVersion">文件版本号。</param>
+/// <returns>成功返回 TRUE。</returns>
 BOOL RewriteSetVerToCppRc(const CString& strRcFile, const CString& strProductVersion, const CString& strFileVersion)
 {
 	std::string strContent;
@@ -356,6 +405,13 @@ BOOL RewriteSetVerToCppRc(const CString& strRcFile, const CString& strProductVer
 	return TRUE;
 }

+/// <summary>
+/// 将 ProductVersion / FileVersion 写入 C# AssemblyInfo.cs。
+/// </summary>
+/// <param name="strAssemblyInfoFile">AssemblyInfo.cs 路径。</param>
+/// <param name="strProductVersion">产品版本号（AssemblyVersion）。</param>
+/// <param name="strFileVersion">文件版本号（AssemblyFileVersion）。</param>
+/// <returns>成功返回 TRUE。</returns>
 BOOL RewriteSetVerToAssemblyInfo(const CString& strAssemblyInfoFile, const CString& strProductVersion, const CString& strFileVersion)
 {
 	std::string strContent;
@@ -392,6 +448,13 @@ BOOL RewriteSetVerToAssemblyInfo(const CString& strAssemblyInfoFile, const CStri
 	return TRUE;
 }

+/// <summary>
+/// 按项目类型（C++ / C#）将版本号写入对应资源文件。
+/// </summary>
+/// <param name="lpRepoPath">项目根目录，NULL 时使用当前模块目录。</param>
+/// <param name="strProductVersion">产品版本号。</param>
+/// <param name="strFileVersion">文件版本号。</param>
+/// <returns>0 成功；15 不支持的项目类型；35 写版本失败。</returns>
 int RewriteSetVerByProjectType(LPCTSTR lpRepoPath, const CString& strProductVersion, const CString& strFileVersion)
 {
 	LPCTSTR lpBaseDir = lpRepoPath == NULL ? g_szCurModuleDir : lpRepoPath;
--- a/GitVer/GitVer_rewrite.h
+++ b/GitVer/GitVer_rewrite.h
@@ -1,3 +1,6 @@
 #pragma once

+/// <summary>
+/// 按项目类型（C++ / C#）将版本号写入对应资源文件。
+/// </summary>
 int RewriteSetVerByProjectType(LPCTSTR lpRepoPath, const CString& strProductVersion, const CString& strFileVersion);
--- a/GitVer/GitVer_setup.cpp
+++ b/GitVer/GitVer_setup.cpp
--- a/GitVer/GitVer_setup.h
+++ b/GitVer/GitVer_setup.h
@@ -1,16 +1,16 @@
 #pragma once

 /// <summary>
-/// 查找安装脚本、修改版本号并调用编译器打包。
-/// nSetupType=0: Inno Setup (.iss)；nSetupType=1: NSIS (.nsi)。
-/// 不写回项目版本文件（.rc / AssemblyInfo.cs）。
+/// 查找安装脚本、修改版本号并调用编译器打包。
+/// nSetupType=0: Inno Setup (.iss)；nSetupType=1: NSIS (.nsi)。
+/// 不写回项目版本文件（.rc / AssemblyInfo.cs）。
 /// </summary>
-/// <returns>TRUE 成功；FALSE 失败（错误已打印）。</returns>
-BOOL ExecuteSetupBuild(int nSetupType, const CString& strProductVersion, const CString& strFileVersion);
+/// <returns>TRUE 成功；FALSE 失败（错误已打印）。</returns>
+BOOL ExecuteSetupBuild(int nSetupType, const CString& strProductVersion, const CString& strFileVersion, CString& strInstallerPath);

 /// <summary>
-/// 处理独立的 setup=n 命令行入口。
-/// 退出码：0 成功，36 setup 值不支持，37 未找到脚本，
-///          38 修改脚本失败，39 未找到编译器，其他同通用错误码。
+/// 处理独立的 setup=n 命令行入口。
+/// 退出码：0 成功，36 setup 值不支持，37 未找到脚本，
+///          38 修改脚本失败，39 未找到编译器，其他同通用错误码。
 /// </summary>
 int HandleSetupCommand(int argc, TCHAR* argv[]);
--- a/GitVer/GitVer_tag.cpp
+++ b/GitVer/GitVer_tag.cpp
@@ -10,6 +10,14 @@ extern TCHAR g_szCurModuleDir[MAX_PATH];
 const UINT DEFAULT_MAJOR_WHEN_NO_TAG_FOR_TAG = 1;
 const UINT DEFAULT_MINOR_WHEN_NO_TAG_FOR_TAG = 0;

+/// <summary>
+/// 获取当前分支下最近 nMaxCount 个符合 major.minor 格式的 Tag。
+/// </summary>
+/// <param name="lpRepoPath">仓库根目录。</param>
+/// <param name="strBranch">输出：当前分支名。</param>
+/// <param name="vtTags">输出：Tag 列表（按版本升序，取最后 nMaxCount 个）。</param>
+/// <param name="nMaxCount">最多返回的 Tag 数量。</param>
+/// <returns>成功返回 TRUE（无 Tag 时 vtTags 为空亦视为成功）。</returns>
 BOOL GetRecentMajorMinorTags(LPCTSTR lpRepoPath, CString& strBranch, std::vector<BranchTagInfo>& vtTags, int nMaxCount)
 {
 	vtTags.clear();
@@ -73,6 +81,10 @@ BOOL GetRecentMajorMinorTags(LPCTSTR lpRepoPath, CString& strBranch, std::vector
 	return TRUE;
 }

+/// <summary>
+/// 交互式 Tag 创建流程：展示最近 Tag、选择 major+1 或 minor+1、创建并推送。
+/// </summary>
+/// <returns>0 成功；30-34 交互/创建/验证失败；36 推送失败。</returns>
 int HandleCreateTagInteractive()
 {
 	CString strBranch;
--- a/GitVer/GitVer_tag.h
+++ b/GitVer/GitVer_tag.h
@@ -1,5 +1,8 @@
 #pragma once

+/// <summary>
+/// 分支 Tag 的 major/minor 解析结果。
+/// </summary>
 struct BranchTagInfo
 {
 	CString strTag;
@@ -7,5 +10,12 @@ struct BranchTagInfo
 	UINT nMinor;
 };

+/// <summary>
+/// 获取当前分支下最近 nMaxCount 个符合 major.minor 格式的 Tag。
+/// </summary>
 BOOL GetRecentMajorMinorTags(LPCTSTR lpRepoPath, CString& strBranch, std::vector<BranchTagInfo>& vtTags, int nMaxCount);
+
+/// <summary>
+/// 交互式 Tag 创建流程：展示最近 Tag、选择递增方式、创建并推送。
+/// </summary>
 int HandleCreateTagInteractive();
--- a/GitVer/GitVer_types.h
+++ b/GitVer/GitVer_types.h
@@ -1,5 +1,8 @@
 #pragma once

+/// <summary>
+/// 项目源码类型枚举。
+/// </summary>
 enum ProjectCodeType
 {
 	PROJECT_UNKNOWN = 0,
--- a/GitVer/GitVer_upload.cpp
+++ b/GitVer/GitVer_upload.cpp
--- a/GitVer/GitVer_upload.h
+++ b/GitVer/GitVer_upload.h
@@ -0,0 +1,22 @@
+#pragma once
+
+/// <summary>
+/// 处理 upload 命令：登录 PMC 并上传包文件。
+/// 退出码：0 成功，47 缺少参数，48 文件不存在，49 info 无效或未设置同名环境变量密码，
+///         50 登录失败，51 上传 HTTP 失败，52 验证未找到版本，53 网络错误，54 Tag/分支校验失败。
+/// </summary>
+int HandleUploadCommand(int argc, TCHAR* argv[]);
+
+/// <summary>
+/// 更新 upload_info.txt 中的 product_version、file_version、file_change_log，保留其他字段。
+/// </summary>
+BOOL WriteUploadInfoVersions(
+	LPCTSTR lpInfoFile,
+	LPCTSTR lpProductVersion,
+	LPCTSTR lpFileVersion,
+	LPCTSTR lpFileChangeLog);
+
+/// <summary>
+/// 更新 upload_info.txt 中的 file（安装包路径），保留其他字段。
+/// </summary>
+BOOL WriteUploadInfoPackageFile(LPCTSTR lpInfoFile, LPCTSTR lpPackageFile);
--- a/GitVer/GitVer_version.cpp
+++ b/GitVer/GitVer_version.cpp
@@ -4,6 +4,33 @@
 #include "gitver_process.h"
 #include "gitver_version.h"

+/// <summary>
+/// 检测 Git 仓库是否处于正常分支状态（非 HEAD 游离）。
+/// </summary>
+/// <param name="lpRepoPath">仓库根目录。</param>
+/// <param name="strStatus">输出：symbolic-ref HEAD 结果。</param>
+/// <returns>在分支上返回 TRUE，游离状态返回 FALSE。</returns>
+BOOL TryGetGitStatus(LPCTSTR lpRepoPath, CString& strStatus)
+{
+	strStatus = StartProcess(NULL, _T("cmd /c git symbolic-ref --quiet HEAD"), lpRepoPath);
+	strStatus.Replace(_T("\r"), _T(""));
+	strStatus.Trim();
+
+	if (strStatus.IsEmpty())
+	{// 游离状态
+		return FALSE;
+	}
+
+	// 正常状态;
+	return TRUE;
+}
+
+/// <summary>
+/// 获取当前检出的本地分支名称。
+/// </summary>
+/// <param name="lpRepoPath">仓库根目录。</param>
+/// <param name="strBranch">输出：分支名。</param>
+/// <returns>成功返回 TRUE。</returns>
 BOOL TryGetCurrentBranch(LPCTSTR lpRepoPath, CString& strBranch)
 {
 	_tprintf(_T("获取当前分支名称: \n"));
@@ -20,6 +47,59 @@ BOOL TryGetCurrentBranch(LPCTSTR lpRepoPath, CString& strBranch)
 	return TRUE;
 }

+/// <summary>
+/// 在 HEAD 游离时，通过远程分支推断当前所属分支名（origin/ 前缀已去除）。
+/// </summary>
+/// <param name="lpRepoPath">仓库根目录。</param>
+/// <param name="strBranch">输出：推断的分支名。</param>
+/// <returns>找到远程分支返回 TRUE。</returns>
+BOOL TryGetDetectedBranch(LPCTSTR lpRepoPath, CString& strBranch)
+{
+	// 远程仓库名必须以 origin 开头;
+	// "C:\Program Files\Git\bin\bash.exe" -c "git branch -r --contains HEAD | head -n1 | sed 's/.*origin\///'"
+	strBranch = StartProcess(NULL, _T("\"C:\\Program Files\\Git\\bin\\bash.exe\" -c \"git branch -r --contains HEAD | head -n1 | sed 's/.*origin\\///'\""), lpRepoPath);
+	//strBranch = StartProcess("C:\\Program Files\\Git\\bin\\bash.exe", _T("git branch -r --contains HEAD | head -n1 | sed 's/.*origin\\///'"), lpRepoPath);
+	strBranch.Replace(_T("\r"), _T(""));
+	strBranch.Replace(_T("\n"), _T(""));
+	strBranch.Trim();
+
+	if (strBranch.IsEmpty())
+	{
+		// 没有找到远程分支;
+		return FALSE;
+	}
+
+	return TRUE;
+}
+
+/// <summary>
+/// 获取指向当前 HEAD 的 Tag 名称。
+/// </summary>
+/// <param name="lpRepoPath">仓库根目录。</param>
+/// <param name="strTag">输出：Tag 名（多个时取 git 输出首行）。</param>
+/// <returns>存在 Tag 返回 TRUE。</returns>
+BOOL TryGetDetectedTag(LPCTSTR lpRepoPath, CString& strTag)
+{
+	strTag = StartProcess(NULL, _T("cmd /c git tag --points-at HEAD"), lpRepoPath);
+	strTag.Replace(_T("\r"), _T(""));
+	strTag.Replace(_T("\n"), _T(""));
+	strTag.Trim();
+
+	if (strTag.IsEmpty())
+	{
+		// 没有找到标签;
+		return FALSE;
+	}
+
+	return TRUE;
+}
+
+/// <summary>
+/// 从分支名解析 bid（分支 ID）：main/master=0，release=1，dev=2，其余取末段数字。
+/// </summary>
+/// <param name="strBranch">分支名称。</param>
+/// <param name="nBid">输出：分支 bid。</param>
+/// <returns>解析成功返回 TRUE。</returns>
 BOOL TryGetBidFromBranch(const CString& strBranch, UINT& nBid)
 {
 	nBid = 0;
@@ -34,6 +114,18 @@ BOOL TryGetBidFromBranch(const CString& strBranch, UINT& nBid)
 		return TRUE;
 	}

+	if (strBranch.CompareNoCase(_T("release")) == 0)
+	{
+		nBid = 1;
+		return TRUE;
+	}
+
+	if (strBranch.CompareNoCase(_T("dev")) == 0)
+	{
+		nBid = 2;
+		return TRUE;
+	}
+
 	int nDotPos = strBranch.ReverseFind(_T('.'));
 	if (nDotPos <= 0 || nDotPos >= strBranch.GetLength() - 1)
 	{
@@ -44,6 +136,14 @@ BOOL TryGetBidFromBranch(const CString& strBranch, UINT& nBid)
 	return TryParseUInt16(strNum, nBid);
 }

+/// <summary>
+/// 解析符合「分支名.major.minor」格式的 Tag，提取 major 与 minor。
+/// </summary>
+/// <param name="strBranch">分支名称。</param>
+/// <param name="strTag">Tag 名称。</param>
+/// <param name="nMajor">输出：主版本号。</param>
+/// <param name="nMinor">输出：次版本号。</param>
+/// <returns>格式匹配且解析成功返回 TRUE。</returns>
 BOOL TryParseTagMajorMinor(const CString& strBranch, const CString& strTag, UINT& nMajor, UINT& nMinor)
 {
 	if (strBranch.IsEmpty())
@@ -79,6 +179,15 @@ BOOL TryParseTagMajorMinor(const CString& strBranch, const CString& strTag, UINT
 	return TRUE;
 }

+/// <summary>
+/// 获取当前分支下版本号最大的 major.minor Tag（按 v:refname 排序遍历）。
+/// </summary>
+/// <param name="lpRepoPath">仓库根目录。</param>
+/// <param name="strBranch">分支名称。</param>
+/// <param name="strTag">输出：最新 Tag 全名。</param>
+/// <param name="nMajor">输出：主版本号。</param>
+/// <param name="nMinor">输出：次版本号。</param>
+/// <returns>找到匹配 Tag 返回 TRUE。</returns>
 BOOL GetLastMajorMinorTag(LPCTSTR lpRepoPath, const CString& strBranch, CString& strTag, UINT& nMajor, UINT& nMinor)
 {
 	strTag.Empty();
@@ -122,6 +231,13 @@ BOOL GetLastMajorMinorTag(LPCTSTR lpRepoPath, const CString& strBranch, CString&
 	return !strTag.IsEmpty();
 }

+/// <summary>
+/// 将 SYSTEMTIME 转换为 FileVersion 中的 yy 与 mmdd 分量。
+/// 月份 1-12 映射为 11-22（mmdd = (month+10)*100 + day）。
+/// </summary>
+/// <param name="stLocal">本地时间。</param>
+/// <param name="nYY">输出：年份后两位。</param>
+/// <param name="nMMDD">输出：编码后的月日。</param>
 void GetFileVersionDateFromSystemTime(const SYSTEMTIME& stLocal, UINT& nYY, UINT& nMMDD)
 {
 	nYY = stLocal.wYear % 100;
@@ -129,6 +245,14 @@ void GetFileVersionDateFromSystemTime(const SYSTEMTIME& stLocal, UINT& nYY, UINT
 	nMMDD = (stLocal.wMonth + 10) * 100 + stLocal.wDay;
 }

+/// <summary>
+/// 统计指定日期内 origin/分支 的提交次数（用于 FileVersion 末段 id）。
+/// </summary>
+/// <param name="lpRepoPath">仓库根目录。</param>
+/// <param name="strBranch">分支名称。</param>
+/// <param name="stDate">目标日期。</param>
+/// <param name="nId">输出：当日提交数。</param>
+/// <returns>成功返回 TRUE。</returns>
 BOOL TryGetBranchCommitCountByDate(LPCTSTR lpRepoPath, const CString& strBranch, const SYSTEMTIME& stDate, UINT& nId)
 {
 	nId = 0;
@@ -142,7 +266,7 @@ BOOL TryGetBranchCommitCountByDate(LPCTSTR lpRepoPath, const CString& strBranch,

 	CString strCmd;
 	strCmd.Format(
-		_T("cmd /c git rev-list --count --since=\"%s 00:00:00\" --until=\"%s 23:59:59\" \"%s\""),
+		_T("cmd /c git rev-list --count --since=\"%s 00:00:00\" --until=\"%s 23:59:59\" \"origin/%s\""),
 		strDate.GetString(),
 		strDate.GetString(),
 		strBranch.GetString());
@@ -167,6 +291,13 @@ BOOL TryGetBranchCommitCountByDate(LPCTSTR lpRepoPath, const CString& strBranch,
 	return TryParseUInt16(strCount, nId);
 }

+/// <summary>
+/// 获取分支最近一次提交的日期（git log -1 --date=short）。
+/// </summary>
+/// <param name="lpRepoPath">仓库根目录。</param>
+/// <param name="strBranch">分支名称。</param>
+/// <param name="stDate">输出：提交日期。</param>
+/// <returns>成功返回 TRUE。</returns>
 BOOL TryGetLastBranchCommitDate(LPCTSTR lpRepoPath, const CString& strBranch, SYSTEMTIME& stDate)
 {
 	::ZeroMemory(&stDate, sizeof(stDate));
@@ -209,7 +340,123 @@ BOOL TryGetLastBranchCommitDate(LPCTSTR lpRepoPath, const CString& strBranch, SY
 	return TRUE;
 }

-BOOL ResolveFileVersionDateAndCommitCount(LPCTSTR lpRepoPath, const CString& strBranch, UINT& nYY, UINT& nMMDD, UINT& nId)
+/// <summary>
+/// 获取 Tag 对应提交的日期（git log -1 --date=short）。
+/// </summary>
+/// <param name="lpRepoPath">仓库根目录。</param>
+/// <param name="strTag">Tag 名称。</param>
+/// <param name="stDate">输出：提交日期。</param>
+/// <returns>成功返回 TRUE。</returns>
+BOOL TryGetTagCommitDate(LPCTSTR lpRepoPath, const CString& strTag, SYSTEMTIME& stDate)
+{
+	::ZeroMemory(&stDate, sizeof(stDate));
+	if (strTag.IsEmpty())
+	{
+		return FALSE;
+	}
+
+	CString strCmd;
+	strCmd.Format(_T("cmd /c git log -1 --date=short --format=%%cd \"%s\""), strTag.GetString());
+
+	CString strDate = StartProcess(NULL, strCmd.GetBuffer(), lpRepoPath);
+	strCmd.ReleaseBuffer();
+
+	if (strDate.IsEmpty())
+	{
+		return FALSE;
+	}
+
+	strDate.Replace(_T("\r"), _T(""));
+	strDate.Replace(_T("\n"), _T(""));
+	strDate.Trim();
+
+	if (strDate.IsEmpty() || strDate.Left(6).CompareNoCase(_T("fatal:")) == 0)
+	{
+		return FALSE;
+	}
+
+	unsigned int nYear = 0;
+	unsigned int nMonth = 0;
+	unsigned int nDay = 0;
+	if (_stscanf_s(strDate.GetString(), _T("%u-%u-%u"), &nYear, &nMonth, &nDay) != 3)
+	{
+		return FALSE;
+	}
+
+	stDate.wYear = static_cast<WORD>(nYear);
+	stDate.wMonth = static_cast<WORD>(nMonth);
+	stDate.wDay = static_cast<WORD>(nDay);
+	return TRUE;
+}
+
+/// <summary>
+/// 基于 Tag 提交日期解析 FileVersion 的 yy、mmdd 与 id（当日提交数）。
+/// </summary>
+/// <param name="lpRepoPath">仓库根目录。</param>
+/// <param name="strBranch">分支名称。</param>
+/// <param name="strTag">Tag 名称。</param>
+/// <param name="nYY">输出：年份后两位。</param>
+/// <param name="nMMDD">输出：编码月日。</param>
+/// <param name="nId">输出：提交序号。</param>
+/// <param name="pOutDate">可选输出：Tag 提交日期。</param>
+/// <returns>成功返回 TRUE。</returns>
+BOOL ResolveTagFileVersionDateAndCommitCount(LPCTSTR lpRepoPath, const CString& strBranch, const CString& strTag, UINT& nYY, UINT& nMMDD, UINT& nId, SYSTEMTIME* pOutDate)
+{
+	nYY = 0;
+	nMMDD = 0;
+	nId = 0;
+
+	if (strTag.IsEmpty())
+	{
+		_tprintf(_T("错误: 标签名称为空\n"));
+		return FALSE;
+	}
+
+	SYSTEMTIME stTargetDate = { 0 };
+	if (!TryGetTagCommitDate(lpRepoPath, strTag, stTargetDate))
+	{
+		_tprintf(_T("错误: 获取标签 [%s] 对应提交日期失败\n"), strTag.GetString());
+		return FALSE;
+	}
+
+	UINT nCommitCount = 0;
+	if (!TryGetBranchCommitCountByDate(lpRepoPath, strBranch, stTargetDate, nCommitCount))
+	{
+		_tprintf(_T("错误: 获取 [%s] 在 [%04u-%02u-%02u] 的提交数量失败\n"),
+			strBranch.GetString(),
+			stTargetDate.wYear,
+			stTargetDate.wMonth,
+			stTargetDate.wDay);
+		return FALSE;
+	}
+
+	_tprintf(_T("获取标签提交信息成功: %04u-%02u-%02u, 提交数量: %u\n"),
+		stTargetDate.wYear,
+		stTargetDate.wMonth,
+		stTargetDate.wDay,
+		nCommitCount);
+
+	GetFileVersionDateFromSystemTime(stTargetDate, nYY, nMMDD);
+	nId = nCommitCount;
+	if (pOutDate != NULL)
+	{
+		*pOutDate = stTargetDate;
+	}
+	return TRUE;
+}
+
+/// <summary>
+/// 基于当前日期（或最近提交日）解析 FileVersion 的 yy、mmdd 与 id。
+/// 当天提交数为 0 时回退到最近一次提交日期。
+/// </summary>
+/// <param name="lpRepoPath">仓库根目录。</param>
+/// <param name="strBranch">分支名称。</param>
+/// <param name="nYY">输出：年份后两位。</param>
+/// <param name="nMMDD">输出：编码月日。</param>
+/// <param name="nId">输出：提交序号。</param>
+/// <param name="pOutDate">可选输出：采用的日期。</param>
+/// <returns>成功返回 TRUE。</returns>
+BOOL ResolveFileVersionDateAndCommitCount(LPCTSTR lpRepoPath, const CString& strBranch, UINT& nYY, UINT& nMMDD, UINT& nId, SYSTEMTIME* pOutDate)
 {
 	nYY = 0;
 	nMMDD = 0;
@@ -251,9 +498,73 @@ BOOL ResolveFileVersionDateAndCommitCount(LPCTSTR lpRepoPath, const CString& str

 	GetFileVersionDateFromSystemTime(stTargetDate, nYY, nMMDD);
 	nId = nTodayCommitCount;
+	if (pOutDate != NULL)
+	{
+		*pOutDate = stTargetDate;
+	}
 	return TRUE;
 }

+/// <summary>
+/// 获取指定日期内 origin/分支 的提交摘要列表（UTF-8 输出，一行一条）。
+/// </summary>
+/// <param name="lpRepoPath">仓库根目录。</param>
+/// <param name="strBranch">分支名称。</param>
+/// <param name="stDate">目标日期。</param>
+/// <param name="strLog">输出：提交摘要，多行以换行分隔。</param>
+/// <returns>成功返回 TRUE。</returns>
+BOOL TryGetGitLogByBranchDate(LPCTSTR lpRepoPath, const CString& strBranch, const SYSTEMTIME& stDate, CString& strLog)
+{
+	strLog.Empty();
+	if (strBranch.IsEmpty())
+	{
+		return FALSE;
+	}
+
+	CString strCmd;
+	strCmd.Format(
+		_T("cmd /c git log --reverse --pretty=format:%%s --since=\"%04u-%02u-%02u 00:00:00\" --until=\"%04u-%02u-%02u 23:59:59\" \"origin/%s\""),
+		stDate.wYear,
+		stDate.wMonth,
+		stDate.wDay,
+		stDate.wYear,
+		stDate.wMonth,
+		stDate.wDay,
+		strBranch.GetString());
+
+	CString strOutput = StartProcess(NULL, strCmd.GetBuffer(), lpRepoPath, CP_UTF8);
+	strCmd.ReleaseBuffer();
+	if (strOutput.IsEmpty())
+	{
+		return FALSE;
+	}
+
+	strOutput.Replace(_T("\r"), _T(""));
+	strOutput.Trim();
+	if (strOutput.IsEmpty() || strOutput.Left(6).CompareNoCase(_T("fatal:")) == 0)
+	{
+		return FALSE;
+	}
+
+	strLog = strOutput;
+	return TRUE;
+}
+
+/// <summary>
+/// 从 Git 仓库信息构建 ProductVersion 与 FileVersion 字符串。
+/// 正常分支：ProductVersion = pid.bid.major.minor，FileVersion = pid.yy.mmdd.id。
+/// HEAD 游离时改用远程分支与 Tag 解析。
+/// </summary>
+/// <param name="lpRepoPath">仓库根目录。</param>
+/// <param name="nPid">产品 ID。</param>
+/// <param name="errorCodes">各步骤失败时的退出码映射。</param>
+/// <param name="strProductVersion">输出：产品版本号。</param>
+/// <param name="strFileVersion">输出：文件版本号。</param>
+/// <param name="nDefaultMajor">无 Tag 时的默认 major。</param>
+/// <param name="nDefaultMinor">无 Tag 时的默认 minor。</param>
+/// <param name="pOutBranch">可选输出：使用的分支名。</param>
+/// <param name="pOutFileVersionDate">可选输出：FileVersion 采用的日期。</param>
+/// <returns>0 成功，否则返回 errorCodes 中对应错误码。</returns>
 int BuildVersionsFromRepo(
 	LPCTSTR lpRepoPath,
 	UINT nPid,
@@ -261,7 +572,9 @@ int BuildVersionsFromRepo(
 	CString& strProductVersion,
 	CString& strFileVersion,
 	UINT nDefaultMajor,
-	UINT nDefaultMinor)
+	UINT nDefaultMinor,
+	CString* pOutBranch,
+	SYSTEMTIME* pOutFileVersionDate)
 {
 	_tprintf(_T("开始构建版本: 仓库路径=%s pid=%u 默认Tag(%u.%u)\n"),
 		lpRepoPath == NULL ? _T("<null>") : lpRepoPath,
@@ -270,47 +583,90 @@ int BuildVersionsFromRepo(
 		nDefaultMinor);

 	UINT nBid = 0;
+	CString strStatus;
 	CString strBranch;
-	if (!TryGetCurrentBranch(lpRepoPath, strBranch))
+	UINT nMajor = 0, nMinor = 0;
+	UINT nYY = 0, nMMDD = 0, nId = 0;
+	if (!TryGetGitStatus(lpRepoPath, strStatus))
 	{
-		_tprintf(_T("错误: 获取当前分支失败\n"));
-		return errorCodes.nBidErrorCode;
-	}
-	_tprintf(_T("当前分支: %s\n"), strBranch.GetString());
+		_tprintf(_T("警告: 当前处于 HEAD 游离状态\n"));
+		if (!TryGetDetectedBranch(lpRepoPath, strBranch))
+		{
+			_tprintf(_T("错误: 获取远程分支失败\n"));
+			return errorCodes.nStatusErrorCode;
+		}

-	if (!TryGetBidFromBranch(strBranch, nBid))
-	{
-		_tprintf(_T("错误: 获取分支 bid 失败\n"));
-		return errorCodes.nBidErrorCode;
-	}
-	_tprintf(_T("分支 bid: %u\n"), nBid);
+		CString strTag;
+		if (!TryGetDetectedTag(lpRepoPath, strTag))
+		{
+			_tprintf(_T("错误: 获取远程分支标签失败\n"));
+			return errorCodes.nStatusErrorCode;
+		}

-	CString strLastTag;
-	UINT nMajor = 0;
-	UINT nMinor = 0;
-	if (!GetLastMajorMinorTag(lpRepoPath, strBranch, strLastTag, nMajor, nMinor))
-	{
-		nMajor = nDefaultMajor;
-		nMinor = nDefaultMinor;
-		_tprintf(_T("使用默认标签 %u %u\n"), nMajor, nMinor);
+		// 处于游离状态，使用远程分支和标签来解析版本号;
+		if (TryParseTagMajorMinor(strBranch, strTag, nMajor, nMinor))
+		{
+			_tprintf(_T("游离标签版本: %s (major=%u minor=%u)\n"), strTag.GetString(), nMajor, nMinor);
+		}
+
+		if (!ResolveTagFileVersionDateAndCommitCount(lpRepoPath, strBranch, strTag, nYY, nMMDD, nId, pOutFileVersionDate))
+		{
+			_tprintf(_T("错误: 获取游离标签提交信息失败\n"));
+			return errorCodes.nCommitErrorCode;
+		}
+
+		if (pOutBranch != NULL)
+		{
+			*pOutBranch = strBranch;
+		}
+
+		_tprintf(_T("游离标签提交信息: yy=%u mmdd=%u id=%u\n"), nYY, nMMDD, nId);
 	}
 	else
 	{
-		_tprintf(_T("最近标签: %s (major=%u minor=%u)\n"), strLastTag.GetString(), nMajor, nMinor);
-	}
+		if (!TryGetCurrentBranch(lpRepoPath, strBranch))
+		{
+			_tprintf(_T("错误: 获取当前分支失败\n"));
+			return errorCodes.nBidErrorCode;
+		}
+		_tprintf(_T("当前分支: %s\n"), strBranch.GetString());

-	UINT nYY = 0;
-	UINT nMMDD = 0;
-	UINT nId = 0;
-	if (!ResolveFileVersionDateAndCommitCount(lpRepoPath, strBranch, nYY, nMMDD, nId))
-	{
-		_tprintf(_T("错误: 获取分支提交信息失败\n"));
-		return errorCodes.nCommitErrorCode;
+		if (!TryGetBidFromBranch(strBranch, nBid))
+		{
+			_tprintf(_T("错误: 获取分支 bid 失败\n"));
+			return errorCodes.nBidErrorCode;
+		}
+		_tprintf(_T("分支 bid: %u\n"), nBid);
+
+		CString strLastTag;
+		if (!GetLastMajorMinorTag(lpRepoPath, strBranch, strLastTag, nMajor, nMinor))
+		{
+			nMajor = nDefaultMajor;
+			nMinor = nDefaultMinor;
+			_tprintf(_T("使用默认标签 %u %u\n"), nMajor, nMinor);
+		}
+		else
+		{
+			_tprintf(_T("最近标签: %s (major=%u minor=%u)\n"), strLastTag.GetString(), nMajor, nMinor);
+		}
+
+		if (!ResolveFileVersionDateAndCommitCount(lpRepoPath, strBranch, nYY, nMMDD, nId, pOutFileVersionDate))
+		{
+			_tprintf(_T("错误: 获取分支提交信息失败\n"));
+			return errorCodes.nCommitErrorCode;
+		}
+
+		if (pOutBranch != NULL)
+		{
+			*pOutBranch = strBranch;
+		}
+
+		_tprintf(_T("分支提交信息: yy=%u mmdd=%u id=%u\n"), nYY, nMMDD, nId);
 	}
-	_tprintf(_T("分支提交信息: yy=%u mmdd=%u id=%u\n"), nYY, nMMDD, nId);

 	strProductVersion.Format(_T("%u.%u.%u.%u"), nPid, nBid, nMajor, nMinor);
 	strFileVersion.Format(_T("%u.%u.%u.%u"), nPid, nYY, nMMDD, nId);
 	_tprintf(_T("文件版本信息: ProductVersion=%s FileVersion=%s\n"), strProductVersion.GetString(), strFileVersion.GetString());
+
 	return 0;
 }
--- a/GitVer/GitVer_version.h
+++ b/GitVer/GitVer_version.h
@@ -1,16 +1,86 @@
 #pragma once

+/// <summary>
+/// BuildVersionsFromRepo 各步骤失败时使用的退出码映射。
+/// </summary>
 struct VersionBuildErrorCodes
 {
 	int nBidErrorCode;
 	int nTagErrorCode;
 	int nCommitErrorCode;
+	int nStatusErrorCode;
 };

+/// <summary>
+/// 检测 Git 仓库是否处于正常分支状态（非 HEAD 游离）。
+/// </summary>
+BOOL TryGetGitStatus(LPCTSTR lpRepoPath, CString& strStatus);
+
+/// <summary>
+/// 获取当前检出的本地分支名称。
+/// </summary>
 BOOL TryGetCurrentBranch(LPCTSTR lpRepoPath, CString& strBranch);
+
+/// <summary>
+/// 在 HEAD 游离时推断当前所属远程分支名。
+/// </summary>
+BOOL TryGetDetectedBranch(LPCTSTR lpRepoPath, CString& strBranch);
+
+/// <summary>
+/// 获取指向当前 HEAD 的 Tag 名称。
+/// </summary>
+BOOL TryGetDetectedTag(LPCTSTR lpRepoPath, CString& strTag);
+
+/// <summary>
+/// 从分支名解析 bid（分支 ID）。
+/// </summary>
 BOOL TryGetBidFromBranch(const CString& strBranch, UINT& nBid);
+
+/// <summary>
+/// 解析符合「分支名.major.minor」格式的 Tag。
+/// </summary>
 BOOL TryParseTagMajorMinor(const CString& strBranch, const CString& strTag, UINT& nMajor, UINT& nMinor);
+
+/// <summary>
+/// 获取当前分支下版本号最大的 major.minor Tag。
+/// </summary>
 BOOL GetLastMajorMinorTag(LPCTSTR lpRepoPath, const CString& strBranch, CString& strTag, UINT& nMajor, UINT& nMinor);
+
+/// <summary>
+/// 基于 Tag 提交日期解析 FileVersion 的 yy、mmdd 与 id。
+/// </summary>
+BOOL ResolveTagFileVersionDateAndCommitCount(
+	LPCTSTR lpRepoPath,
+	const CString& strBranch,
+	const CString& strTag,
+	UINT& nYY,
+	UINT& nMMDD,
+	UINT& nId,
+	SYSTEMTIME* pOutDate = NULL);
+
+/// <summary>
+/// 基于当前或最近提交日解析 FileVersion 的 yy、mmdd 与 id。
+/// </summary>
+BOOL ResolveFileVersionDateAndCommitCount(
+	LPCTSTR lpRepoPath,
+	const CString& strBranch,
+	UINT& nYY,
+	UINT& nMMDD,
+	UINT& nId,
+	SYSTEMTIME* pOutDate = NULL);
+
+/// <summary>
+/// 获取指定日期内 origin/分支 的提交摘要列表。
+/// </summary>
+BOOL TryGetGitLogByBranchDate(
+	LPCTSTR lpRepoPath,
+	const CString& strBranch,
+	const SYSTEMTIME& stDate,
+	CString& strLog);
+
+/// <summary>
+/// 从 Git 仓库信息构建 ProductVersion 与 FileVersion 字符串。
+/// </summary>
 int BuildVersionsFromRepo(
 	LPCTSTR lpRepoPath,
 	UINT nPid,
@@ -18,4 +88,6 @@ int BuildVersionsFromRepo(
 	CString& strProductVersion,
 	CString& strFileVersion,
 	UINT nDefaultMajor,
-	UINT nDefaultMinor);
+	UINT nDefaultMinor,
+	CString* pOutBranch = NULL,
+	SYSTEMTIME* pOutFileVersionDate = NULL);
--- a/GitVer/framework.h
+++ b/GitVer/framework.h
@@ -1,23 +1,23 @@
-#pragma once
+#pragma once

 #include "targetver.h"
 #include <stdio.h>
 #include <tchar.h>
-#define _ATL_CSTRING_EXPLICIT_CONSTRUCTORS      // 部分 CString 构造函数将是显式的
-#define _AFX_NO_MFC_CONTROLS_IN_DIALOGS         // 移除对话框中的 MFC 控件支持
+#define _ATL_CSTRING_EXPLICIT_CONSTRUCTORS      // 部分 CString 构造函数将是显式的
+#define _AFX_NO_MFC_CONTROLS_IN_DIALOGS         // 移除对话框中的 MFC 控件支持

 #ifndef VC_EXTRALEAN
-#define VC_EXTRALEAN            // 从 Windows 头文件中排除极少使用的内容
+#define VC_EXTRALEAN            // 从 Windows 头文件中排除极少使用的内容
 #endif

 #include <afx.h>
-#include <afxwin.h>         // MFC 核心组件和标准组件
-#include <afxext.h>         // MFC 扩展
+#include <afxwin.h>         // MFC 核心组件和标准组件
+#include <afxext.h>         // MFC 扩展
 #ifndef _AFX_NO_OLE_SUPPORT
-#include <afxdtctl.h>           // MFC 对 Internet Explorer 4 公共控件的支持
+#include <afxdtctl.h>           // MFC 对 Internet Explorer 4 公共控件的支持
 #endif
 #ifndef _AFX_NO_AFXCMN_SUPPORT
-#include <afxcmn.h>                     // MFC 对 Windows 公共控件的支持
+#include <afxcmn.h>                     // MFC 对 Windows 公共控件的支持
 #endif // _AFX_NO_AFXCMN_SUPPORT

 #include <iostream>
--- a/GitVer/httplib.h
+++ b/GitVer/httplib.h
--- a/GitVer/pch.cpp
+++ b/GitVer/pch.cpp
@@ -1,5 +1,5 @@
-// pch.cpp: 与预编译标头对应的源文件
+// pch.cpp: 与预编译标头对应的源文件

 #include "pch.h"

-// 当使用预编译的头时，需要使用此源文件，编译才能成功。
+// 当使用预编译的头时，需要使用此源文件，编译才能成功。
--- a/GitVer/pch.h
+++ b/GitVer/pch.h
@@ -1,13 +1,13 @@
-// pch.h: 这是预编译标头文件。
-// 下方列出的文件仅编译一次，提高了将来生成的生成性能。
-// 这还将影响 IntelliSense 性能，包括代码完成和许多代码浏览功能。
-// 但是，如果此处列出的文件中的任何一个在生成之间有更新，它们全部都将被重新编译。
-// 请勿在此处添加要频繁更新的文件，这将使得性能优势无效。
+// pch.h: 这是预编译标头文件。
+// 下方列出的文件仅编译一次，提高了将来生成的生成性能。
+// 这还将影响 IntelliSense 性能，包括代码完成和许多代码浏览功能。
+// 但是，如果此处列出的文件中的任何一个在生成之间有更新，它们全部都将被重新编译。
+// 请勿在此处添加要频繁更新的文件，这将使得性能优势无效。

 #ifndef PCH_H
 #define PCH_H

-// 添加要在此处预编译的标头
+// 添加要在此处预编译的标头
 #include "framework.h"

 #endif //PCH_H
--- a/GitVer/resource.h
+++ b/GitVer/resource.h
@@ -1,6 +1,6 @@
-//{{NO_DEPENDENCIES}}
-// Microsoft Visual C++ 生成的包含文件。
-// 供 GitVer.rc 使用
+//{{NO_DEPENDENCIES}}
+// Microsoft Visual C++ 生成的包含文件。
+// 供 GitVer.rc 使用
 //
 #define IDI_ICON_APP                    100
 #define IDI_ICON1                       101
--- a/GitVer/targetver.h
+++ b/GitVer/targetver.h
@@ -1,6 +1,6 @@
-#pragma once
+#pragma once

-// // 包含 SDKDDKVer.h 可定义可用的最高版本的 Windows 平台。
-// 如果希望为之前的 Windows 平台构建应用程序，在包含 SDKDDKVer.h 之前请先包含 WinSDKVer.h 并
-// 将 _WIN32_WINNT 宏设置为想要支持的平台。
+// // 包含 SDKDDKVer.h 可定义可用的最高版本的 Windows 平台。
+// 如果希望为之前的 Windows 平台构建应用程序，在包含 SDKDDKVer.h 之前请先包含 WinSDKVer.h 并
+// 将 _WIN32_WINNT 宏设置为想要支持的平台。
 #include <SDKDDKVer.h>
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
 # GitVer

 命令行版本管理工具，从 Git 仓库读取 tag 自动生成并回写版本号。
+必须安装Git for Windows，且安装目录默认在C盘：C:\Program Files\Git

 ---

@@ -14,6 +15,7 @@ gitver nuitkabuild=<pid> [repodir=<path>] [-test] [params="<mainPy> <nuitka参
 gitver nuitkapydbuild=<pid> [repodir=<path>] [-test] [params="<modulePy> <nuitka参数>"]
 gitver pyinstaller=<pid> [repodir=<path>] [-test] [params="<mainPy|specFile> <pyinstaller参数>"]
 gitver setup=n [pid=m] [repodir=<path>] [-test]
+gitver upload username=<用户名> [file=<上传文件>] [info=<配置.txt>] [url=<PMC基址>]
 ```

 **通用参数说明：**
@@ -115,8 +117,21 @@ gitver setver=5 -test
 ```
 ProductVersion=5.0.1920.11
 FileVersion=5.26.0519.3
+已更新 upload_info.txt: E:\Code\MyProj\upload_info.txt
 ```

+**upload_info.txt 自动更新：**
+
+`setver` 成功生成版本号后，会在仓库目录（`repodir`，缺省为当前目录）写入或更新 `upload_info.txt`：
+
+| 字段 | 来源 |
+|---|---|
+| `product_version` | 本次生成的 ProductVersion |
+| `file_version` | 本次生成的 FileVersion |
+| `file_change_log` | 文件版本对应日期的 git 提交说明（`origin/<分支>` 当天 log，多条以换行分隔） |
+
+`setup` 成功编译安装包后，还会写入 `file`（安装包路径）。文件中已有的其他字段（如 `package_name`、`package_type_id`、`url` 等）会保留不变。
+
 **回写说明：**

 - **C++**：回写 `.rc` 文件中的 FILEVERSION、PRODUCTVERSION 及对应字符串字段
@@ -264,6 +279,84 @@ gitver setup=0 pid=5
 gitver setup=1 pid=5 repodir=E:\Code\MyProj
 ```

+**upload_info.txt 自动更新：**
+
+`setup` 编译成功后，会在仓库目录（`repodir`，缺省为当前目录）写入或更新 `upload_info.txt` 的 `file` 字段（安装包完整路径）。路径从 ISCC/NSIS 编译输出中解析；若无法解析，则尝试脚本目录下 `Output\*.exe` 或脚本目录内最新 `.exe`。
+
+**输出示例：**
+
+```
+安装包路径: E:\Code\MyProj\Output\MyApp_Setup_5.26.0624.3.exe
+已更新 upload_info.txt: E:\Code\MyProj\upload_info.txt
+```
+
+---
+
+### `gitver upload`（上传包到 PMC）
+
+将构建产物上传到 PMC 包管理中心。需 PMC 服务已运行，且账号具有管理员权限。
+
+```
+gitver upload username=<用户名> [file=<上传文件>] [info=<配置.txt>] [url=<PMC基址>]
+gitver upload username=<用户名>                         # 需在分支上且 HEAD 指向 Tag
+gitver upload username=<用户名> -f                      # 游离 HEAD 指向 Tag 时强制上传
+gitver upload -f username=<用户名> [file=<上传文件>]     # -f 位置任意
+```
+
+| 参数 | 说明 |
+|---|---|
+| `username=` | PMC 登录账号（必填）；登录密码从**同名环境变量**读取，如 `username=admin` 读取 `%admin%` |
+| `file=` | 可选，要上传的包文件路径；省略时从 info 文件的 `file` 字段读取（通常由 `setup` 写入） |
+| `info=` | 可选，上传配置信息文件路径，默认 `upload_info.txt`（见下方格式） |
+| `url=` | 可选，PMC 服务基址，默认 `http://127.0.0.1:8000` |
+
+**info 配置文件格式**（UTF-8 或 ANSI，每行 `key=value`，`#` 开头为注释）：
+
+```ini
+url=http://127.0.0.1:8000
+
+package_name=daily-report
+package_type_id=1
+file=E:\dist\MyApp_Setup_5.26.0624.3.exe
+product_version=5.0.1920.11
+file_version=5.26.0624.3
+file_change_log=修复导出 bug
+description=日报工具
+wiki_url=https://example.com/wiki
+product_change_log=首次发布
+```
+
+| info 字段 | 必填 | 说明 |
+|---|---|---|
+| `package_name` | 是 | 包名称 |
+| `package_type_id` | 是 | 包类型 ID（整数） |
+| `file` | 否* | 安装包路径；`upload` 省略 `file=` 时必填，通常由 `setup` 自动写入 |
+| `product_version` | 是 | 产品版本号 |
+| `file_version` | 是 | 文件版本号 |
+| `file_change_log` | 是 | 文件版本更新说明 |
+| `description` | 否 | 包描述 |
+| `wiki_url` | 否 | Wiki 链接 |
+| `product_change_log` | 否 | 产品版本更新说明 |
+| `url` | 否 | PMC 基址，默认 `http://127.0.0.1:8000` |
+
+上传流程：先 `POST /auth/login` 获取 Session，再 `POST /admin/packages/upload`（multipart/form-data），最后通过 `/api/packages/latest` 验证版本是否写入。
+
+HTTP 实现基于 [cpp-httplib](https://github.com/yhirose/cpp-httplib)（[`GitVer/httplib.h`](GitVer/httplib.h)），默认支持 `http://`；若需 `https://` 须另行启用 OpenSSL 支持。
+
+**示例：**
+
+```powershell
+# 先设置与 username 同名的环境变量作为登录密码
+$env:admin = "your_admin_password"
+```
+
+```
+gitver upload username=admin
+gitver upload username=admin info=E:\upload_info.txt
+gitver upload username=admin file=E:\dist\app.zip info=E:\upload_info.txt
+gitver upload username=admin url=http://192.168.1.10:8000
+```
+
 ---

 ## Nuitka 与 PyInstaller 常用参数速查
@@ -504,6 +597,13 @@ VSVersionInfo(
 | 44 | `pyinstaller=` 获取当天分支提交次数失败 |
 | 45 | `pyinstaller=` 版本信息文件无法生成或更新 |
 | 46 | `pyinstaller=` spec 文件无法注入或修改版本信息 |
+| 47 | `upload` 缺少必填参数（username），或 file 未指定且 info 中无 file 字段 |
+| 48 | `upload` 上传文件不存在 |
+| 49 | `upload` info 文件无效、缺少必填字段，或未设置与 username 同名的环境变量 |
+| 50 | `upload` PMC 登录失败 |
+| 51 | `upload` HTTP 上传请求失败 |
+| 52 | `upload` 上传后未找到对应版本（校验失败或版本冲突） |
+| 53 | `upload` 网络/HTTP 错误 |

 ---

@@ -591,6 +691,16 @@ gitver setup=0 pid=5
 # 预期: 使用 pid=5 生成版本号，修改 setup.iss 并调用 ISCC.exe 编译
 ```

+### 验证 upload
+
+```powershell
+# 前提：PMC 运行于 http://127.0.0.1:8000，且已有 admin 账号
+$env:admin = "your_admin_password"
+# 准备 upload_info.txt（含 package_name、file 等字段，不含 password）
+gitver upload username=admin
+# 预期: 读取当前目录 upload_info.txt，返回码 0，PMC 管理页可见新版本
+```
+
 ---

 ## 回归清单
@@ -657,6 +767,17 @@ gitver setup=0 pid=5
 | `gitver setup=9` | 36 |
 | `gitver setup=0 pid=abc` | 4 |

+### upload 组
+
+| 命令 | 预期返回码 |
+|---|---|
+| `gitver upload username=admin` | 0 / 47 / 48 / 49 / 50 / 52 / 53 |
+| `gitver upload username=admin info=E:\upload_info.txt` | 0 / 50 / 52 / 53 |
+| `gitver upload username=admin file=E:\dist\app.zip info=E:\upload_info.txt` | 0 / 50 / 52 / 53 |
+| `gitver upload username=admin file=E:\NotExists info=E:\upload_info.txt` | 48 |
+| `gitver upload username=admin info=E:\NotExists` | 49 |
+| `gitver upload` | 47 |
+
 > **注意**：如果打包时提示“未找到安装编译器（ISCC.exe / makensis.exe）”，请手动下载安装对应工具，并将其可执行文件路径（如 `ISCC.exe` 或 `makensis.exe` 所在目录）添加到系统环境变量 `PATH`。常见下载地址：
 >
 > - Inno Setup: https://jrsoftware.org/isinfo.php
Author	SHA1	Message	Date
Jeff	0766d09e27	非强制上传模式下，要求HEAD游离且指向Tag	2026-06-29 14:44:06 +08:00
Jeff	6b0f602e57	1、加强注释 2、上传时，添加-f参数才会强制上传，否则需要根据当前Tag标签信息来判断是否需要上传。	2026-06-28 20:56:56 +08:00
Jeff	ec7b51873c	修复上传时，中文乱码的问题。	2026-06-28 20:16:16 +08:00
Jeff	685a2094f7	字符编码统一GBK	2026-06-28 19:32:57 +08:00
Jeff	04904c2919	1、新增上传命令行参数：upload 2、上传参数关联函数调整与优化	2026-06-26 17:16:44 +08:00
Jeff	46134343e3	变更版本号	2026-06-24 09:58:32 +08:00
Jeff	5679433f7c	1、修复TryGetDetectedBranch问题 2、修复TryGetBranchCommitCountByDate在游离状态下获取分支失败的问题，应当获取远程分支，如：origin/master 但当浅克隆仓库，本地从未拉取过 origin/master，需要先执行：git fetch origin/master 3、更新md文件	2026-06-24 09:24:27 +08:00
Jeff	71f99a55b4	添加对gitlab runner执行ci时游离分支的支持	2026-06-23 21:12:56 +08:00
Jeff	a1f4ebd45a	修复inno setup中脚本的版本修改失败问题。	2026-06-03 18:33:18 +08:00
Jeff	171fa4448d	返回release和dev分支bid值	2026-05-22 20:27:28 +08:00