Improve installation and release hygiene

.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

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

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

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

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

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"