Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .githooks/plugin-shell-versions.txt
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,5 @@ plugin 0.13.14 b5a6f4f73a785f17754cc039362a4b4bce4c406331ee6d91037c69e50835977a
plugin 0.13.15 0d77d4d1b72078218157f378bc547ffc1472ef0238522c0f4a1feb60516ad10f
plugin 0.13.16 acf8a5f6d54ff90ff76b324a5f9c408ab4bc38a38ff0fc9ce3ff5e5af1ef986b
plugin 0.13.17 c598d9e016a84021f96c07bb95583fe23e13f333428e92ddd10b3b1aefca7150
plugin 0.13.18 85e500da52faab6cf71c8bcc8f3ffa86024bd2607b44a46fb55c645ae7075ffb
plugins/akashic-discovery 0.2.18 afe7301483d7d1d470b5dd23b29ae7d87eb413139445300904a1a82f9f51917a
1 change: 1 addition & 0 deletions .githooks/protected-ratchet.txt
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@ docs/zero-instance-measurements.md
mcpb/manifest.json
plugin/.claude-plugin/plugin.json
plugin/rules/assertions-must-be-measured.md
plugin/rules/site-knowledge-goes-back-into-the-plugin.md
plugin/rules/source-of-truth-over-consent.md
plugin/skills/akashic-promote-literals/SKILL.md
plugins/akashic-discovery/.claude-plugin/plugin.json
4 changes: 3 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,11 +113,13 @@ Foresay 管**人機確認的格式與迴圈**,本 repo 的規則管**哪些寫
| [upstream-first-bibliographic-updates.md](.claude/rules/upstream-first-bibliographic-updates.md) | **文獻資料更新一律從上游 store 開始,交付層只投影不修正**——投影只能選欄、改名、剝除隱私、加標記欄,不得改變事實陳述;上游暫時修不了才可遮蔽,且必須開 issue 註明號碼、遮蔽是暫時的;反例是一次下游交付(R2)在交付層遮蔽離職博後被標現職等三個資料問題,之後才回頭修 store(#599)|

> **plugin 另有自己的規則目錄。** `plugin/rules/` 隨 plugin 走(plugin 安裝到哪,規則就在哪),
> 由 skill 以相對路徑引用——**不像上表那樣自動注入**。目前兩條:
> 由 skill 以相對路徑引用——**不像上表那樣自動注入**。目前三條:前兩條是
> [`assertions-must-be-measured`](plugin/rules/assertions-must-be-measured.md),管「寫下一句可能是錯的話
> 之前先回答四個問題」(不是分類法——理由見該檔);
> [`source-of-truth-over-consent`](plugin/rules/source-of-truth-over-consent.md),管「寫入的依據是 source of truth、
> 不是同意」——使用者要的與 source of truth 不符時改成正確的再寫,使用者可以提供證據、不能提供授權(#642)。
> 第三條是 [`site-knowledge-goes-back-into-the-plugin`](plugin/rules/site-knowledge-goes-back-into-the-plugin.md),管「碰網站的 skill 量到的
> 站別做法,在回報之前寫回 plugin;改動合併之後同一個工作階段更新安裝的 plugin 與 CLI」(#822)。
> 刻意不列進上表:那張表的語意是「自動注入的 repo 規則」,
> 混進去會讓那個性質變成謊話(#407)。
>
Expand Down
1 change: 1 addition & 0 deletions Sources/akashic-guards/AuditGuardsMutationsData.swift
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ let agmCases: [AGMCase] = [
// 「移植時的新舊差分(不在 repo)」,於是這條分支沒有任何東西釘住。刪光 `plugin/rules/` 底下的 `.md`(目錄還在)即得那個狀態。
AGMCase(desc: "coverage④:規則目錄在、一條 .md 規則都沒有(空集合不得冒充通過)", guardRel: "akashic-guards rule-coverage", edits: [
AGMEdit(path: "plugin/rules/assertions-must-be-measured.md", kind: "delete", a: "", b: ""),
AGMEdit(path: "plugin/rules/site-knowledge-goes-back-into-the-plugin.md", kind: "delete", a: "", b: ""),
AGMEdit(path: "plugin/rules/source-of-truth-over-consent.md", kind: "delete", a: "", b: ""),
], expect: ["沒有任何 .md 規則檔"]),
AGMCase(desc: "numbers:把某個數字唯一的行內時間錨拿掉", guardRel: "akashic-guards measured-numbers-audit", edits: [
Expand Down
29 changes: 29 additions & 0 deletions changelog/2026-11-20-site-knowledge-rule-822.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# #822:量到的站別做法要寫回 plugin(plugin 殼 0.13.17 → 0.13.18,契約版本不變)

使用者 2026-11-20 17:26(+08:00),正在用 `akashic-fetch-fulltext` 抓一批全文時:「akashic 的plugin要有一個rule是每次更新pdf取用方式都要更新到plugin上」。之後以選單問了三題,回答都是選單上的選項文字(#822 的兩則 Decision comment):

| 問題 | 回答 | 是不是選單上標成建議的那一個 |
|---|---|---|
| 「更新到 plugin 上」是寫回檔案,還是發布到安裝的版本 | 兩者都要 | 是 |
| 什麼時候寫回 | 整批結束、回報之前 | 是 |
| 範圍 | 所有碰網站的 skill | 不是(建議的是只管取全文)|

## 文件

- `plugin/rules/site-knowledge-goes-back-into-the-plugin.md`(新):六條。第 1、3、4 條是封閉列舉(什麼算要寫回的更新、寫到哪個檔、誰來寫);第 6 條是合併之後更新安裝的版本,只適用有原始碼 repo 的維護者,而且合併與更新各自仍要使用者確認。規則自己寫明三件做不到的事:它不自動載入(靠各 skill 引用,守衛只保證連結在)、一般安裝的使用者不送出就到不了 plugin、沒有檢查會發現「量到了卻沒寫」。
- `plugin/skills/akashic-fetch-fulltext/SKILL.md`:第 7 步加「回報之前,把這一批量到的寫回 plugin」;〈相關〉加這條規則;`html-page` 一列括號裡 Wiley epdf 的例子改成兩次量測各自的結果。
- `plugin/skills/akashic-bootstrap/references/web-access.md`:〈其他〉加一點,讓每一個照它取得的 skill 都讀得到這條義務。
- 其餘九個 skill 的 `SKILL.md`:各加一行指向這條規則。規則覆蓋的守衛(`run-guards.sh` 的 rule coverage)要求每一條 plugin 規則都被每一個 skill 以可解析的相對路徑引用;第一次跑守衛時九個 skill 缺這個連結。`akashic-merge-twins`、`akashic-promote-literals`、`akashic-verify-work` 沒有自己的網頁取得步驟,那一行照實這樣寫。
- `plugin/skills/akashic-fetch-fulltext/references/publishers.md`:新增〈2026-11-20 的實測〉一節(九篇、六個站,每一列只有表裡寫的篇數);規則表與先前各節裡被這一批推翻或補上的六處加註。
- `CLAUDE.md`:plugin 規則的說明由兩條改成三條。
- `plugins/akashic-discovery/.claude-plugin/plugin.json` 0.2.17 → 0.2.18 與 `.githooks/plugin-shell-versions.txt` 兩列:`akashic-discovery` 的 `rules/` 連到 `plugin/rules`,新規則讓它的殼內容變了;兩個殼都照 `akashic-guards plugin-shell-version` 印出的摘要接列。

## 這一批量到、但沒有因此改流程的事

- 視窗裡出現顯示 PDF 的分頁之後,`documents --json` 的 `blocking_dialog` 對整個視窗每一次都讀成 `unknown`/`incomplete`(PsychQuant/safari-browser#345,2026-11-20 的實測已補在那一張)。SKILL 第 3 步「按之前不是 `clear` 就不按、仍然 `unknown` 就停下整批」照這個觀察會在第一個 `pdf-shown` 之後擋下後面每一次按。那條規則沒有改:它是往停的方向定的,要不要放寬是使用者的裁決。
- Safari 的下載位置設成固定資料夾時,下載鈕按下去不跳儲存面板。開始前提醒或檢查這個設定是 #823,使用者決定等 PsychQuant/safari-browser#388(讀出這個設定)落地再做,這一次沒有動。
- 存進 store 的 provenance note 寫錯時沒有更正的入口:#824。

## 驗證

只改 Markdown 與 `plugin.json` 的版本號。釘住 SKILL 與 publishers.md 文字的測試與守衛的結果寫在 #822 的實作留言。
2 changes: 1 addition & 1 deletion plugin/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "akashic-mcp",
"version": "0.13.17",
"version": "0.13.18",
"binary_version": "0.13.0",
"description": "Akashic-Library MCP server — file-based canonical literature store: search, relations, graph, derived-layer writes (tags/status/links/person updates), person & organization resolution, divergence recording with judgement, resolution verdicts (confirm/reject with four-state counts incl. checked-undecided, no ratios), Zotero one-way pull, author-list replacement from a work's own full text. Store format 23.",
"author": {
Expand Down
10 changes: 10 additions & 0 deletions plugin/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# Changelog

## #822 — 量到的站別做法要寫回 plugin(2026-11-20):plugin 殼 0.13.17 → 0.13.18,契約版本不變(13)

使用者 2026-11-20 的指示與三個選擇;細節在 `changelog/2026-11-20-site-knowledge-rule-822.md`。**只改文件,沒有改 `akashic` CLI**:SKILL 第 0 步要求的契約版本仍是 13。

- 新規則 `rules/site-knowledge-goes-back-into-the-plugin.md`:碰網站的 skill 在一批做完、回報之前,把量到的站別做法寫回 plugin(什麼算、寫到哪個檔、誰來寫、要帶哪些欄位都是封閉列舉);改動合併之後,同一個工作階段把安裝的 plugin 與 CLI 更新到合併後的版本。`akashic-fetch-fulltext` 第 7 步與 `akashic-bootstrap` 的 `web-access.md`〈其他〉引用它;其餘九個 skill 的 `SKILL.md` 各加一行指向它(規則覆蓋的守衛要求每一條 plugin 規則都被每一個 skill 引用),不自己讀網站的三個 skill 寫明這一點。
- `akashic-fetch-fulltext` 的 `references/publishers.md` 新增〈2026-11-20 的實測〉:合併後的流程第一次用在真的出版商網站,九篇、六個站(SAGE、Wiley 的學會子網域、Cambridge Core、Taylor & Francis、Oxford Academic、SpringerLink),以及對話框探測在出現 PDF 分頁之後整個視窗讀成 `unknown` 的觀察(PsychQuant/safari-browser#345)。
- 被這一批推翻的舊句加註、不刪:Wiley 的 epdf 閱讀器「讀不到任何下載鈕」(那一篇讀得到)、SAGE「每一篇最後都要使用者按一次儲存」(下載位置是固定資料夾時不必)。SKILL 的 `html-page` 一列括號裡的例子跟著改。
- `akashic-discovery` 的殼 0.2.17 → 0.2.18:它的 `rules/` 是指向 `plugin/rules` 的連結,多了一條規則就是殼的內容變了(`akashic-guards plugin-shell-version` 要求升版),skill 本身沒有改。
- **沒有改的**:按之前讀到 `unknown` 就停的那條處置規則。這一批的觀察顯示它會讓第一個 PDF 分頁之後需要按的每一篇都停下來,要不要改等使用者裁決。

## #772 — `fetch` 鎖在開頭選定的視窗,別的 profile 的視窗開著不再停(2026-11-19):plugin 殼維持 0.13.17(同一條分支、還沒推上 main),契約版本 11 → 12

使用者 2026-11-19 09:24、09:25 的決定;細節在 `changelog/2026-11-19-fetch-window-id-772.md`。**需要新的 `akashic` CLI 與 safari-browser 2.9.0 以上**:SKILL 第 0 步要求契約版本 12。
Expand Down
79 changes: 79 additions & 0 deletions plugin/rules/site-knowledge-goes-back-into-the-plugin.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# 量到的站別做法要回到 plugin——不留在對話、暫存腳本或個人記憶裡

適用於本 plugin **每一個讀外部網頁或 web API 的 skill**(使用者 2026-11-20:範圍是所有碰網站的 skill,不只取全文)。

不適用於不碰網站的工作(只讀寫 store 的 skill 步驟),也不適用於「這一筆資料查到什麼」——那是 store 的內容,照 [`source-of-truth-over-consent`](source-of-truth-over-consent.md) 寫進 store,不是這條規則管的事。

## 規則

### 1. 什麼算要寫回的更新(封閉列舉,只有這三類,不得依性質相似類推第四類)

| # | 類別 | 例子(2026-11-20 那一批) |
|---|---|---|
| 1 | 某個站量到了 plugin 還沒有紀錄的行為:哪個連結通到哪裡、工具的結束碼與交接原因、按了之後檔案落在哪裡、沒有權限時頁面上的字 | Cambridge Core 上的 Psychometrika:PDF 連結導航之後分頁不離開摘要頁,頁面寫「Get access」「Add article to cart」 |
| 2 | 量到的與 plugin 寫的不同 | Wiley 的 epdf 閱讀器:文字寫 `snapshot -i` 讀不到任何下載鈕,那一篇讀得到 |
| 3 | 流程照字面做不到,或照字面做會得到流程自己沒料到的結果 | 視窗裡出現顯示 PDF 的分頁之後,對話框探測把整個視窗讀成 `unknown`,後面每一下「按之前先看對話框」都會停 |

你自己漏做一步(文字有寫、執行時沒照做)不屬於這三類:那一批的回報照實寫漏了什麼,不改 plugin。

### 2. 什麼時候寫

**一批做完、向使用者回報之前**(使用者 2026-11-20)。回報裡列出寫了什麼:哪個檔、加了或改了哪一列。批次中途不停下來改檔。

### 3. 寫到哪裡(封閉列舉)

| 量到的是 | 寫進 |
|---|---|
| 出版商或網站的行為,由 `akashic-fetch-fulltext` 量到 | `skills/akashic-fetch-fulltext/references/publishers.md`:依日期開一節,一站一列 |
| Safari 或 safari-browser 本身的行為(分頁開在哪裡、對話框與面板讀起來是什麼) | `skills/akashic-fetch-fulltext/references/safari-measurements.md`;同時在 safari-browser 的 repo 查有沒有既有的 issue,有就把這次量到的補在那一張,沒有就照下面〈誰來寫〉的 (b) 處理 |
| 期刊網站的行為,由 `akashic-venue-works` 量到 | `skills/akashic-venue-works/references/site-access.md` |
| web API 或名冊、個人頁的行為,由其他經 `web-access.md` 取得的 skill 量到 | `skills/akashic-bootstrap/references/` 下講那個來源的檔(作品來源在 `work-sources.md`,人的來源在 `person-sources.md`,Semantic Scholar 在 `semantic-scholar.md`);取得程序本身的行為寫進 `web-access.md` |

表裡沒有的組合,先在這張表加一列再寫,不要挑一個看起來相近的檔。

**與 `SKILL.md` 的句子不同時,同一個變更裡改那一句**,並寫明是哪一天的哪一次量測。舊的列與舊的句子加註、不刪:它們是當時量到的事實,被推翻的是「現在仍然如此」。

**會改變流程怎麼判的句子不在這條規則的授權內。** 量到的事實讓某條處置規則顯得不對時(例如第 1 條第 3 類的例子),寫下事實、指出它碰到哪一條,處置規則本身怎麼改交給使用者裁決。

### 4. 誰來寫(封閉列舉,依這個工作階段手上有什麼)

| # | 情況 | 做法 |
|---|---|---|
| (a) | 這個工作階段讀得到 plugin 的原始碼 repo,而且使用者是它的維護者 | 在 repo 的功能分支上改檔、commit。推送、開 PR、合併各自照使用者自己的確認規則;本規則不授權其中任何一步 |
| (b) | 其他(一般安裝:只有 Claude Code 管理的 plugin 安裝目錄,不改它) | 把同樣的內容寫成回報裡的一節「要寫回 plugin 的觀察」,照第 5 條的欄位寫;問使用者要不要把它送到 plugin 的 repo(開 issue 是把內容送出這台機器,由使用者決定,內文先過隱私檢查) |

### 5. 怎麼寫:證據範圍

每一列帶:日期、主機(學會或子刊的子網域照實寫,不寫成母站)、幾篇、工具的結果(結束碼、交接原因)、之後做了什麼與看到什麼、環境(safari-browser 版本、`akashic fulltext contract` 的值)。

- 量到一篇就寫一篇,不寫成「這一站都這樣」。
- 原因是推論、或來自使用者的說明時,照實標明,並寫出沒有做的對照。
- 權限因機構而異:「取得成功」「沒有權限」都只代表那個網路、那一天。

每一句都是關於世界的斷言,寫之前照 [`assertions-must-be-measured`](assertions-must-be-measured.md) 的四個問題過一次。

### 6. 寫進 repo 之後,要到達實際在用的版本(只適用第 4 條的 (a))

取得方式的改動合併進預設分支之後,**同一個工作階段**把這台機器上安裝的 plugin 與 `akashic` CLI 更新到合併後的版本,並確認:plugin 的版本號、`akashic fulltext contract` 印的值,都是合併後的。

- 合併與更新安裝的版本,各自要使用者確認;這一條規定的是「不要停在合併之前就當成做完」,不是讓它們自動發生。
- 沒有更新完就結束時,回報寫明安裝的還是哪一版、差在哪幾項。
- skill 的版本檢查擋下舊的 CLI 時,處置是更新 CLI;不請使用者配合舊版才有的限制。

## 為什麼(2026-11-20,同一天、同一個工作階段的兩種落差)

**安裝的版本落後。** 安裝的 CLI 印 `fulltext-contract 10`,而「別的 profile 的視窗開著就停」這個限制在分支上已經依使用者前一天的裁決拿掉。舊的 `fetch` 仍然停下,Claude 因此請使用者去關視窗;使用者指出那個限制早就拿掉了,之後才合併、更新。第 6 條防的是這個。

**量到的沒有寫回去。** 更新之後在真的出版商網站上抓九篇全文,量到的事有三件與 plugin 的文字不同或 plugin 沒有(第 1 條表裡的三個例子),另外四個站的結果是 plugin 第一次有導航之後的實測。這些原本只在那個工作階段的對話與暫存腳本裡。使用者當場說:

> 「akashic 的plugin要有一個rule是每次更新pdf取用方式都要更新到plugin上」

問他要的是「寫回檔案」還是「發布到安裝的版本」時,他選了兩者都要;範圍選了所有碰網站的 skill;時間點選了整批結束、回報之前(PsychQuant/Akashic-Library#822)。

**不寫回去的代價是下一次照舊的文字做。** 站別紀錄寫得比實際保守,能取得的全文會被列成「取不到」或多交給使用者一次;寫得比實際寬鬆,Claude 會照過時的步驟對網站動作。兩種都不會報錯。

## 這條規則做不到的事

- 它不讓規則自己被讀到:`plugin/rules/` 不自動載入,要靠各 skill 引用它。每個 skill 的 `SKILL.md` 都有一行指向本檔,repo 的守衛只檢查那個連結在、路徑解析得到;寫在回報步驟裡的只有 `akashic-fetch-fulltext` 第 7 步與 `web-access.md`〈其他〉。skill 執行時有沒有讀、有沒有照做,沒有東西檢查。
- 第 4 條的 (b) 只做到把觀察交到使用者手上;他不送出,plugin 就不會知道。
- 沒有檢查會發現「量到了卻沒寫」。
2 changes: 2 additions & 0 deletions plugin/skills/akashic-bootstrap/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,8 @@ DOI 識別「註冊的物件」,篇名識別「作品」,store 的 work 記

**寫入的依據是 source of truth,不是同意。** 使用者要求的值與作品本身、權威來源對不上時,改成正確的再寫,乾跑報告逐筆寫出「要求/依據/實際寫入」;查不到就不寫——見 [`source-of-truth-over-consent`](../../rules/source-of-truth-over-consent.md)。

**量到的站別做法要寫回 plugin。** 一批做完、回報之前,把這一批量到的網站或 API 行為(plugin 還沒有紀錄的、與 plugin 寫的不同的、照字面做不到的一步)寫回 plugin,並在回報列出寫了什麼(#822)——見 [`site-knowledge-goes-back-into-the-plugin`](../../rules/site-knowledge-goes-back-into-the-plugin.md)。

## 常見情境

| 使用者說 | 路徑 |
Expand Down
1 change: 1 addition & 0 deletions plugin/skills/akashic-bootstrap/references/web-access.md
Original file line number Diff line number Diff line change
Expand Up @@ -330,6 +330,7 @@ grep -q '[^[:space:]]' "<W>/r-$K.txt" || { echo "empty read - read failed" >&2;

- **持久狀態變更先問**:清 cache、註銷 service worker、改 cookie 或 storage,先說明意圖、取得同意再做。
- **不代按登入、授權、「接受」之類的按鈕**:那是使用者本人的操作。
- **量到的站別做法要寫回 plugin**(使用者 2026-11-20,#822):一批做完、向使用者回報之前,這一批裡量到 plugin 還沒有紀錄的網站或 API 行為、與 plugin 寫的不同的行為、或本檔照字面做不到的一步,照 [`site-knowledge-goes-back-into-the-plugin`](../../../rules/site-knowledge-goes-back-into-the-plugin.md) 寫回去(寫到哪個檔、誰來寫、要帶哪些欄位都在那一條),並在回報列出寫了什麼。這一條對每一個照本檔取得的 skill 都適用。
- **用完的分頁**:整個 run **沒有**觸發中止條款時,用同一把鎖關掉自己開的分頁(每個站一個):

```bash
Expand Down
Loading
Loading