Semantic Scholar API：Akashic 共用的金鑰與存取方式（往回、往前、相似作品、作者著作、書目查詢）

[kiki830621]

Problem

Original text:
「我有semantic scolor的api，是不是 /akashic 也可以支援api查詢功能 ?」
— Source: 使用者，2026-09-28（+08:00）對話

使用者有 Semantic Scholar（S2）的 API 金鑰，希望 Akashic 能用它查詢。

目前 Akashic 的外部查詢走 OpenAlex、Crossref、ORCID 與 DOI 解析，全都在 skill 層、經 safari-browser 取得（.claude/rules/web-access-via-safari-browser.md）。Sources/ 沒有 HTTP client（2026-09-28 量：URLSession／URLRequest 0 處）。

S2 是另一個獨立的學術圖譜，而且有幾種能力是現有來源沒有、或正是其他開著的 issue 需要的。本單要定下讓整個 Akashic 共用的 S2 存取方式，讓各個 skill 都能用。#640 是其中一個使用者。

Type

feature

S2 能提供什麼（2026-09-28 量：官方 OpenAPI 規格 graph/v1/swagger.json 與 recommendations/v1/swagger.json）

S2 端點	用途	對應的 Akashic 需求
GET /paper/{paper_id}/references	一篇論文的參考文獻	#640：akashic-work-references（#617）的第三來源
GET /paper/{paper_id}/citations	引用某篇的論文	#620：akashic-work-cited-by（往前追）
GET /papers/forpaper/{paper_id}（Recommendations API）	給一篇論文，回傳相似的論文	#621：akashic-work-connected（相似作品）
GET /author/search、GET /author/{author_id}/papers	作者搜尋與著作清單	#622：akashic-person-works
GET /paper/search/match、POST /paper/batch、GET /paper/{paper_id}	標題比對、批次查詢、單篇查詢	akashic-bootstrap 補書目欄位（現在用 Crossref、OpenAlex）

額度（S2 官方 API 頁）：有金鑰時的起始額度是所有端點合計每秒 1 次。

Expected

1. 定下存取方式。這要先決定，因為它牽動專案規則：
   • 是否仍經 safari-browser（頁內 fetch），還是改在 akashic CLI 裡直接呼叫。後者等於在 Sources/ 加 HTTP client，違反 web-access 規則第 2 條，要改規則或列為封閉例外
   • 金鑰怎麼送出：從 keychain 即時讀取，不寫進任何檔案；不得出現在指令列參數、process list、log 或頁面網址。akashic-work-references：以 Semantic Scholar references 作為第三來源（API key 經 keychain）(sibling concern from #639) #640 已指出，現行頁內 fetch 的程式碼是以指令列參數交給 safari-browser js 的，照原樣把金鑰塞進去就會外露
2. 共用的節流：所有 skill 合計遵守每秒 1 次。多個 skill 或多個 session 同時跑時怎麼協調
3. 每個使用者 skill 各自接上，不在本單一次做完：akashic-work-references：以 Semantic Scholar references 作為第三來源（API key 經 keychain）(sibling concern from #639) #640、新 skill akashic-work-cited-by（akashic-discovery plugin）：往前的引用追蹤——找出引用某篇的論文，產出候選清單由使用者勾選才建檔，絕不自動匯入 #620、新 skill akashic-work-connected（akashic-discovery plugin）：依書目耦合與共被引找相似作品，庫內計算優先，產出附連結理由的候選清單、勾選才建檔 #621、新 skill akashic-person-works（akashic-discovery plugin）：給一個人找出他的所有著作並補進 library，從 akashic-bootstrap 移出 person → works 路徑 #622、akashic-bootstrap 各自以本單的存取方式為前提
4. S2 回傳的資料一律是線索，不是寫入依據：依 source-of-truth-over-consent（Akashic 欄位值以文稿本身為最終依歸——文稿與 registry（Crossref／OpenAlex）不一致時的裁決原則 #639、library 沒有機器可讀的成員規則——封閉目錄被往回追誤掛 52 筆，要能在寫入時擋下 #642 定案），書目欄位的依據是作品本身，身分要判定

Actual

• 沒有任何 skill 使用 S2 API
• akashic-work-references：以 Semantic Scholar references 作為第三來源（API key 經 keychain）(sibling concern from #639) #640 提出了同樣的金鑰與存取方式問題，但只在單一 skill 的範圍內，尚未定案

Impact

• 往前追（新 skill akashic-work-cited-by（akashic-discovery plugin）：往前的引用追蹤——找出引用某篇的論文，產出候選清單由使用者勾選才建檔，絕不自動匯入 #620）、相似作品（新 skill akashic-work-connected（akashic-discovery plugin）：依書目耦合與共被引找相似作品，庫內計算優先，產出附連結理由的候選清單、勾選才建檔 #621）、作者著作（新 skill akashic-person-works（akashic-discovery plugin）：給一個人找出他的所有著作並補進 library，從 akashic-bootstrap 移出 person → works 路徑 #622）都需要引用關係或著作清單，S2 是其中一個主要來源
• 新 skill akashic-work-references（akashic-discovery plugin）：往回——從一篇作品的參考文獻找出該補進 library 的論文，驗證建檔並寫入 relations.cites #617 兩源（PDF × OpenAlex）對不上的情況有第三方可仲裁（akashic-work-references：以 Semantic Scholar references 作為第三來源（API key 經 keychain）(sibling concern from #639) #640）
• 存取方式若各 skill 各自實作，金鑰處理與節流會出現多份、不一致的做法

與既有 issue 的關係

• akashic-work-references：以 Semantic Scholar references 作為第三來源（API key 經 keychain）(sibling concern from #639) #640：本單是它的前提。akashic-work-references：以 Semantic Scholar references 作為第三來源（API key 經 keychain）(sibling concern from #639) #640 裡「金鑰的處理方式」「與 web-access 規則的關係」兩項，改在本單決定；akashic-work-references：以 Semantic Scholar references 作為第三來源（API key 經 keychain）(sibling concern from #639) #640 只處理第三來源本身
• [refactor] 既有 skill 的網頁取得指令遷移到 safari-browser（web-access 規則的 grandfathered 清單）(tangential from #617) #634（既有 skill 遷移到 safari-browser）：若本單決定帶金鑰的 API 不走 safari-browser，要同步更新 web-access 規則與 [refactor] 既有 skill 的網頁取得指令遷移到 safari-browser（web-access 規則的 grandfathered 清單）(tangential from #617) #634 的遷移範圍

待定

• keychain 的 service handle（由使用者提供；本 issue 不記任何金鑰內容）
• 存取方式（上面第 1 點）
• 先接哪一個 skill

Clarity Surface(idd-clarify run 2026-09-28T01:57:47Z)

Type	Source	Question for you	Status
ambiguity	「是不是 /akashic 也可以支援api查詢功能」	你要的是一個自己能直接下的 S2 查詢（例如「查這篇被誰引用」），還是讓既有的 skill 在流程裡用 S2 查資料，或兩者都要？	resolved @ 2026-09-28T04:47:10Z (reason: 兩者都要：使用者可直接下的查詢，與 skill 流程中的取用，走同一個接口)
ambiguity	「是否仍經 safari-browser（頁內 fetch），還是改在 akashic CLI 裡直接呼叫」	帶金鑰的 S2 呼叫，可以讓 web-access 規則為它開一個封閉例外、不經 safari-browser 嗎？	resolved @ 2026-09-28T04:47:10Z (reason: 要：帶金鑰的 S2 呼叫列為 web-access 規則的封閉例外，不經 safari-browser)
missing-context	「keychain 的 service handle（由使用者提供；本 issue 不記任何金鑰內容）」	S2 金鑰已經存進 keychain 了嗎？service 名稱是什麼？	resolved @ 2026-09-28T04:47:10Z (reason: 尚未存入，由使用者自行存入（user-only action）。提案 service semantic-scholar、account default，以值不經呼叫端的對話框寫入)
missing-context	「所有 skill 合計遵守每秒 1 次。多個 skill 或多個 session 同時跑時怎麼協調」	這把金鑰只給這台電腦上的 Akashic 用，還是其他機器或其他工具也會用？（2026-09-28 量：本機其他 repo 沒有原始碼呼叫 S2 API）	resolved @ 2026-09-28T04:47:10Z (reason: 只在這台電腦用：節流只需協調本機的 skill／session。其他使用者要用時，由 skill／MCP 提示他們自行設定金鑰)
missing-context	「先接哪一個 skill」	第一個接上 S2 的要是哪一個：#640、#620、#621、#622，還是 akashic-bootstrap？	resolved @ 2026-09-28T04:47:10Z (reason: 做成一個共用接口，每個功能都從它取用；本單交付接口本身，#640、#620、#621、#622、#665 各自接上)

Linked-Context Siblings Filed (v2.48.0+ #529)

Filed: #665

• akashic-bootstrap：以 Semantic Scholar 補 work 書目欄位——先量覆蓋率，有增益才接 (linked-context sibling from #664) #665：akashic-bootstrap 接 S2（本單「每個使用者 skill 各自接上」五個之中，唯一還沒有自己單子的）
• 「待定」三項已是上方 Clarity Surface 的列，akashic-work-references：以 Semantic Scholar references 作為第三來源（API key 經 keychain）(sibling concern from #639) #640、新 skill akashic-work-cited-by（akashic-discovery plugin）：往前的引用追蹤——找出引用某篇的論文，產出候選清單由使用者勾選才建檔，絕不自動匯入 #620、新 skill akashic-work-connected（akashic-discovery plugin）：依書目耦合與共被引找相似作品，庫內計算優先，產出附連結理由的候選清單、勾選才建檔 #621、新 skill akashic-person-works（akashic-discovery plugin）：給一個人找出他的所有著作並補進 library，從 akashic-bootstrap 移出 person → works 路徑 #622、[refactor] 既有 skill 的網頁取得指令遷移到 safari-browser（web-access 規則的 grandfathered 清單）(tangential from #617) #634 是既有單——皆依 IC_R011 §3「既有 issue 已涵蓋」不另開

---

Current Status

Phase: implemented（已推送到 main；R4 無 HIGH／MEDIUM；R4 之後的小修未再驗證）
Last updated: 2026-10-07 by idd-verify（R4 與推送紀錄：https://github.com/PsychQuant/Akashic-Library/issues/664#issuecomment-6023704389）
Dashboard: #664 (comment)

Key Decisions

• 已推送：修正輪在 main（b089dc73..074a2097，快轉、8 個 commit）；pre-push 的建置、全套測試、守衛全過，0 個失敗。推送後量：快取目錄只有 s2-throttle、沒有任何 x-api-key
• verify 四輪（pai-ensemble，4 lens＋DA＋Codex）：R1 FAIL（4 個 HIGH）→ R2（0 HIGH、9 MEDIUM）→ R3（0 HIGH、7 MEDIUM）→ R4（0 HIGH、0 MEDIUM，26 LOW）；R4 確認 R3 的修正成立。R4 之後的修正（小，文字與錯誤訊息字串）沒有再經 ensemble 驗證（任務 12.6）。整體判定是 FINDINGS（只剩 LOW），不是 PASS，所以沒有打 idd-664-verified
• 金鑰：使用者 2026-10-06 裁決沿用舊金鑰、不輪替（原話「這用舊的沒官系」，原文如此）；那些快取檔已刪。changelog 有給「從公開 main 建置過」的人的影響窗口提醒（2026-09-29 到這次推送之間）
• S2 的取得順序（使用者 2026-09-29 裁決「有 key 走 key，沒 key 最後才用 safari-browser」；R3、R4 後補完）：看 keychain.present／readable，不只看結束碼——都是 true → 接口；present 為 false（keychain 明確說找不到）→ 請使用者自己存、最後才經 safari-browser 不帶金鑰查；present 為 true 但讀不到（鎖著、權限、內容壞、不明錯誤）或其他結果 → 停下回報，不退到頁面；查詢本身回 3／1／64 時重跑 status --json 再選路。錯誤訊息分不出「鎖著」與「權限」（同一個狀態碼）：先解鎖、仍讀不到才查權限。解鎖、刪除、重存都是使用者自己在 Terminal 的動作
• 實作完成：spectra change semantic-scholar-interface 14/14；實機驗證通過（真金鑰查得 Hamaker 等 2015）
• 實作中修改 artifacts 五處（base URL 覆寫時不讀 keychain、blockedUntil、錯誤在擲出端清理、環境覆寫回 1、parity 守衛的名稱 regex），詳見 Implementation Complete
• spectra-discuss 收斂（2026-09-29）：新 library target AkashicS2，CLI akashic s2 與 MCP akashic_s2 直接呼叫、不經 AkashicService；八個端點一次做完
• 金鑰：keychain semantic-scholar／default，程序內非互動讀取，只對 api.semanticscholar.org 帶 x-api-key；讀不到就停下並指向設定文件
• 節流：全機每秒至多 1 次，429 退避共用，同一請求最多重試 3 次
• Complexity = Spectra；否決 skill 層 shell＋curl 與 safari-browser 頁內 fetch

Scope Changes

• 交付物是共用接口本身；akashic-work-references：以 Semantic Scholar references 作為第三來源（API key 經 keychain）(sibling concern from #639) #640、新 skill akashic-work-cited-by（akashic-discovery plugin）：往前的引用追蹤——找出引用某篇的論文，產出候選清單由使用者勾選才建檔，絕不自動匯入 #620、新 skill akashic-work-connected（akashic-discovery plugin）：依書目耦合與共被引找相似作品，庫內計算優先，產出附連結理由的候選清單、勾選才建檔 #621、新 skill akashic-person-works（akashic-discovery plugin）：給一個人找出他的所有著作並補進 library，從 akashic-bootstrap 移出 person → works 路徑 #622、akashic-bootstrap：以 Semantic Scholar 補 work 書目欄位——先量覆蓋率，有增益才接 (linked-context sibling from #664) #665 各自接上
• 新增：金鑰設定文件（給其他 Akashic 使用者）
• 範圍內順修：parity-table-drift 看不到含數字的名稱；測試替身在 async 函式內直接用 NSLock（pre-push 的 -warnings-as-errors 擋下，5c9b7d2a）
• 範圍內順修（verify R1–R3）：連線不快取、不跟隨轉址、429 退避共用、續查契約、JSON 面無損清理、present 的語意、取得順序的路由、plugin/CHANGELOG.md 與 changelog/2026-10-06-s2-interface-664.md

Blocking

• (none)——是否結案由你決定。結案時要做 spectra archive
• 追蹤中、不擋：[feature] akashic CLI 沒有發布管道，但依賴它的 skill 已有 5 個 (tangential from #617) #633（發布 akashic／akashic-mcp，使用者手上的 binary 才會有 s2／akashic_s2）、S2：非互動 keychain 讀取「不跳授權框」尚未在實機驗證（一次性的人工驗證） #725（「不跳授權框」與「解鎖是否跨工作階段」的人工實機驗證）、S2 接口：五個看過、沒有修的小決定（#664 verify 留下的） #727（五個看過、沒有修的小決定）、akashic-work-references：以 Semantic Scholar references 作為第三來源（API key 經 keychain）(sibling concern from #639) #640／新 skill akashic-work-cited-by（akashic-discovery plugin）：往前的引用追蹤——找出引用某篇的論文，產出候選清單由使用者勾選才建檔，絕不自動匯入 #620／新 skill akashic-work-connected（akashic-discovery plugin）：依書目耦合與共被引找相似作品，庫內計算優先，產出附連結理由的候選清單、勾選才建檔 #621／新 skill akashic-person-works（akashic-discovery plugin）：給一個人找出他的所有著作並補進 library，從 akashic-bootstrap 移出 person → works 路徑 #622／akashic-bootstrap：以 Semantic Scholar 補 work 書目欄位——先量覆蓋率，有增益才接 (linked-context sibling from #664) #665（各 skill 接上 S2）

Tasks

• 1.1 在 Package.swift 新增 library target AkashicS2（依賴 AkashicCore）與 test target AkashicS2Tests，讓 akashic 與 akashic-mcp 依賴 …
• 2.1 [P] 先寫測試再實作 S2KeyProvider：以 Security framework（kSecUseAuthenticationContext 搭配 interactionNotAllowed = true 的 `LAContext …
• 2.2 先寫測試再實作 S2Client 的 host 規則與錯誤分類：x-api-key 只附給 https://api.semanticscholar.org，loopback 覆寫一律不帶；404 回報找不到的識別碼，其他 4xx、5xx、連 …
• 3.1 [P] 先寫測試再實作 S2Throttle 的時段預約：以 flock 鎖住狀態檔、讀寫 nextAllowedAt、解鎖後才等待；存的時間比現在晚超過 60 秒時視為過期並從現在重設；狀態檔預設在 `~/Library/Caches/a …
• 3.2 先寫測試再實作 429 退避與重試：把共用的 nextAllowedAt 推到「現在＋Retry-After」（秒數或 HTTP-date），沒有 header 時依序等 2、4、8 秒，同一請求最多重試 3 次，Retry-After 超 …
• 4.1 先寫測試再實作八個端點的請求組裝與分頁（S2Endpoints）：以 10. 開頭的裸 DOI 補上 DOI:、id 百分比編碼、batch 至多 500 個 id、references／citations／author-papers 翻頁 …
• 4.2 [P] 先寫測試再實作 S2Output：S2 回應中的每個字串遞迴經過 displaySafe；依傳入的位元組上限只保留完整筆數，回報 returned、truncated、nextOffset（Requirement「Text …
• 5.1 先寫測試再實作 akashic s2 子命令群：八個端點各一個子命令，外加 status（design「每個端點一個具型別子命令」）；--json 信封含 source、endpoint、request、fetchedAt（ …
• 5.2 跨程序節流驗收：兩個 akashic 子程序共用同一個 AKASHIC_S2_STATE_DIR，各送 3 個請求到 loopback stub（Requirement「Requests are throttled machine-wide」） …
• 6.1 先寫測試再在 Sources/akashic-mcp/Server.swift 註冊 akashic_s2，在 async 的 CallTool handler 內分流：akashic_s2 走 async 的處理函式，其餘工具照舊走同 …
• 7.1 [P] 先寫負對照 akashic-guards network-confinement-mutations（RED），再寫 akashic-guards network-confinement，並在 `Sources/akashic-guar …
• 8.1 [P] 改寫 .claude/rules/web-access-via-safari-browser.md：第 2 條改為只有 Sources/AkashicS2/ 例外；例外清單從一類改為兩類（帶金鑰的 S2 呼叫經 akashic s2 …
• 8.2 [P] 寫設定文件 plugin/skills/akashic-bootstrap/references/semantic-scholar.md（存金鑰的指令、ACL 取捨、以 akashic s2 status 確認、結束碼 3 的兩種原因） …
• 8.3 整體驗證：swift build 與 swift test 全綠，且 RealHomeSandboxGuard 未報錯；bash .githooks/run-guards.sh 全綠；`spectra validate semantic …
• 9.1 連線不快取、不跟隨轉址：預設連線改為 ephemeral（urlCache、cookie 儲存為 nil），每個請求帶不快取、不處理 cookie，task delegate 把 3xx 當最終回應；測試 `S2SessionHardeningTe …
• 9.2 429 共用與狀態檔：放棄之前先記退避、長退避有自己的過期門檻（最多一小時）、其他呼叫者對超過 60 秒的封鎖快速失敗（結束碼 4）；狀態檔不跟隨 symlink、收緊到 0600、errno 先取走
• 9.3 續查契約：S2Result.hasMore 取自 S2 的 next；不分頁的端點與空的一頁 nextOffset 為 null；第一筆就超過 48 KiB 回錯誤並點名 fields；MCP limit 預設 100、至多 100 …
• 9.4 JSON 面的清理改為字串原樣＋序列化後無損逃脫（documentSafeJSON）；位元組上限量實際輸出
• 9.5 其餘程式修正：空白 --title／--name 回 64、--ids-file 大小上限與識別碼形狀檢查、金鑰錯誤訊息帶可照做的指令並先講「keychain 鎖著」
• 9.6 規則、規格與文件：取得順序補「其他結果停下回報」、mcp-cli-parity 例外改封閉列舉、-T 兩個 binary、skill／agent 不得直接讀 keychain 項目、akashic_s2 附在 tools 陣列最後、prop …
• 10.1 連線層的保證：逐請求的 cachePolicy 擋不住寫入（R2 實測），所以注入的連線若帶磁碟快取就拒絕（S2Client.isCacheFree）；預設連線全程序共用一個（S2Client.defaultSession，每次新建會在長 …
• 10.2 Retry-After 封頂一天（Int.max 轉 Int(delay) 會讓整個程序當掉）；backOff 先清掉過期的遠期狀態再合併；--ids-file 的上限量讀進來的位元組（/dev/zero 與 FIFO 量屬性 …
• 10.3 取得順序補洞：結束碼 3 且 keychain.present 為 true（項目在、讀不到）不是沒有金鑰，停下請使用者解鎖或改權限，不退到 safari-browser；skill／agent 不代使用者存金鑰
• 10.4 文字追上契約：parity 表 akashic_s2 列（續查看 nextOffset、JSON 面無損、結束碼清單、MCP 專有的三項限制）、README、規格的過期狀態情境、設定文件的過期門檻與 recommend 的建議、`netw …
• 10.5 追蹤與記錄：「不跳授權框」的人工實機驗證追蹤在 S2：非互動 keychain 讀取「不跳授權框」尚未在實機驗證（一次性的人工驗證） #725；金鑰輪替（使用者 2026-10-06 裁決沿用）、AKASHIC_S2_STATE_DIR 正式環境也接受、硬連結、nextOffset 以筆數計、預約時段的 60 秒門檻，都記進 …
• 11.1 結束碼 3 的路由：present 只在 keychain 明確回答找不到時是 false（itemMayExist(forAttributeStatus:)，有單元測試）；取得順序改成看 present／readable，不只看結束 …
• 11.2 使用者自己的動作：解鎖（security unlock-keychain，不加 -p）與重存都是使用者在自己 Terminal 的事，登入密碼與金鑰不進對話；缺金鑰與讀不到的錯誤訊息都這樣寫
• 11.3 S2Client 拒絕帶磁碟快取的注入連線改為 send 的錯誤（S2Error.unsafeSession），不再 precondition；有測試
• 11.4 Retry-After 比 Int 還大的數字視為封頂值，不是「沒給」；backOff 寫進狀態檔的 blockedUntil 有測試；被拒的識別碼不回顯內容；缺金鑰訊息拆成多行（plugin 安裝處的路徑不再被行長上限截掉）
• 11.5 plugin/CHANGELOG.md 與 changelog/2026-10-06-s2-interface-664.md；「看過、沒有修」表更正兩條站不住的理由，並補上暴露期
• 11.6 R3 之後的修正已在 R4 驗證（見下一組）
• 12.1 我引入的回歸：akashic s2 --help 與 MCP 工具描述補回 plugin 安裝處的設定文件位置
• 12.2 路由文字照實：錯誤訊息分不出「鎖著」與「權限」（同一個狀態碼）——先解鎖、仍讀不到才查權限；查詢本身回結束碼 3／1／64 時重跑 status --json 再選路；「其他結果」補上 MCP status 的 isError 與 `BA …
• 12.3 錯誤訊息：刪除與重存的「agent 不代刪、代存」、invalidValue 把 -U 指令印出來、不明的 keychain 錯誤指向文件並說明不是「沒有金鑰」、解鎖是否跨工作階段的提醒（未實測，併進 S2：非互動 keychain 讀取「不跳授權框」尚未在實機驗證（一次性的人工驗證） #725）
• 12.4 規格補 present 的語意與兩個情境；Retry-After 的句子改成 min(delay, 1 hour)；design 更正「不叫使用者重存」、--ids-file 的不做理由（承認第三方機密的殘餘風險）、「只有那一筆」限定 …
• 12.5 追蹤：五個小決定開成 S2 接口：五個看過、沒有修的小決定（#664 verify 留下的） #727；changelog 補「給從公開 main 建置過的人」的影響窗口提醒
• 12.6 R4 之後的修正（小，多為文字與錯誤訊息字串）沒有再經 ensemble 驗證；推送時 pre-push 會跑全套測試

Commits

• main 上：c11b0ed2 … 5c9b7d2a（原始實作，20 個）加 4715d1ae … 074a2097（修正輪，8 個）；git log --oneline --grep='#664'
• Sister：README 的 Python 範例寫死個人家目錄的絕對路徑（公開 repo）(sister bug from #664) #688、migrated-guard-control 偵測不到「負對照不存在」——main.swift 的 case 字串永遠滿足它 (sister bug from #664) #689、CI 觸發路徑沒有涵蓋整個 Sources/——network-confinement 在 CI 上只對部分目錄生效 (sister concern from #664) #690、core.hooksPath 是共用 checkout 的絕對路徑：從 worktree 推送時 pre-push 跑的是舊版 run-guards.sh #697、CLAUDE.md 規則索引的 web-access 列仍寫 --url-exact，規則本檔已改為 --url-endswith #698、S2：非互動 keychain 讀取「不跳授權框」尚未在實機驗證（一次性的人工驗證） #725、S2 接口：五個看過、沒有修的小決定（#664 verify 留下的） #727

[kiki830621]

Diagnosis

Type

feature

Root Cause / Analysis

需求拆解（issue body ＋ Clarity Surface 五題的回答）：

#	需求	來源
R1	一個共用接口，涵蓋 8 個 S2 端點：paper、search/match、batch、references、citations、recommendations/forpaper、author/search、author/{id}/papers	body〈S2 能提供什麼〉、Clarity 5
R2	使用者可以直接查，skill 也從同一個接口取用	Clarity 1
R3	金鑰從 keychain 讀（提案 service semantic-scholar、account default）；不出現在指令參數、process list、log、網址、檔案	body Expected 1、Clarity 3
R4	本機所有呼叫者合計每秒 1 次（多個 skill、多個 session、CLI 與 MCP 同時跑）	body Expected 2、Clarity 4
R5	帶金鑰的 S2 呼叫列為 web-access 規則的封閉例外	Clarity 2
R6	找不到金鑰時，接口告訴使用者怎麼自行設定（給其他 Akashic 使用者）	Clarity 4
R7	只讀：S2 回傳是線索，接口不寫 store	body Expected 4
R8	各使用者（#640、#620、#621、#622、#665）各自接上，不在本單做	Clarity 5

現況（2026-09-28 量）：

• Sources/ 沒有 URLSession／URLRequest／Network framework，也沒有 spawn curl：0 處
• Sources/ 沒有 Security framework 或 security CLI 的使用：0 處
• Sources/ 沒有跨程序的檔案鎖（現有的 NSLock 與 serial queue 都只在程序內）
• S2 官方 OpenAPI 規格（graph/v1/swagger.json）：金鑰必須放在 header x-api-key（大小寫有別）
• CLI 用 swift-argument-parser，CLI.swift 的 main() 是錯誤訊息的顯示安全閘；MCP 工具集中在 Sources/akashic-mcp/Server.swift，和 CLI 經 AkashicService 共用同一條路徑
• 環境變數覆寫的既有慣例：解析函式收可注入的 environment: 參數（例：LibraryLocator）
• 測試：AkashicCLITests 以子程序跑 binary；AkashicKitTests 等是 in-process，可以用 URLProtocol 攔截 HTTP，不需連網

所以本單的交付物在 Sources/ 裡是三個「第一次」：第一個 HTTP client、第一次讀 keychain、第一個跨程序鎖。

Impact

• 新增：S2 接口的 library target（網路、keychain、節流、回應清理），CLI 子命令群，依 parity 裁決的 MCP 工具
• 修改：Package.swift、Sources/akashic/CLI.swift（註冊）、Sources/akashic-mcp/Server.swift（若有 MCP 面）
• 規則：
  • web-access-via-safari-browser.md：第 2 條「Sources/ 不新增 HTTP client」要改成封閉例外；「不適用」第 2 類寫 akashic CLI「沒有網路」，加了 S2 之後這句就不成立了
  • mcp-cli-parity.md：新增一列裁決
  • CLAUDE.md 的規則索引
• 文件：金鑰設定指引（給其他使用者）
• 使用者流程：akashic-work-references（akashic-work-references：以 Semantic Scholar references 作為第三來源（API key 經 keychain）(sibling concern from #639) #640）、往前（新 skill akashic-work-cited-by（akashic-discovery plugin）：往前的引用追蹤——找出引用某篇的論文，產出候選清單由使用者勾選才建檔，絕不自動匯入 #620）、相似（新 skill akashic-work-connected（akashic-discovery plugin）：依書目耦合與共被引找相似作品，庫內計算優先，產出附連結理由的候選清單、勾選才建檔 #621）、作者著作（新 skill akashic-person-works（akashic-discovery plugin）：給一個人找出他的所有著作並補進 library，從 akashic-bootstrap 移出 person → works 路徑 #622）、akashic-bootstrap（akashic-bootstrap：以 Semantic Scholar 補 work 書目欄位——先量覆蓋率，有增益才接 (linked-context sibling from #664) #665）之後都改從這個接口取 S2；不再有 skill 在頁面裡帶金鑰 fetch（akashic-work-references：以 Semantic Scholar references 作為第三來源（API key 經 keychain）(sibling concern from #639) #640 指出的指令參數外露問題因此消失）

Strategy

推薦做法：Swift 內建的共用接口。另外兩條路都否決：

• skill 層用 shell 把金鑰從 keychain 導進 curl：違反 swift-is-the-implementation-language（skill 目錄不新增腳本）；節流要在每個 skill 各寫一份；macOS 沒有 flock 指令
• 經 safari-browser 頁內 fetch：使用者已否決（Clarity 2）；金鑰得交給 safari-browser js 的指令參數，會外露

實作步驟：

• 新 library target（暫名 AkashicS2），CLI 與 MCP 都依賴它
  • HTTP client：URLSession，host 白名單只有 api.semanticscholar.org
  • 金鑰：x-api-key 只在 host 是 S2 時才附上。測試用的網址覆寫（例如 AKASHIC_S2_BASE_URL）只接受 loopback，而且一律不帶真金鑰；否則一個環境變數就能把金鑰導到別的主機
  • KeyProvider：用 SecItemCopyMatching 在程序內讀取，設成非互動（kSecUseAuthenticationUIFail），免得 MCP server 卡在看不見的授權框
    • 讀不到（項目不存在，或 ACL 不讓讀）→ 專用 exit code，附設定指引
    • 不提供環境變數或指令參數當金鑰來源：ps -E 看得到同使用者程序的環境變數
  • Throttle：flock 鎖一個狀態檔，檔內記上次請求的時間。每次請求等到上次時間加 1 秒後才送；遇到 429 照 Retry-After 有上限地重試。狀態檔放在 ~/Library/Caches/akashic/，不放 ~/.akashic（RealHomeSandboxGuard 監看那裡）；測試另有覆寫目錄
  • 回應清理：S2 的字串是外部、不可信的文字，輸出前逐欄遞迴過一遍既有的顯示安全清理
• CLI 子命令群 akashic s2 …
  • 8 個端點各一個具型別的子命令（paper、match、batch、references、citations、recommend、author-search、author-papers）
  • 加 status：回報金鑰存在、可讀、節流狀態，不印出值
  • 分頁由接口處理
  • 輸出 JSON：source、endpoint、fetched_at、data
• MCP 面：依 mcp-cli-parity 裁決。使用者要能直接查（Clarity 1），傾向提供 akashic_s2（見下方決策點 D2）
• Guard：URLSession 與 Security framework 只准出現在這個 target，進 run-guards。離線本體的不變式從「0 處」改成「只在一處」，由機器守
• 規則與文件：web-access-via-safari-browser.md（封閉例外改成兩類；「不適用」第 2 類改寫）、mcp-cli-parity.md、CLAUDE.md 索引、金鑰設定指引
• 測試（全部不碰真 keychain、不連網）
  • in-process 用 URLProtocol stub 驗證：只有 S2 host 帶 x-api-key；金鑰不出現在網址；429 重試有上限；清理有效
  • 兩個子程序搶同一個狀態目錄，驗證每秒 1 次
  • CLI 子程序測「沒有金鑰」路徑的 exit code 與訊息
• 發布：~/bin/akashic 重建照 [feature] akashic CLI 沒有發布管道，但依賴它的 skill 已有 5 個 (tangential from #617) #633 的閘（其他工作線全部驗過才重建）；若有 MCP 面，走 akashic-mcp 的發布流程

要在 spectra-discuss 對齊的決策點：

• D1 介面形狀：每個端點一個具型別子命令（推薦，契約穩定、參數可驗證），還是一個限定路徑前綴的通用 get
• D2 使用者直接查的入口：CLI ＋ MCP 工具 akashic_s2（推薦）／CLI ＋ 一個 skill／三者都有
• D3 keychain ACL：允許所有 app 讀取（推薦，security add-generic-password -A；S2 金鑰免費、有額度限制、可撤銷重發）／只信任特定 binary（akashic 是本機 ad-hoc 建置，每次重建都會再跳授權提示）
• D4 沒有金鑰時：停下並附設定指引（推薦，照 Clarity 4）／退回匿名請求（S2 共用額度，容易 429）
• D5 設定指引放哪裡：核心 plugin 的 references 文件，由 CLI 錯誤訊息與 skill 引用（推薦）／一個獨立的設定 skill

Conflict Class

C_shared_module_coord — 共享資源：Package.swift、Sources/akashic/CLI.swift（子命令註冊）、Sources/akashic-mcp/Server.swift（工具表）、.claude/rules/mcp-cli-parity.md。這幾個檔案目前也有其他進行中的修改，實作前要先協調。

Complexity

Spectra

• Layer 1：未命中。deliverable 是程式與對外介面，不是 prose 或一次性分析
• Layer V（Step 3.4）：V1 = 2、V4 = 3，未觸發（見下方 audit）
• Layer 2：命中。新增 CLI 子命令群（加上可能的 MCP 工具），是給 future callers（akashic-work-references：以 Semantic Scholar references 作為第三來源（API key 經 keychain）(sibling concern from #639) #640、新 skill akashic-work-cited-by（akashic-discovery plugin）：往前的引用追蹤——找出引用某篇的論文，產出候選清單由使用者勾選才建檔，絕不自動匯入 #620、新 skill akashic-work-connected（akashic-discovery plugin）：依書目耦合與共被引找相似作品，庫內計算優先，產出附連結理由的候選清單、勾選才建檔 #621、新 skill akashic-person-works（akashic-discovery plugin）：給一個人找出他的所有著作並補進 library，從 akashic-bootstrap 移出 person → works 路徑 #622、akashic-bootstrap：以 Semantic Scholar 補 work 書目欄位——先量覆蓋率，有增益才接 (linked-context sibling from #664) #665）的公開介面，behavior contract 應寫成 spec
• Layer 3：命中三項
  • 修改既有規則的 normative 條文：web-access 第 2 條是 MUST
  • 牽動 2 份以上規則的一致性：web-access、mcp-cli-parity、swift-is-the-implementation-language 的放置表
  • 長期架構決定：本體第一次連網、第一次讀 keychain、第一個跨程序鎖
• Hard-gate: triggered — 同一個概念散佈到 ≥ 5 檔（新 target、Package.swift、CLI.swift、Server.swift、兩份規則、CLAUDE.md、測試）。但 Spectra（Layer 2 ＋ 3）優先，verdict 仍是 Spectra

Risks

• 離線本體的不變式被打開一個口：要靠 guard 把網路與 keychain 鎖在單一 target，否則之後的改動會照抄
• 金鑰外洩的四條路：
  • 網址覆寫把金鑰導到別的主機 → 只對 S2 host 帶 header
  • 錯誤訊息或 debug 輸出印出 request headers → 永不記錄 headers
  • MCP 工具的參數或回傳帶到金鑰 → 金鑰只存在 KeyProvider 內
  • 環境變數當金鑰來源 → 不提供
• keychain ACL：選錯的話，MCP server 會卡在授權，或每次重建都要重新授權
• 節流：跨程序鎖的正確性（程序中途死掉時鎖會不會釋放：flock 隨 fd 關閉釋放）；時鐘回撥；429 連鎖
• 測試隔離：不得碰真 keychain、真網路、真 ~/.akashic
• 發布：新子命令要等 ~/bin/akashic 重建（[feature] akashic CLI 沒有發布管道，但依賴它的 skill 已有 5 個 (tangential from #617) #633 的閘，目前還有其他工作線未驗）；MCP 面還要 akashic-mcp 發布
• 共用 checkout 的並行修改：見 Conflict Class

Residue

使用者的原意是「Akashic 能用 API 查詢」。之後若有其他需要金鑰的 API（例如別的學術圖譜付費層），是否共用同一套金鑰、節流與 host 白名單框架，本單不處理：本單只做 S2，泛化留待真的出現第二個 API 時再決定。

Vagueness Pre-check

• V1: 2 — 要做什麼已經具體：8 個端點列在 body 的端點表；Clarity 1、5 定了「一個接口、兩種使用者」
• V4: 3 — 完成定義多半可以推導（金鑰不外露的四條路、每秒 1 次、缺金鑰時提示），但 body 沒有寫成明文的驗收條件；留待 spectra spec 的 scenarios 補上
• Triggered: no — both axes ≤ 3

Recommended Agent: claude-opus-4.7

Confidence: 0.5（cold start，沒有歷史資料）
Data source: static_heuristic
Reasoning: 靜態規則偏好 Claude family；四個候選的 N 都是 0，僅供參考

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

(none surfaced)

• 規則改寫、akashic-work-references：以 Semantic Scholar references 作為第三來源（API key 經 keychain）(sibling concern from #639) #640 的指令參數外露、[feature] akashic CLI 沒有發布管道，但依賴它的 skill 已有 5 個 (tangential from #617) #633 的重建閘：皆在本單範圍內或已有既有單（IC_R011 §3）

[kiki830621]

📊 For Reviewer / Collaborator

現在：Semantic Scholar 共用接口（akashic s2／akashic_s2）與它的修正輪都在 main（074a2097）。四輪驗證（pai-ensemble）的趨勢是收斂的：R1 有 4 個 HIGH，R2、R3 沒有 HIGH，R4 連 MEDIUM 都沒有（26 個 LOW，多是文字）；R4 確認 R3 的修正成立。推送前的 pre-push 全套測試與守衛 0 個失敗。整體判定是 FINDINGS（只剩 LOW），不是 PASS，所以沒有打 verified tag。記錄：#664 (comment)
Blocking：無。使用者手上的 akashic／akashic-mcp 還沒有這個接口——要等 #633 發布，或從 main 建置。
你該做什麼：決定是否結案（結案時要做 spectra archive）。不急、但值得排的：#633（發布）、#725（兩個人工實機驗證）、#727（五個小決定）。

last-updated by idd-verify at → implemented (pushed), 2026-10-07

[kiki830621]

🎯 Decision

Original (2026-09-29)：
「都正確」（回覆 spectra-discuss 列出的五條假設）
「可以一次全做」（回覆三個例子是否正確）

決定

S2 共用接口採用 spectra-discuss 收斂的設計。新增一個 library target AkashicS2，CLI 的 akashic s2 <端點> 與 MCP 的 akashic_s2 兩面都直接呼叫它；八個端點一次做完。接下來走 spectra-propose，然後實作。

Rationale

這次設計的核心取捨，是做一個夠深的模組，還是讓各 skill 各寫一份。金鑰處理與節流只要分岔一次，就同時出現外洩點與超速：某個 skill 把金鑰印進 log，另一個 skill 用程序內的鎖，兩個 session 同時跑時就超過 S2 每秒 1 次的額度。把 S2 關在單一 target 裡，還有第二個好處：「本體其他部分不連網」可以用 target 邊界加 guard 機械地守住，不必靠每次審查去記得。

有兩個方向被刻意避開。第一，不把 S2 包進 AkashicService：那是綁 store 的服務層，而 S2 查詢完全不開 store，包進去只是多一層只轉呼叫的 adapter，刪掉它什麼都不壞。第二，不把 S2 程式放進 AkashicCore：那會讓網路程式與離線本體混在同一個 target，守衛只能靠掃字串。

五條定案的假設：

1. 邊界：新 library target AkashicS2，CLI 與 MCP 直接呼叫，不經 AkashicService
2. 兩面都做：依 mcp-cli-parity「可用性不該取決於用 MCP 還是 CLI」。MCP 面輸出上限 48 KiB，以 total／returned／truncated 揭露（先例：akashic_doctor 列）；CLI 面不截
3. 介面形狀：每個端點一個具型別子命令；讀取面預設人可讀、--json 原樣輸出（parity 規則的讀取面要求）
4. 金鑰：keychain service semantic-scholar、account default；程序內 SecItemCopyMatching 非互動讀取；ACL 為所有 app 可讀（akashic 是本機 ad-hoc 建置，限定特定 binary 會在每次重建後卡在授權）；只對 api.semanticscholar.org 附上 x-api-key；讀不到就停下並指向設定文件，不退回匿名
5. 節流：flock 鎖 ~/Library/Caches/akashic/s2-throttle，記「下次可送時間」；429 照 Retry-After 退避，退避狀態由所有呼叫者共用；同一請求最多重試 3 次；不做回應快取。狀態檔不放 ~/.akashic（RealHomeSandboxGuard 監看那裡）

三個確認過的例子（之後寫進 spec 的 ##### Example:）：

情境	預期行為
節流	A 在 t=0.00 送出 → 下次可送時間 1.00；B 在 t=0.30 要送 → 等到 1.00；A 收到 429、Retry-After: 3 → 共用的下次可送時間推到 4.00，B 的下一個請求也等到 4.00；同一請求重試 3 次仍 429 → 回報錯誤結束
一篇 1,000 筆參考文獻	CLI akashic s2 references <id> --json 自動翻完分頁，輸出 1,000 筆；MCP 只回放得進 48 KiB 的完整筆數，附 total: 1000、returned、truncated: true 與下一頁的 offset，不切半筆
沒有金鑰	CLI 以專用 exit code 結束，訊息寫明 service／account 並指向設定文件，不退回匿名；MCP 回傳同一段訊息並標為錯誤

介面深度檢查：

問題	回答
邊界放哪裡	AkashicS2 負責端點、金鑰、節流、輸出清理的整份契約
幾層 adapter	一層（S2 client）；CLI 子命令與 MCP 那一段只做參數解析與輸出格式
裡面藏了什麼	keychain 讀取、host 白名單與 header 附加規則、跨程序節流與共用退避、429 重試、分頁、外部字串清理
刪掉會壞什麼	兩個面，以及 #640、#620、#621、#622、#665；它們會各自重寫金鑰與節流

金鑰狀態：使用者 2026-09-29 表示已存入 keychain。我沒有另外查 keychain 確認；實作完成後由 akashic s2 status 確認讀得到（只回報存在與可讀，不印值）。

Related

#664、#640、#620、#621、#622、#665、#633、#634

[kiki830621]

Implementation Complete

Spectra change semantic-scholar-interface 的 14 個任務全部完成（spectra instructions apply 回報 all_done、spectra validate 通過）。實作在分支 idd/664-semantic-scholar（從 origin/main 6b3cc959 開出），18 個 commit，尚未推送。

做了什麼

• AkashicS2（新 library target）：本體裡唯一可以連網、唯一可以讀 keychain 的地方。八個端點（paper、match、batch、references、citations、recommend、author-search、author-papers）加 status；分頁與 total；金鑰以 kSecUseAuthenticationContext＋interactionNotAllowed 的 LAContext 非互動讀取（Apple 文件：kSecUseAuthenticationUIFail 自 macOS 11 棄用），金鑰型別一律描述為 <redacted>；x-api-key 只附給 https 且 host 恰為 api.semanticscholar.org 的請求；flock 狀態檔預約時段、429 退避共用、醒來後重新檢查封鎖期；外部字串經 displaySafe
• CLI akashic s2：九個子命令、--json 信封與同源的人可讀輸出；結束碼 0／1／3／4／5／64
• MCP akashic_s2：與 CLI 共用 AkashicS2、不經 AkashicService；48 KiB 上限只放完整筆數（total／returned／truncated／offset／nextOffset）；錯誤文字與 CLI 逐字相同
• **守衛 akashic-guards network-confinement**＋負對照（11/11）：九個網路／keychain 字樣只准出現在 Sources/AkashicS2/
• 規則與文件：web-access 規則的例外改為兩類、〈不適用〉排除 akashic s2；parity 表加 akashic_s2 ↔ s2（33 → 34）；CLAUDE.md 索引；plugin 側 references/web-access.md 與 akashic-bootstrap SKILL.md 指明 S2 另走一條路；新設定文件 references/semantic-scholar.md；README 段落

Checklist

• AkashicS2 target、三個受限的測試覆寫（任務 1.1）
• 金鑰非互動讀取、<redacted>（2.1）；host 規則與錯誤分類（2.2）
• 跨程序節流（3.1）；429 共用退避與重試上限（3.2）
• 八個端點與分頁（4.1）；外部字串清理與 MCP 位元組上限（4.2）
• akashic s2 子命令群（5.1）；兩程序節流驗收（5.2）
• MCP akashic_s2（6.1）
• network-confinement 守衛與負對照（7.1）
• 規則、CLAUDE.md、parity 表（8.1）；設定文件與 README（8.2）
• 全套測試、守衛、實機驗證（8.3）

驗證

• swift test：七個 bundle 全部通過（exit 0），RealHomeSandboxGuard 未報錯；新測試：AkashicS2Tests 43、CLI S2CommandTests 10、MCP S2ToolTests＋S2ToolStdioTests 7
• bash .githooks/run-guards.sh：exit 0
• TDD：每個任務先 RED 再 GREEN；在骨架上就通過的測試（過期狀態重設、Retry-After 超過 60 秒、兩程序節流）各補 mutation check，拿掉對應的邏輯時都會失敗
• 實機（使用者的機器、真金鑰）：akashic s2 status --json 回報 present／readable 皆為 true、結束碼 0、未跳授權框、不含金鑰；akashic s2 paper DOI:10.1037/a0038889 --json 回傳〈A critique of the cross-lagged panel model.〉（2015；Hamaker、Kuiper、Grasman），fetchedAt 帶 +08:00

實作中對 artifacts 的修改（已同步進 spec／design，未默默偏離）

1. AKASHIC_S2_BASE_URL 設定時不讀 keychain：否則成功路徑的 CLI 測試需要測試用金鑰；金鑰本來就只送 S2 主機
2. 狀態檔多一個 blockedUntil，醒來後重新檢查：只推 nextAllowedAt 時，已預約較早時段、正在睡的呼叫者不會被 429 擋住——spec 的「A 429 delays the other session too」照原 design 做不到
3. 錯誤在擲出端清理、宣告 SanitizedErrorDescription：初版在描述端才清理，方向與 venue 的 authorized 只有 bootstrap 寫得到——479/479 筆是 [names[0]]，而合併會單向降級它 #554 相反（SanitizationBoundaryTests 抓出）
4. 環境覆寫被拒回 1，不是 64：依 store 缺佈局回 exit 64（EX_USAGE）並印 top-level usage——執行期失敗被渲染成用法錯誤 (sister bug from #547) #549，環境變數不是 argv；argv 錯誤移到 validate()、早於任何 I/O
5. parity 守衛的名稱 regex 不允許數字：akashic_s2 在程式與表兩邊一起漏掉、集合仍相等而守衛照綠；S2Cmd.self 被讀成 Cmd——已修，並以拿掉那列時守衛會失敗驗證

Sister Bugs Filed

Filed: #688, #689, #690

• README 的 Python 範例寫死個人家目錄的絕對路徑（公開 repo）(sister bug from #664) #688：README 的 Python 範例寫死個人家目錄的絕對路徑（公開 repo，既有問題）
• migrated-guard-control 偵測不到「負對照不存在」——main.swift 的 case 字串永遠滿足它 (sister bug from #664) #689：migrated-guard-control 偵測不到「負對照不存在」
• CI 觸發路徑沒有涵蓋整個 Sources/——network-confinement 在 CI 上只對部分目錄生效 (sister concern from #664) #690：CI 觸發路徑沒有涵蓋整個 Sources/，network-confinement 在 CI 上只對部分目錄生效

待定

• 推送：待使用者同意（pre-push 會跑全套測試）
• 政策問題：未帶金鑰的 S2 查詢，規則目前沒有禁止它經 safari-browser 走——那會是繞過全機節流的第二條路。建議：所有 S2 查詢一律經 akashic s2／akashic_s2
• ~/bin/akashic 的重建依 [feature] akashic CLI 沒有發布管道，但依賴它的 skill 已有 5 個 (tangential from #617) #633 的閘；akashic-mcp 隨 plugin release 發布
• 合併後：/idd-verify #664，之後 spectra archive