chore(release): 1.0.2b7

.cursor/skills/publish/SKILL.md

@@ -23,7 +23,7 @@ disable-model-invocation: true
 | `CHANGELOG_FILE` | `CHANGELOG.md` | 相对于仓库根目录的路径，文件不存在则跳过 |
 | `VERSION_FILE` | `pyproject.toml` | 包含版本号的文件 |
 | `VERSION_PATTERN` | `^\s*version\s*=\s*"[^"]+"` | 匹配版本行的正则表达式 |
-| `README_FILE` | `README.md` | 含 shields.io 版本徽标的文件（badge 版本号同步升级） |
+| `README_GLOB` | `README*.md` | 含 shields.io 版本徽标的 README（含多语言变体，如 `README.md`、`README_CN.md`）；全部同步升级 |
 | `INIT_VERSION_FILE` | `src/octop/__init__.py` | 含运行时常量 `__version__` 的文件（缺失则跳过并提示） |
 | `TAG_PREFIX` | `v` | Git tag 前缀；工作流监听 `v*`，生成 `v0.1.14` 风格标签 |
 | `REMOTE` | `origin` | Git 远程仓库名 |
@@ -175,27 +175,76 @@ git checkout -B {RELEASE_BRANCH_PREFIX}{version} {REMOTE}/{INTEGRATION_BRANCH}
 
 如果 `## [Unreleased]` 标题不存在，在 `# Changelog` 标题行之后插入新条目（若无标题则插入到文件顶部）。
 
-**4b. 升级版本号（同步所有版本来源）：**
+**4b. 升级版本号（把旧号 X.Y.Z 全部换成当前号 A.B.C）：**
 
-发布版本号必须保持多文件一致。依次升级以下位置：
+表示「当前发布版本」的钉死号必须一致，**不得只改 `pyproject.toml`**。
+把旧版本 `X.Y.Z` 换成目标版本 `A.B.C`。缺文件则提示并继续（不中止）。
+
+必改清单（按顺序，用 Edit 工具精确替换，勿用会误伤 CHANGELOG 历史条目的全局 replace）：
 
 1. `VERSION_FILE`（`pyproject.toml`）— wheel / PyPI 的唯一版本源：
    ```bash
    grep -n '^\s*version\s*=\s*"[^"]+"' pyproject.toml
-   # 用 Edit 工具将该行的 "X.Y.Z" 替换为 "A.B.C"
+   # "X.Y.Z" → "A.B.C"
    ```
-2. `README_FILE`（`README.md`）— shields.io 版本徽标：
+2. 所有匹配 `README_GLOB` 且含 shields.io 版本徽标的 README（含多语言）：
    ```bash
-   grep -n 'shields.io/badge/version-' README.md
-   # 用 Edit 工具将 `version-X.Y.Z-orange` 替换为 `version-A.B.C-orange`
+   grep -l 'shields.io/badge/version-' README.md README_*.md 2>/dev/null
+   grep -n 'shields.io/badge/version-' {file}
+   # `version-X.Y.Z-orange` → `version-A.B.C-orange`
    ```
-   文件不存在则跳过并提示（不中止）。
+   当前仓库至少包括 `README.md` 与 `README_CN.md`。全部未命中则提示并继续。
 3. `INIT_VERSION_FILE`（`src/octop/__init__.py`）— 运行时常量 `__version__`：
    ```bash
    grep -n '__version__' src/octop/__init__.py
-   # 用 Edit 工具将 `__version__ = "X.Y.Z"` 替换为 `"A.B.C"`
+   # `__version__ = "X.Y.Z"` → `"A.B.C"`
+   ```
+4. 飞牛 FnOS 两个 manifest 的 `version=`（`scripts/build-fpk.sh` 打包时会再注入，但仓库源文件必须先改）：
+   ```bash
+   grep -n '^version=' fnos/docker/manifest fnos/native/manifest
+   # `version=X.Y.Z` → `version=A.B.C`（两个文件都要改）
+   ```
+5. 飞牛 Docker compose 镜像标签（与本包版本相同，供 FPK 拉取 GHCR）：
+   ```bash
+   grep -n 'ghcr.io/tencentcloud/octop:' fnos/docker/app/docker/docker-compose.yaml
+   # `ghcr.io/tencentcloud/octop:X.Y.Z` → `:A.B.C`
+   # 不得改成 `:latest`（测试禁止 latest）
    ```
-   文件不存在则跳过并提示（不中止）。
+6. `uv.lock` 里可编辑包 `octop` 的版本（漏改会导致 lock 与 pyproject 不一致）：
+   ```bash
+   grep -n -A2 'name = "octop"' uv.lock | head -5
+   # 将该包的 `version = "X.Y.Z"` 改为 `"A.B.C"`
+   # 或在改完 pyproject.toml 后执行 `uv lock`，只接受 octop 版本行变化
+   ```
+
+**扫尾（必做）：** 全库搜索旧号，把漏网的「当前版本钉死」一并改掉：
+
+```bash
+git grep -n --fixed-strings "X.Y.Z"
+```
+
+对每一处命中：
+
+| 类型 | 处理 |
+|------|------|
+| 当前版本钉死（compose / badge / manifest / lock / `__version__` / 文档里「当前版本」） | 换成 `A.B.C` |
+| 测试里断言「等于当前发布号」的硬编码 | 改成读 `_pyproject_version()`（或同步为 `A.B.C`） |
+| `CHANGELOG.md` 已发布章节（`## [X.Y.Z]` 及正文） | **保留**，不要改历史 |
+| 测试夹具里拿旧号做比较（如 `1.0.2b4` vs `1.0.2b5`、解析示例） | **保留** |
+| workflow / 注释里的示例旧号（如 `0.9.28`） | **保留**（不是当前钉死） |
+
+提交前再扫必改清单，必须已经没有旧号：
+
+```bash
+git grep -n --fixed-strings "X.Y.Z" -- \
+  pyproject.toml src/octop/__init__.py \
+  README.md README_CN.md \
+  fnos/docker/manifest fnos/native/manifest \
+  fnos/docker/app/docker/docker-compose.yaml \
+  uv.lock
+```
+
+任一文件仍命中旧号：**补改后再提交**，不得带着半套版本号推 release。
 
 **4c. 提交：**
 
@@ -317,4 +366,6 @@ git checkout {original_branch}
 - 发版后删除 `release/*`；`main → develop` 由 `sync-main-to-develop.yml` 自动同步（失败时再手动补）
 - 中止前展示完整错误输出
 - 插入新版本条目后保持 `[Unreleased]` 为空
+- 把旧版本号 `X.Y.Z` 换成 `A.B.C`：`pyproject.toml`、`__version__`、多语言 README 徽标、`fnos/*/manifest`、`fnos/docker/app/docker/docker-compose.yaml` 镜像标签、`uv.lock` 的 octop 包版本；提交前 `git grep` 必改清单确认无旧号
+- 勿改 CHANGELOG 历史章节、测试夹具里的旧版本比较、workflow 示例号
 - 推送 tag 后提示用户关注 GitHub Actions 的发布结果

.env.example

@@ -13,9 +13,11 @@ OCTOP_BIND_HOST=0.0.0.0
 
 # Docker first-run bootstrap (only used when ~/.octop/octop.db is absent)
 # Password must be ≥8 chars with letters and digits (same policy as change-password).
-# Future: first boot may randomize this and write it to credential.txt instead.
+# Set a valid password to create the admin via `octop init`. Leave empty (or set a
+# password the policy rejects) to start the web setup wizard instead; the wizard
+# unlock password is written to ~/.octop/octop-login.txt.
 OCTOP_ADMIN_USERNAME=admin
-# First-run admin password; leave empty to auto-generate a random one (written to ~/.octop/credential.txt)
+# First-run admin password; empty / rejected → setup wizard (not a silent random admin)
 OCTOP_DEFAULT_PASSWORD=
 OCTOP_ADMIN_DISPLAY_NAME=Admin
 
@@ -37,7 +39,12 @@ OPENAI_API_KEY=
 DASHSCOPE_API_KEY=
 
 # Langfuse observability (optional)
-OCTOP_LANGFUSE_ENABLED=false
+# Octop's on/off switch is the admin setting in Dashboard → Settings →
+# Observability (stored as the settings key `observability_langfuse_enabled`);
+# there is no OCTOP_LANGFUSE_ENABLED variable. LANGFUSE_TRACING_ENABLED=false
+# is the SDK-level kill switch, honoured by the langfuse client along with the
+# public / secret key and base URL below.
+LANGFUSE_TRACING_ENABLED=true
 
 # Optional login captcha (boot snapshot; restart after changing).
 # Default slider is dashboard-only. Strong providers need both keys.

.github/workflows/docker-publish.yml

@@ -4,12 +4,19 @@ name: Docker Publish
 # 文档与对外引用统一使用：ghcr.io/tencentcloud/octop
 # （Hub 仍用 DOCKERHUB_* secrets 同步推送。）
 #
+# 架构：ubuntu-latest 打 linux/amd64，ubuntu-24.04-arm 打 linux/arm64，
+# 再合并为 :{version} / :latest 多架构清单。飞牛 Docker 版 FPK 共用一份，
+# NAS 按本机架构拉取对应镜像层。
+#
 # 触发路径：
 #   1. 人工推送 v* tag → on.push.tags
 #   2. Auto Tag 用 GITHUB_TOKEN 推 tag 后显式 workflow_dispatch（token push 不会触发 push 工作流）
+#   3. 在任意分支 Run workflow，填 tag=vX.Y.Z（用该分支的 workflow 文件，checkout 指定 tag）
 #
 # 注意：workflow_dispatch 下 metadata-action 的 type=semver 不可靠，
-# 必须从 GITHUB_REF_NAME 显式解析版本号。
+# 必须从 tag / 输入显式解析版本号。
+# 不要把 DOCKERHUB_USERNAME 放进 job outputs：跨 job 传递会被抹成空，
+# 导致只推 GHCR，合并清单时再对空 Hub 名失败。
 #
 # FnOS FPK 由 Release 成功后自动 dispatch，并等待本工作流推送的 :{version} 就绪。
 #
@@ -21,43 +28,84 @@ on:
     tags:
       - "v*"
   workflow_dispatch:
+    inputs:
+      tag:
+        description: "v* tag to publish (e.g. v1.0.2b6). Required when not running on a tag."
+        required: false
+        type: string
 
 permissions:
   contents: read
   packages: write
 
 jobs:
-  docker:
-    name: Build and push image
+  prepare:
+    name: Resolve version
     runs-on: ubuntu-latest
-    # 拒绝在非 v* ref 上误跑（例如 UI 里对 main 点 Run workflow）
-    if: startsWith(github.ref, 'refs/tags/v')
+    # 拒绝在非 v* ref 上误跑（例如 UI 里对 main 点 Run workflow 且未填 tag）
+    if: >-
+      startsWith(github.ref, 'refs/tags/v')
+      || (github.event_name == 'workflow_dispatch' && startsWith(inputs.tag, 'v'))
+    outputs:
+      version: ${{ steps.ver.outputs.version }}
+      tag: ${{ steps.ver.outputs.tag }}
+      ghcr: ${{ steps.image.outputs.ghcr }}
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
       - name: Resolve version from tag ref
         id: ver
+        env:
+          DISPATCH_TAG: ${{ inputs.tag }}
         run: |
           set -euo pipefail
-          ref="${GITHUB_REF_NAME}"
+          if [ -n "${DISPATCH_TAG:-}" ]; then
+            ref="$DISPATCH_TAG"
+          else
+            ref="${GITHUB_REF_NAME}"
+          fi
           case "$ref" in
             v*)
               echo "version=${ref#v}" >> "$GITHUB_OUTPUT"
               echo "tag=$ref" >> "$GITHUB_OUTPUT"
               ;;
             *)
-              echo "::error::Expected refs/tags/v*, got ref_name=$ref"
+              echo "::error::Expected v* tag, got ref=$ref"
               exit 1
               ;;
           esac
 
+      - name: Image names
+        id: image
+        run: |
+          echo "ghcr=ghcr.io/$(echo '${{ github.repository }}' | tr '[:upper:]' '[:lower:]')" >> "$GITHUB_OUTPUT"
+
+  build:
+    name: Build ${{ matrix.arch }}
+    needs: prepare
+    runs-on: ${{ matrix.runner }}
+    env:
+      DOCKERHUB_USER: ${{ secrets.DOCKERHUB_USERNAME }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: ubuntu-latest
+            platform: linux/amd64
+            arch: amd64
+          - runner: ubuntu-24.04-arm
+            platform: linux/arm64
+            arch: arm64
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.prepare.outputs.tag }}
+          fetch-depth: 0
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
       - name: Log in to Docker Hub
+        if: env.DOCKERHUB_USER != ''
         uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
@@ -70,32 +118,87 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Image names
-        id: image
-        run: |
-          echo "ghcr=ghcr.io/$(echo '${{ github.repository }}' | tr '[:upper:]' '[:lower:]')" >> "$GITHUB_OUTPUT"
-          echo "hub=${{ secrets.DOCKERHUB_USERNAME }}/octop" >> "$GITHUB_OUTPUT"
-
       - name: Docker metadata
         id: meta
         uses: docker/metadata-action@v5
         with:
           images: |
-            ${{ steps.image.outputs.hub }}
-            ${{ steps.image.outputs.ghcr }}
-          # 显式 raw tag：兼容 push.tags 与 Auto Tag 的 workflow_dispatch
+            ${{ env.DOCKERHUB_USER != '' && format('{0}/octop', env.DOCKERHUB_USER) || '' }}
+            ${{ needs.prepare.outputs.ghcr }}
+          # 单架构中间 tag；:{version} / :latest 由 merge 合成多架构清单
           tags: |
-            type=raw,value=${{ steps.ver.outputs.version }}
-            type=raw,value=latest
+            type=raw,value=${{ needs.prepare.outputs.version }}-${{ matrix.arch }}
 
       - name: Build and push
         uses: docker/build-push-action@v6
         with:
           context: .
           file: ./docker/Dockerfile
           push: true
-          platforms: linux/amd64
+          platforms: ${{ matrix.platform }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-from: type=gha,scope=docker-${{ matrix.arch }}
+          cache-to: type=gha,mode=max,scope=docker-${{ matrix.arch }}
+
+  merge:
+    name: Multi-arch manifest
+    needs: [prepare, build]
+    # ARM runner 偶发失败时仍发布已有架构，避免卡住 :{version} 与 Docker FPK。
+    if: always() && needs.prepare.result == 'success' && !cancelled()
+    runs-on: ubuntu-latest
+    env:
+      DOCKERHUB_USER: ${{ secrets.DOCKERHUB_USERNAME }}
+    steps:
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        if: env.DOCKERHUB_USER != ''
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create and push multi-arch manifests
+        env:
+          VER: ${{ needs.prepare.outputs.version }}
+          GHCR: ${{ needs.prepare.outputs.ghcr }}
+          HUB: ${{ env.DOCKERHUB_USER != '' && format('{0}/octop', env.DOCKERHUB_USER) || '' }}
+        run: |
+          set -euo pipefail
+          any_multi=0
+          for REG in "$GHCR" "$HUB"; do
+            [ -n "$REG" ] || continue
+            sources=()
+            for arch in amd64 arm64; do
+              if docker buildx imagetools inspect "${REG}:${VER}-${arch}" >/dev/null 2>&1; then
+                sources+=("${REG}:${VER}-${arch}")
+              else
+                echo "::warning::missing ${REG}:${VER}-${arch}"
+              fi
+            done
+            if [ "${#sources[@]}" -eq 0 ]; then
+              echo "::error::No platform images published for ${REG}:${VER}"
+              exit 1
+            fi
+            if [ "${#sources[@]}" -ge 2 ]; then
+              any_multi=1
+            fi
+            docker buildx imagetools create \
+              -t "${REG}:${VER}" \
+              -t "${REG}:latest" \
+              "${sources[@]}"
+            echo "=== ${REG}:${VER} ==="
+            docker buildx imagetools inspect "${REG}:${VER}"
+          done
+          if [ "$any_multi" -eq 0 ]; then
+            echo "::warning:::${VER} is not multi-arch (ARM image missing). Docker FPK on ARM NAS will not run."
+          fi