Skip to content

整理 README：與程式碼雙向對齊，更正三處不符的敘述 - #15

Merged
k66inthesky merged 2 commits into
mainfrom
claude/0g-tech-competition-deploy-lv08or
Sep 10, 2026
Merged

整理 README：與程式碼雙向對齊，更正三處不符的敘述#15
k66inthesky merged 2 commits into
mainfrom
claude/0g-tech-competition-deploy-lv08or

Conversation

@k66inthesky

@k66inthesky k66inthesky commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

.env.example

  • 補上 OG_PROXY_SECRET —— zg 代理拿它簽節點網址，程式碼讀得到但範例漏了。
  • 修正 OG_STORAGE_UPLOAD_URL 的說明。現在預設是玩家用自己的錢包上傳，那個 gateway 是「想讓玩家不用付儲存費」才要的選項，不是原本寫的「沒設就只產生摘要」。
  • 末尾註明 proxy/ 那台服務的變數設在它自己的專案上。
  • 一律留空值，不放任何真實金鑰。

雙向交叉檢查都乾淨：

=== 程式碼讀得到、但 .env.example 沒寫的變數 ===
=== .env.example 有、但程式碼不讀的變數 ===
（兩邊都沒輸出就是完全對齊）

README

章節 改了什麼
部署 新增「賽道二還需要一台 Node 代理」 —— 這步不做「存進 0G Storage」必定失敗，之前完全沒寫
部署 方式 B 補上 --branch main，並註明少了它會部署成 Preview、正式網址不會更新
環境變數 補 OG_ZG_PROXY_BASE（標成上傳必要）與 OG_PROXY_SECRET
檔案配置 補上 404.html、_headers、_routes.json、vendor/、public/js/storage.js、functions/api/og/zg/、proxy/、slides/
安全性 「0G Storage 的寫入交給外部 gateway」已不成立 → 改成全程走玩家錢包；新增一條說明節點代理為什麼不是開放代理

行號連結

14 個逐一驗證，5 個在這幾天的改動後跑掉了：

原本 改成 原本指到哪
public/js/storage.js#L65-L108 #L72-L116 upload() 中段
functions/api/og/storage.js#L76-L114 #L117-L159 unwrap / seqOf 兩個小工具
functions/api/og/status.js#L59-L150 #L59-L157 尾端被新欄位推移
public/js/og.js#L174-L199 #L235-L260 connect() 中段
public/js/og.js#L116-L159 #L167-L220 currentAccount

現在 14 個全部落在正確函式的起訖行上（起始行是 /** 或 export function，結束行是收尾的 }）。

順手更正 storage.js 裡一句過時註解：「刻意忽略呼叫端傳進來的真實 indexer 網址」—— 呼叫端現在傳的是 proxyBase，不是 indexer。

🤖 Generated with Claude Code

https://claude.ai/code/session_015NBxaWtzqEX3i8NvoZEeq3

Generated by Claude Code

@claude
整理 README，.env.example 與程式碼雙向對齊
4c96723 
.env.example
  補上 OG_PROXY_SECRET（zg 代理拿它簽節點網址，程式碼讀得到但範例沒寫）。
  OG_STORAGE_UPLOAD_URL 的說明過時了 —— 現在預設是玩家用自己的錢包上傳，
  那個 gateway 是「想讓玩家不用付儲存費」才要的選項，不是「沒設就只產生摘要」。
  末尾註明 proxy/ 那台服務的變數設在它自己的專案上，不在這裡。
  一律留空值，不放任何真實金鑰。

  雙向交叉檢查都乾淨：程式碼讀得到的 13 個變數範例裡都有，範例裡也沒有
  程式碼不讀的殘留變數。

README
  · 部署章節新增「賽道二還需要一台 Node 代理」—— 這步不做「存進 0G Storage」
    必定失敗，之前完全沒寫。附上兩行指令與原因（error 1003 / 521）。
  · 方式 B 的部署指令補上 --branch main，並註明少了它會部署成 Preview、
    正式網址不會更新（我們為此耗掉一整輪除錯）。
  · 環境變數表補 OG_ZG_PROXY_BASE（標成「上傳必要」）與 OG_PROXY_SECRET，
    修正 OG_STORAGE_UPLOAD_URL 的必要性描述。
  · 檔案配置補上這幾天新增的：404.html、_headers、_routes.json、vendor/、
    public/js/storage.js、functions/api/og/zg/、proxy/、slides/。
  · 安全性那條「0G Storage 的寫入交給外部 gateway」已經不成立 —— 改成寫入
    全程走玩家錢包，並新增一條說明節點代理為什麼不是開放代理（HMAC 簽章、
    內網過濾、不轉 cookie/authorization）。

行號連結
  14 個逐一驗證，5 個在這幾天的改動後跑掉了：
    public/js/storage.js#L65-L108      → #L72-L116（upload 整支）
    functions/api/og/storage.js#L76-L114 → #L117-L159（原本指到 unwrap/seqOf）
    functions/api/og/status.js#L59-L150  → #L59-L157
    public/js/og.js#L174-L199          → #L235-L260（原本指到 connect 中段）
    public/js/og.js#L116-L159          → #L167-L220（原本指到 currentAccount）
  現在 14 個全部落在正確函式的起訖行上。

順手更正 storage.js 裡一句過時註解：「刻意忽略呼叫端傳進來的真實 indexer 網址」
—— 呼叫端現在傳的是 proxyBase，不是 indexer。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015NBxaWtzqEX3i8NvoZEeq3
@claude
更正 README 三處與程式碼不符的敘述，CI 補上 --branch=main
84e5811 
逐段拿 README 對程式碼查了一次，三處對不上：

1. 「美術與音樂全部是程式現畫、現合成的 —— 沒有任何圖檔」
   現在 public/ 底下有 heroes.jpeg（915KB）、logo.svg、favicon.svg。音檔那半是
   對的（find 找不到任何 mp3/wav/ogg），圖檔那半已經不成立。改成照實說：音樂
   沒有音檔，美術除了三位主角的形象照之外都是 art.js 現畫的 inline SVG，
   抽掉形象照照樣能玩。

2. 形象照「單格比例約 454×787」
   實際那張是 1361×768，單格 453×768。787 不知道從哪來的，照著它做圖臉會被
   縱向拉伸 —— 這正是先前修過的那個 bug。順便寫清楚 CSS 的 aspect-ratio 是
   1361 / 2304（整張寬 ÷ 單格高×3），換圖要一起改。

3. 「實測 300 場：71% 落敗，平均 3.7 回合」
   重跑五輪：遺忘者勝 176 / 176 / 193 / 203 / 206，也就是落敗 59–69%，
   平均 3.7–3.8 回合。71% 復現不出來。模擬用隨機出牌，本來就會抖動，
   所以改成寫範圍而不是單一數字。

另外 .github/workflows/deploy.yml 的部署指令沒有 --branch=main。CI 裡 wrangler
會從 git 推斷分支，多半會落在 main，但 README 方式 B 才剛特別強調少了這個參數
會部署成 Preview、正式網址不會更新（我們為此耗掉一整輪）。既然要求別人加，
自己的 workflow 沒理由靠推斷。

查過但沒問題的：規則數字（LANES/TRACK=3、CORE_HP=12、MAX_TURNS=7、
COMPUTE_PER_TURN=2、CONTROL_DAMAGE=2）全部對得上 rules.js；三位角色的名字與
稱號對得上 story.js；npm run dev / sim / deploy 三個 script 都存在；
/api/og/verify 不帶 digest 也能用（digestMatch 回 null，不會報錯）；
sanitizePlays() 確實在 agent.js 裡。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015NBxaWtzqEX3i8NvoZEeq3
@k66inthesky k66inthesky changed the title 整理 README，.env.example 與程式碼雙向對齊 整理 README：與程式碼雙向對齊，更正三處不符的敘述 Sep 10, 2026
@k66inthesky
k66inthesky marked this pull request as ready for review September 10, 2026 07:41
Copilot AI lite review requested due to automatic review settings September 10, 2026 07:41
@k66inthesky
k66inthesky merged commit a72ea84 into main Sep 10, 2026
1 check passed
Copilot AI reviewed Sep 10, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

README 與 .env.example 對 OG_PROXY_SECRET 的描述會誤導部署者低估其保密性與濫用風險，需先修正文案以符合實際安全模型。

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

本 PR 主要針對部署與環境變數文件（README / .env.example）做「與程式碼雙向對齊」的整理，並補齊賽道二（0G Storage）在實務上需要 Node 代理服務的部署說明，同步更新多個 README 行號連結與敘述。

Changes:

  • 更新 README 的部署流程與檔案結構說明，補上賽道二 Node 代理（proxy）部署與 --branch main 注意事項。
  • 補齊 .env.example 的 OG_PROXY_SECRET，並更新 README 的賽道二環境變數表。
  • 修正 public/js/storage.js 內對「為何 indexer/節點必須走代理」的註解，使其反映現況。
File summaries
File Description
README.md 補強部署/環境變數/安全性/檔案配置說明，並更新多處程式碼行號連結
public/js/storage.js 更新註解以反映 proxyBase 與 mixed content/CORS 的實際限制
.github/workflows/deploy.yml Cloudflare Pages 部署指令補上 --branch=main
.env.example 補上 OG_PROXY_SECRET 與 proxy 專案變數的說明註記
Review details

Suppressed comments (2)

README.md:324

  • 這段寫「外人塞任意網址進來拿 403」只有在 OG_PROXY_SECRET 真正保密且有設定時才成立；目前預設會退回公開的內建常數，攻擊者可自行算簽章繞過這個敘述。建議在 README 明確要求 production 設定隨機 secret，避免誤判風險。
- **節點代理不是開放代理。** 節點是裸 IP，沒有網域可以白名單，所以改用 HMAC 簽章綁住：
  只有代理自己從 indexer 回應吐出來的網址才轉發得動，外人塞任意網址進來拿 403。
  另外擋掉內網 / link-local / 雲端 metadata 位址，也不把 `cookie`、`authorization`
  轉給第三方主機。

.env.example:52

  • 末尾註解說 proxy 的變數「不在這裡」但又把 OG_PROXY_SECRET 列進 proxy 清單，容易讓人誤以為主站不用設這個值；而實際上主站與 proxy 需要用同一個 OG_PROXY_SECRET 才能驗證簽章。建議把註解改成明確描述「proxy 端也要設、且需與主站相同」。
# ══ 代理服務（proxy/）的變數不在這裡 ═══════════════════════════
# 那是另一個部署（Vercel），變數設在它自己的專案上：
# OG_PROXY_SECRET / OG_STORAGE_INDEXER / ALLOWED_ORIGINS / PUBLIC_BASE_URL
# 說明見 proxy/README.md。
  • Files reviewed: 4/4 changed files
  • Comments generated: 3
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread .env.example
Comment on lines +36 to +38
# 代理用來簽節點網址的金鑰。擋的是「有人拿這個網域當跳板」，不是機密資料，
# 沒設會用內建常數。要更嚴的話這裡與 proxy 那台服務要設成同一個值。
OG_PROXY_SECRET=
Comment thread README.md
| `OG_STORAGE_INDEXER` | 賽道二 | 選用 | 預設 Turbo indexer；唯讀查詢不需金鑰 |
| `OG_STORAGE_UPLOAD_URL` | 賽道二 | 上傳才需要 | 指向 `0g-storage-client` gateway；沒設就只產生摘要 |
| `OG_ZG_PROXY_BASE` | 賽道二 | **上傳必要** | 節點代理的網址（結尾要有 `/api`）。沒設的話前端會走同源的 `/api/og/zg`，那條路在 Cloudflare 上必定失敗 —— 見上面「賽道二還需要一台 Node 代理」 |
| `OG_PROXY_SECRET` | 賽道二 | 選用 | 代理用來簽節點網址的金鑰。擋的是「有人拿這個網域當跳板」，不是機密資料；沒設會用內建常數。要更嚴的話**主站與 proxy 兩邊要設成同一個值** |
Comment thread README.md
| `OG_ZG_PROXY_BASE` | 賽道二 | **上傳必要** | 節點代理的網址（結尾要有 `/api`）。沒設的話前端會走同源的 `/api/og/zg`，那條路在 Cloudflare 上必定失敗 —— 見上面「賽道二還需要一台 Node 代理」 |
| `OG_PROXY_SECRET` | 賽道二 | 選用 | 代理用來簽節點網址的金鑰。擋的是「有人拿這個網域當跳板」，不是機密資料；沒設會用內建常數。要更嚴的話**主站與 proxy 兩邊要設成同一個值** |
| `OG_STORAGE_UPLOAD_URL` | 賽道二 | 選用 | 想讓玩家不用付儲存費才需要：指向自架的 `0g-storage-client` gateway，改由 Function 轉發上傳。預設是玩家用自己的錢包上傳，不需要設 |
| `OG_STORAGE_TOKEN` | 賽道二 | 選用 | 上述 gateway 需要的 Bearer token |
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort, defaults to Lite
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@k66inthesky @claude