---
name: package-source-sha1
description: 为 massive-cloud-v3 生成可复现的纯源码 ZIP 包、内容清单和 40 位 SHA-1。用户要求打包整个项目、交付源码包、排除点云/CAD/数据库/构建产物/密钥，或计算项目 ZIP 哈希时使用。
---

# 打包源码并计算 SHA-1

使用 `scripts/package_source.py`，不要临时拼装 `find`、`tar` 或 `zip` 命令。

## 工作流

1. 根据项目 `AGENTS.md` 查看开发服务器 `/home/lipan/massive-cloud-v3` 的实时工作树和 `git status`。
2. 先运行 `--dry-run` 检查纳入、排除数量和排除原因；发现异常大文件或新的数据格式时，先更新脚本规则。
3. 运行正式打包。脚本只从 `git ls-files --cached --others --exclude-standard` 取候选文件，因此包含已跟踪文件和未忽略的新文件，也包含尚未提交的实际代码改动。
4. 将 ZIP、`.sha1` 和 `.manifest.json` 一起交付。明确说明包是否包含未提交改动，并报告基线提交。
5. 用 `unzip -t` 验证 ZIP；再独立运行 `sha1sum` 或 `shasum -a 1`，确认与 `.sha1` 一致且为 40 位小写十六进制。

## 固定规则

- 保留源码、测试、SQL、配置模板、依赖清单/锁文件、容器配置、脚本和文档。
- 排除 Git 历史、被 `.gitignore` 忽略的内容、真实 `.env`、密钥、日志、缓存、依赖目录和构建产物。
- 排除点云、CAD/网格、数据库、表格结果、归档包、模型权重等非源码文件。
- 不要使用 `git archive`：它会遗漏工作区中尚未提交的实际代码。
- ZIP 使用固定时间戳、固定顺序和规范权限；相同文件内容应生成相同哈希。

## 命令

```bash
python3 scripts/package_source.py \
  --source /home/lipan/massive-cloud-v3 \
  --output /tmp/massive-cloud-v3-source.zip \
  --dry-run

python3 scripts/package_source.py \
  --source /home/lipan/massive-cloud-v3 \
  --output /tmp/massive-cloud-v3-source.zip
```

不要把产物写进被打包的源码目录；优先使用 `/tmp`，再复制到交付位置。