From 9ba2c846a30ffc00e18a290991cee55f50f02334 Mon Sep 17 00:00:00 2001
From: esowt <esowt@qq.com>
Date: Sun, 2 Aug 2026 23:06:56 +0800
Subject: [PATCH] Improve installation and release hygiene

---
 .github/workflows/container.yml              | 15 ++++++-----
 README.md                                    | 15 +++++++++++
 README.zh-CN.md                              | 12 +++++++++
 packaging/cli/README.txt                     |  9 +++++++
 scripts/cleanup-untagged-package-versions.sh | 27 ++++++++++++++++++++
 scripts/install.sh                           |  7 +++++
 6 files changed, 79 insertions(+), 6 deletions(-)
 create mode 100644 scripts/cleanup-untagged-package-versions.sh

diff --git a/.github/workflows/container.yml b/.github/workflows/container.yml
index 118aea3..bc14429 100644
--- a/.github/workflows/container.yml
+++ b/.github/workflows/container.yml
@@ -76,10 +76,13 @@ jobs:
       packages: write
 
     steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
       - name: Remove untagged package versions
-        uses: actions/delete-package-versions@v5
-        with:
-          package-name: doc7
-          package-type: container
-          min-versions-to-keep: 10
-          delete-only-untagged-versions: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PACKAGE_OWNER: magicrew
+          PACKAGE_NAME: doc7
+          PACKAGE_TYPE: container
+        run: bash scripts/cleanup-untagged-package-versions.sh
diff --git a/README.md b/README.md
index 7e14780..6bc7fd6 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,21 @@ Windows PowerShell:
 irm https://raw.githubusercontent.com/magicrew/doc7/main/scripts/install.ps1 | iex
 ```
 
+The installer is the recommended macOS path. It downloads a checksum-verified
+release and installs it under your user directory, so it does not require an
+administrator account or an Apple Developer ID. Directly opening a binary
+downloaded by a browser is different: macOS may attach a quarantine attribute
+to that file. If you choose the archive path, run the included command from
+Terminal after extracting it:
+
+```bash
+xattr -dr com.apple.quarantine <extracted-directory>
+```
+
+This removes the local download quarantine; it is not Apple signing or
+notarization. Official Developer ID signing and notarization require an Apple
+Developer Program account and are planned for a future signed release channel.
+
 Start LM Studio or Ollama, load a local vision model, and convert a file:
 
 ```bash
diff --git a/README.zh-CN.md b/README.zh-CN.md
index dc45bdc..d539176 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -32,6 +32,18 @@ Windows PowerShell：
 irm https://raw.githubusercontent.com/magicrew/doc7/main/scripts/install.ps1 | iex
 ```
 
+macOS 推荐使用上面的安装脚本。它会下载并校验发行包，然后安装到当前用户目录，
+不需要管理员权限，也不要求 Apple Developer ID。直接用浏览器下载并打开二进制文件
+是另一条路径：macOS 可能会给文件添加隔离属性。若选择直接下载压缩包，请在终端
+解压后执行发行包中对应的命令：
+
+```bash
+xattr -dr com.apple.quarantine <解压后的目录>
+```
+
+这只会移除当前下载文件的本地隔离属性，不等同于 Apple 签名或公证。正式的 Developer
+ID 签名和公证需要 Apple Developer Program 账号，后续可以为正式发行通道接入。
+
 启动 LM Studio 或 Ollama，加载一个本地视觉模型，然后直接转换文件：
 
 ```bash
diff --git a/packaging/cli/README.txt b/packaging/cli/README.txt
index 3673070..0e2e654 100644
--- a/packaging/cli/README.txt
+++ b/packaging/cli/README.txt
@@ -8,6 +8,15 @@ Turn any document into AI-ready Markdown.
 3. Run: doc7 setup
 4. Convert: doc7 <file>
 
+macOS note:
+  The curl installer is the recommended path because it verifies the release and installs
+  under the current user. If you downloaded and extracted this archive in a browser and
+  macOS blocks the executable, run this from Terminal after extraction:
+
+  xattr -dr com.apple.quarantine <extracted-directory>
+
+  This clears the local browser quarantine. It is not a Developer ID signature or notarization.
+
 Examples:
   doc7 report.pdf
   doc7 screenshot.png
diff --git a/scripts/cleanup-untagged-package-versions.sh b/scripts/cleanup-untagged-package-versions.sh
new file mode 100644
index 0000000..6bd38b9
--- /dev/null
+++ b/scripts/cleanup-untagged-package-versions.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+: "${GH_TOKEN:?GH_TOKEN is required}"
+
+owner="${PACKAGE_OWNER:-magicrew}"
+package_name="${PACKAGE_NAME:-doc7}"
+package_type="${PACKAGE_TYPE:-container}"
+
+command -v gh >/dev/null 2>&1 || {
+  printf 'gh is required\n' >&2
+  exit 1
+}
+command -v jq >/dev/null 2>&1 || {
+  printf 'jq is required\n' >&2
+  exit 1
+}
+
+gh api --paginate \
+  "/orgs/${owner}/packages/${package_type}/${package_name}/versions?per_page=100" \
+  --jq '.[] | select((.metadata.container.tags // []) | length == 0) | .id' |
+while IFS= read -r version_id; do
+  [[ -n "${version_id}" ]] || continue
+  gh api --method DELETE \
+    "/orgs/${owner}/packages/${package_type}/${package_name}/versions/${version_id}"
+done
diff --git a/scripts/install.sh b/scripts/install.sh
index 4b98a80..78013c0 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -73,6 +73,12 @@ verify_checksum() {
   [[ "${actual}" == "${expected}" ]] || fail "checksum verification failed"
 }
 
+clear_macos_quarantine() {
+  [[ "${OS}" == "darwin" ]] || return 0
+  command -v xattr >/dev/null 2>&1 || return 0
+  xattr -dr com.apple.quarantine "${TEMP_DIR}" 2>/dev/null || true
+}
+
 require_command curl
 require_command tar
 require_command awk
@@ -116,6 +122,7 @@ curl --fail --silent --show-error --location \
 
 verify_checksum
 tar -xzf "${ARCHIVE_PATH}" -C "${TEMP_DIR}"
+clear_macos_quarantine
 
 BINARY_PATH="${TEMP_DIR}/${PACKAGE_NAME}/doc7"
 LICENSE_PATH="${TEMP_DIR}/${PACKAGE_NAME}/LICENSE"