Skip to content

refactor: Akashic-Library 自身成為 plugin——akashic-mcp shell（skills/wrapper/manifest）遷入本 repo，marketplace 改為引用 #275

Closed
Closed
refactor: Akashic-Library 自身成為 plugin——akashic-mcp shell（skills/wrapper/manifest）遷入本 repo，marketplace 改為引用#275

Description

@kiki830621
kiki830621
opened on Aug 13, 2026

Problem

Original text（使用者，2026-08-14）:
「（plugins/akashic-mcp/skills/）這應該全部都放在 Akashic-Library 才對，是不是 skill 放錯地方了，那邊應該也要成一個 plugin」

akashic-mcp 的 plugin shell 目前散在 psychquant-claude-plugins（marketplace repo）：

psychquant-claude-plugins/plugins/akashic-mcp/
├── .claude-plugin/plugin.json     # version 0.5.0、binary 版本 pin
├── .mcp.json                      # MCP server 定義（wrapper 啟動）
├── bin/akashic-mcp-wrapper.sh     # 依 plugin.json 版本自動下載 binary
├── skills/akashic-bootstrap/      # 既有 skill ×2
├── skills/akashic-bootstrap-workspace/
└── CHANGELOG.md

而 binary 原始碼、mcpb bundle、以及所有 akashic 開發追蹤都在 Akashic-Library。後果：skill 的開發與 akashic 本體脫節（今天 #232 的 verdict ledger 落地，配套查證 skill 卻要去另一個 repo 開發）、issue 追蹤散兩處、release 鏈要跨 repo 同步兩次。

Type

refactor

Expected

Akashic-Library 自身成為 plugin 的 source of truth：

  1. plugin shell（.claude-plugin/plugin.json、.mcp.json、bin/wrapper、skills/、plugin CHANGELOG）搬進 Akashic-Library（佈局由 diagnose 拍板，例如 repo 根 .claude-plugin/ 或 plugin/ 子目錄）
  2. 既有兩個 skill（akashic-bootstrap、akashic-bootstrap-workspace）隨遷，git 歷史至少以搬遷 commit 交代來源
  3. psychquant-claude-plugins 的 marketplace.json 改為引用 Akashic-Library——diagnose 需先查證 Claude Code marketplace schema 是否支援 git/github plugin source（livedocs 查最新文檔，不憑記憶）；若支援 → 直接引用；不支援 → 退而求其次：release 時同步（如 binary 既有鏈，plugin-update 流程調整）
  4. 既有安裝的升級路徑不斷（wrapper 版本 pin 機制、claude plugin update 照常運作）
  5. /devtools:plugin-update akashic-mcp 鏈（common-release-flow 的強制 marketplace sync）在新佈局下仍成立——調整其偵測或文檔

Impact

  • akashic 的所有開發（binary／skills／plugin shell）單一 repo 追蹤，release 單點
  • 後續 skill 開發（person-verify、wos-intake——見 blocked issues）直接在本 repo 進行
  • psychquant-claude-plugins 降為純 marketplace（它本來的定位）

順序

本案是 skill 系列的前置：person-verify 與 wos-intake 兩案 blocked by 本案。

Current Status

Phase: closed
Last updated: 2026-08-14 by idd-close（closed——PR #278＋marketplace merge；0.5.3 全鏈實測落地）

Key Decisions

  • marketplace 引用機制查證定案：git-subdir source（sparse clone 子目錄）——不走 release-time 同步複製
  • plugin 落點：Akashic-Library plugin/ 子目錄；marketplace entry 移除 version 欄位（單一版本源）

Scope Changes

  • (none)

Blocking

Tasks

Activity

  1. kiki830621 commented on Aug 13, 2026

    @kiki830621
    kiki830621
    on Aug 13, 2026
    MemberAuthor

    Diagnosis

    Type

    refactor

    Root Cause / Analysis（現狀分析）

    為什麼要重構：akashic 的 plugin shell（plugin.json／.mcp.json／wrapper／skills×2／CHANGELOG）住在 psychquant-claude-plugins，binary 原始碼與全部開發追蹤住 Akashic-Library——同一產品的兩半各自演化，release 要跨 repo 同步兩次（今天 v0.5.0 實際走過：Akashic-Library 發 release → 手動 bump marketplace repo 三檔 → marketplace update → plugin update），skill 開發與本體脫節（#232 的 verdict ledger 落地當天，配套 skill 卻要去另一 repo 開發——使用者裁定統一）。

    關鍵查證（livedocs → code.claude.com/docs/en/plugin-marketplaces.md，2026-08-14）：marketplace.json 的 plugin source 原生支援外部 git 來源——

    • {"source": "github", "repo": "owner/repo", "ref"?, "sha"?}（整 repo 為 plugin）
    • {"source": "git-subdir", "url": "…", "path": "…", "ref"?, "sha"?}（repo 子目錄為 plugin，sparse clone 省頻寬——文檔明寫為 monorepo 設計）

    → 不需要「release 時同步複製」的次佳方案；marketplace 直接引用即可。

    Private repo 注意：Akashic-Library 是 private——git 來源的 fetch 用使用者自己的 git 憑證，等同現況（wrapper 的 gh release download 本來就要 private repo 存取權；公開 marketplace 的其他使用者今天也裝不了 binary）。可及性不變。

    風險評估：改動範圍＝兩 repo（Akashic-Library 新增 plugin/ 子樹；marketplace repo 改 entry、刪 plugins/akashic-mcp/）；無測試覆蓋 plugin 佈局（驗收靠 claude plugin update 實測）；隱藏依賴＝harness-devtools:plugin-update 的偵測邏輯假設 shell 住 marketplace repo（plugins/{name}/）——遷移後該 chain 對 akashic-mcp 的行為改變，須在 README/CHANGELOG 明記新流程。

    Impact

    • Akashic-Library：新增 plugin/（.claude-plugin/plugin.json、.mcp.json、bin/wrapper、skills/、CHANGELOG）
    • psychquant-claude-plugins：marketplace.json 的 akashic-mcp entry 改 git-subdir source；plugins/akashic-mcp/ 移除
    • 使用者端：claude plugin update akashic-mcp@psychquant-claude-plugins 照常（source 變更由 marketplace update 帶下來）
    • Release 流程：單 repo 化——bump plugin/plugin.json 與 binary release 同 commit/tag，marketplace entry 不再逐版本改

    Strategy

    • Akashic-Library 建 plugin/ 子樹：搬 plugin.json（version 0.5.0 起跳）、.mcp.json、bin/akashic-mcp-wrapper.sh、skills/（akashic-bootstrap、akashic-bootstrap-workspace）、CHANGELOG.md——搬遷 commit 明記來源 repo 與路徑
    • marketplace.json entry 改 {"source": {"source": "git-subdir", "url": "https://github.com/PsychQuant/Akashic-Library.git", "path": "plugin"}}；entry 保留 name/description/author/category，version 欄位移除（安裝版本以 fetch 到的 plugin.json 為準，避免雙源漂移）——若 schema 要求 version 則保留並註記同步義務
    • marketplace repo 刪 plugins/akashic-mcp/（同 commit，附遷移說明）
    • 實測升級路徑：claude plugin marketplace update → claude plugin update akashic-mcp → 確認 wrapper 照常自動下載 binary、MCP server 可啟動
    • Akashic-Library README ＋ marketplace repo 該 entry 的文檔：新 release 流程（單 repo bump）與 plugin-update chain 的行為變更明記
    • 兩 repo 各自 commit 均引用本 issue（cross-repo 全名引用）

    Conflict Class

    C_shared_module_coord——共享資源：psychquant-claude-plugins 的 marketplace.json 與 akashic plugin shell 佈局；本批 #276/#277 blocked by 本案（skill 落點依本案的 plugin/skills/）。

    Complexity

    Plan

    Hard-gate: triggered——單一概念（plugin shell 搬遷）散佈 ≥5 檔且跨兩 repo（plugin.json／.mcp.json／wrapper／skills×2／CHANGELOG／marketplace.json）；shared abstraction＝release 鏈與 plugin-update 流程（≥2 消費端：release-signed.sh 之後的 sync 步驟、harness-devtools 偵測）。Layer P 另命中：順序依賴（先搬樹→改 entry→刪舊→實測）、risk-sensitive（既有安裝的升級路徑不可斷）。

    [Plan tier deliberation will be skipped under unattended mode——/idd-all orchestrator]

    Risks

    • git-subdir source 對舊版 Claude Code 的支援下限文檔未標（github/url/git-subdir 無版本註記；archive 需 v2.1.224+、command 需 v2.1.229+）——實測本機版本通過即可，其他機器若過舊需升級 Claude Code
    • marketplace entry 改壞會讓 plugin update 失敗——保留舊 plugins/akashic-mcp/ 於同 PR 的前一 commit，回退容易
    • .mcp.json 的 wrapper 相對路徑在新佈局下必須重驗（plugin root 變成 plugin/）

    Residue

    其他 che-mcps 家族 repo（che-apple-mail-mcp 等）沿用同樣的 binary/shell 兩 repo 分工——本案為 akashic 建立「repo 即 plugin」先例，是否推廣到其他 repo 是使用者的架構政策，不在本案 scope；此處明記不靜默。

    Vagueness Pre-check

    • V1: 2——要做什麼明確（issue 列了五項 Expected，落點與引用機制經查證確認）
    • V4: 3——驗收「既有安裝升級不斷」可實測但無自動化測試；以手動驗證清單補
    • Triggered: no——both axes ≤ 3

  2. kiki830621 commented on Aug 13, 2026

    @kiki830621
    kiki830621
    on Aug 13, 2026
    MemberAuthor

    Verify

    Mode: 機械驗證（config/佈局遷移——無 Swift code 變更，無 6-AI fan-out 必要；驗證面全數可機械測試）
    Result: PASS

    驗證項 結果
    claude plugin validate plugin/ ✔（binary_version unknown-field warning 為預期——harness-devtools 慣例欄位）
    wrapper 版本解析：binary_version 優先 0.5.0 ✓
    wrapper 相容：欄位缺席回讀 version 0.5.1 ✓
    bash -n wrapper 語法 ✓
    git-subdir e2e：private repo 匿名非互動 sparse clone → fetch 分支 → checkout plugin/ 恰好 9 個 plugin 檔 ✓（憑證鏈可用）
    舊路徑殘留引用掃描（che-claude-config／marketplace repo／本 repo／~/.claude 設定） 乾淨——plugin ID akashic-mcp@psychquant-claude-plugins 不變，既有安裝不受影響
    schema 依據 code.claude.com/docs/en/plugin-marketplaces.md（git-subdir：url＋path＋ref?＋sha?）

    PR: #278（本 repo）＋ psychquant-claude-plugins akashic-mcp-git-subdir 分支（merge 順序：#278 先）

  3. kiki830621
    added a commit that references this issue on Aug 13, 2026

    refactor: akashic-mcp plugin shell 遷入本 repo——plugin/ 子樹 + binary_vers…

    428bfd1

  4. kiki830621 commented on Aug 13, 2026

    @kiki830621
    kiki830621
    on Aug 13, 2026
    MemberAuthor

    Closing Summary

    Problem

    akashic-mcp 的 plugin shell（plugin.json／.mcp.json／wrapper／skills）住在 psychquant-claude-plugins，binary 住本 repo——每次 release 都要跨 repo 同步兩邊，skill 的程式碼實體與它服務的專案分離。使用者裁決：Akashic-Library 自己就是 plugin 的 source of truth。

    Root Cause

    歷史沿革：marketplace 早期以「每個 plugin 一個子目錄」集中管理，當時 Claude Code 尚無（或未查證）從外部 repo 子目錄引用 plugin 的機制。#276/#277 兩個 skill 要落地時，「skill 放哪」的問題把這個架構債擠到台面上。

    Solution

    「repo 即 plugin」：本 repo 建 plugin/ 子樹（plugin.json、.mcp.json、bin/wrapper、skills/、CHANGELOG），marketplace entry 改 git-subdir source（{"source": "git-subdir", "url": …, "path": "plugin"}，version 欄位移除以避免雙源漂移）；marketplace repo 刪本地副本。關鍵設計：plugin.json 新增 binary_version 與 version 解耦——shell-only bump 不再產生不存在的 release tag，wrapper 以 binary_version 為準（缺席回讀 version 相容）。eval 工作區（504 檔）不出貨，移存 docs/skill-evals/。

    Verification

    • git-subdir 機制 e2e 實測：private repo 匿名 sparse clone 可用、wrapper 解析正確（verify comment）
    • merge 後全鏈實測：claude plugin marketplace update → claude plugin update akashic-mcp 成功 0.5.0 → 0.5.3，三個 skill（bootstrap／person-verify／wos-intake）都在安裝 cache、binary wrapper 照常
    • stale-reference sweep 零殘留；pre-push 全套測試綠

    Changes

    Merge-completeness

    Step 1.55 rc=0（clean）。

    Distribution Sync

    • Detected: plugin+mcp
    • Choice / Outcome: 已於 close 前依使用者指示手動完成——marketplace merge → claude plugin marketplace update → claude plugin update（0.5.3 落地實證見 Verification）
    • At: 2026-08-13T23:30Z

    Residue Acknowledgement

    Filed: PsychQuant/psychquant-claude-plugins#131（逐 repo 評估「repo 即 plugin」推廣——決策表＋逐一執行或明記不遷）

  5. kiki830621
    closed this as completedon Aug 13, 2026
  6. kiki830621
    added a commit that references this issue on Sep 24, 2026

    chore: plugin 殼版本 0.12.0 → 0.13.0——送出新 skill akashic-fetch-fulltext；b…

    afebc91
  7. kiki830621
    added a commit that references this issue on Oct 7, 2026

    chore: akashic-mcp 0.13.3——殼版本升版讓 #613 之後的 skill 修改進得了快取；binary_versi…

    6f9d960
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions