Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
283e640
feat: akashic --version 印建置時的 commit,未戳記的建置印 unknown (#775)
kiki830621 Nov 9, 2026
b6718e3
feat: scripts/stamp-version.sh 在建置期間把 commit 寫進佔位檔,建完還原 (#775)
kiki830621 Nov 9, 2026
c21d368
feat: akashic-mcp plugin 加 SessionStart hook,CLI 過期或契約不足時提示 (#775)
kiki830621 Nov 9, 2026
2783369
docs: akashic-fetch-fulltext 第 0 步的建置指示改用戳記腳本 (#775)
kiki830621 Nov 9, 2026
cec5fec
docs: 例外 1 收 stamp-version.sh 與 check-cli.sh;--version 的兩面裁決 (#775)
kiki830621 Nov 9, 2026
e6927a6
chore: plugin 殼 0.13.13 → 0.13.14 與 CHANGELOG;0.13.13 已由 #613 b49 發布 …
kiki830621 Nov 9, 2026
236a1f6
fix: hook 的變數一律加大括號,UTF-8 locale 下全形標點不再吃掉變數名;測試改在 UTF-8 locale 跑 (#775)
kiki830621 Nov 9, 2026
7854f89
docs: #775 changelog 記下 UTF-8 locale 的亂碼與實機驗證 (#775)
kiki830621 Nov 9, 2026
1be7fc4
fix: 測試剝除 GIT_* 並登記、--version 不算寫入腿、hook 註解揭露 repo 路徑讀不到 (#775)
kiki830621 Nov 9, 2026
886ce15
chore: 版號表加 plugin 殼 0.13.14 的摘要 (#775)
kiki830621 Nov 9, 2026
36a966f
docs: #775 changelog 補上 rebase 後的實機結果 (#775)
kiki830621 Nov 9, 2026
ab5192e
fix: SessionStart 檢查看內容判定落後、只用 git plumbing、探測傳回結束碼 (#775)
kiki830621 Nov 10, 2026
8ab023a
fix: 戳記腳本拒絕非佔位值的檔、寫不進去就中止、未追蹤檔算 dirty (#775)
kiki830621 Nov 10, 2026
8819122
docs: verify r1 修正輪的 changelog、README 的 AKASHIC_SOURCE_DIR、版號表摘要 (#775)
kiki830621 Nov 10, 2026
3d86c8e
fix: 落後判定看每個 commit 動過什麼、關掉 fsmonitor、探測用使用者的 PATH (#775)
kiki830621 Nov 10, 2026
961b733
fix: 戳記腳本備份後再查備份、戳記帶標記、submodule 的未追蹤檔算 dirty (#775)
kiki830621 Nov 10, 2026
a3cfa0d
docs: verify r2 修正輪的 changelog、例外 1 的描述、README、版號表摘要 (#775)
kiki830621 Nov 10, 2026
887944a
fix: 探測的小 shell 指名 /bin/bash、檔頭照實寫 grafts 與被砍時的輸出 (#775)
kiki830621 Nov 10, 2026
c1acc06
docs: 分岔比對的成本寫成界線、改用 package 路徑時訊息說實話 (#775)
kiki830621 Nov 10, 2026
b96ecb1
docs: changelog 補上 verify r3 修正的驗證結果 (#775)
kiki830621 Nov 10, 2026
12b04e7
docs: verify r4 的改字——成本數字改用 C locale 的量測、被砍時留下什麼照實寫 (#775)
kiki830621 Nov 10, 2026
6a112fc
chore: 併入 main(#779 的 PR #787 已合併)、plugin 殼改升 0.13.15 (#775)
kiki830621 Nov 10, 2026
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
15 changes: 13 additions & 2 deletions .claude/rules/swift-is-the-implementation-language.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,19 @@

## 例外:可以不是 Swift 的檔案(封閉列舉,只有兩類,不得依性質相似類推第三類)

1. **在 Swift binary 存在之前就得先跑、或本身是外部工具約定入口的殼層**。目前恰為四個檔:
1. **在 Swift binary 存在之前就得先跑、或本身是外部工具約定入口的殼層**。目前恰為六個檔:
`.githooks/pre-push`、`.githooks/run-guards.sh`(git hook 與守衛入口)、
`plugin/bin/akashic-mcp-wrapper.sh`(下載 server binary)、`scripts/release-signed.sh`
(編排 `codesign`/`notarytool`)。**它們只做串接**——檢查 binary、依序呼叫、下載、編排外部
(編排 `codesign`/`notarytool`)、`scripts/stamp-version.sh`(建置期間把 commit 寫進
`Sources/akashic/BuildVersion.swift`、建完還原,#775)、`plugin/hooks/check-cli.sh`(akashic-mcp plugin 的
SessionStart hook,#775)。**它們只做串接**——檢查 binary、依序呼叫、下載、編排外部
CLI。領域判斷一旦出現在裡面,就移進 Swift。
**`plugin/hooks/check-cli.sh` 是這一句的具名例外**(使用者 2026-11-09 裁決,#775):它含判斷——這次建置與原始碼的內容
是否相同、兩者的祖先關係、基準上哪些 commit 動過內容不同的檔、比不出時改比檔案時間、契約數字的比較——但它判斷的對象就是 `akashic` binary 本身(不存在、過舊、卡住),
判斷者不能住在被判斷的 binary 裡;那些也不是 store 的領域判斷。它的行為測試寫在 Swift test target
(`Tests/AkashicCLITests/CheckCLIHookTests.swift`)。下面〈已移植〉的 `fetch-fulltext.sh` 處置相反,理由也正是這一點:
那支的判斷搬得進 `akashic`,因為 skill 跑它的時候 `akashic` 一定在。下一支想援用這個例外的殼層,要在這裡另外加列並寫明
它判斷的對象為什麼不能是 Swift,不從這一支類推。
2. **本規則成文前已存在的檔(grandfathered)**,逐檔列在下方〈既有檔〉。可以修 bug、可以
小改;**不得在它們旁邊新增同類檔案**,也不得把新功能長在它們裡面。大幅改寫時移植成
上表的 Swift 形式。
Expand Down Expand Up @@ -107,9 +115,12 @@ parity 測試不是「移植」而是**受測物不存在後退場**)。
| 2026-09-23~24 | akashic-fetch-fulltext skill 新增 5 支 Python 與 1 支 Python 測試(`verify_pdf.py` 等),在本規則成文之前 | 列入〈既有檔〉;移植成 `akashic` CLI 子命令由 #629 追蹤 |
| 2026-10-03~04 | #692 R3 把讀頁面的安全檢查寫成 `web-access.md` 裡約 175 行、要模型照抄進暫存目錄再執行的 Python(`check-read.py`:主機形狀驗證、UTF-16 截斷、逐碼位剔除),以「不適用」第 1 類(文件裡的指令列)辯護,規則檔沒改。R4 verify 四席指出那是依性質相似類推:第 1 類是呼叫工具的指令列;留在 Python 的理由(舊 CLI 會停)也不成立——同一個區塊本來就硬依賴 `akashic fulltext bot-signals --kind`。代價是實的:跑的是抄本、測試釘的是文件;它重寫一份 `UnsafeToEmitScalar`,macOS 的 `/usr/bin/python3`(3.9、Unicode 13)留下九個之後才指派的格式字元;`swift test` 因此需要 python3 | 移植成 `akashic web-read origin|landing|check`(`Sources/AkashicSkillTools/WebRead.swift`,剔除集合是 `UnsafeToEmitScalar`,b33 起加 noncharacter);文件裡要照抄進暫存檔的程式只剩讀頁面的 JS 運算式(單行的 `python3 -c` 指令列仍在,見第 1 類);「不適用」第 1 類補一句「不含要照抄執行的程式」 |
| 2026-10-05 | #692 b33 verify:上一列補的那一句寫成「不含:…的程式(含解析、驗證、比對邏輯的)」——括號裡是性質判準,而文件仍要模型把 `read-*.js` 寫進暫存檔、當 JS 執行(它含 `t.length > LIMIT` 的比較與截斷),落在邊界上沒有答案 | 拿掉性質限定詞;例外改成封閉列舉的一項(`read-*.js`,理由寫在第 1 類) |
| 2026-11-09 | #775:比照 safari-browser 給 akashic-mcp plugin 加 CLI 過期提示,需要兩支 shell——建置戳記腳本與 SessionStart hook。戳記腳本是例外 1 的原型(建置前就得跑、只做串接);hook 卻含判斷,照「含判斷者移進 Swift」本該移植,但它判斷的是 `akashic` binary 本身 | 使用者裁決修改例外 1:四個檔改六個,hook 以具名例外列入並寫明理由(判斷對象是 binary 本身);它的測試在 Swift test target |

## 語言組成(tracked,排除 `repos/`、`docs/`、`changelog/`、`openspec/`)

**2026-11-09(#775 branch 上量)**:Swift 681、Python 0、shell 6(恰為例外 1 的六個檔)。

**2026-09-29(#629 R1 修正後重量)**:Swift 511、Python 0、shell 4(含沒有副檔名的 `.githooks/pre-push`;恰為例外 1 的四個檔)。
第一版這裡寫 Swift 497,驗證席在同一個 commit 上重量得 501(R1 verify 第 20 則;497 是 rebase 之前量的)——**這個數字隨每個 commit 變動**(別的工作線也在加 Swift 檔),
不要照抄,重量。第一塊移植後是 472/9/6,成文當日(2026-09-24)是 372/11/11。量法:`git ls-files` 依副檔名計數,排除 `repos/`、`docs/`、`changelog/`、`openspec/`。
1 change: 1 addition & 0 deletions .githooks/plugin-shell-versions.txt
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,4 @@ plugin 0.13.11 1068c7a2921269065a4ead8079d4fc12b242d5ec707dc9608d3fae03c2c317f9
plugin 0.13.12 3c9aed7dc601ce97d62c861d576f644303cc4111b85b0962d08b76201e05918f
plugin 0.13.13 3171c0b774f05023109b16004f691c4512405947ebf3dfa8c04c84542c3665e6
plugin 0.13.14 b5a6f4f73a785f17754cc039362a4b4bce4c406331ee6d91037c69e50835977a
plugin 0.13.15 0d77d4d1b72078218157f378bc547ffc1472ef0238522c0f4a1feb60516ad10f
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -224,6 +224,7 @@ akashic export-tables --view iss -o out/ # view-scoped 關聯表匯出(#274
|---|---|
| `AKASHIC_HOME` | 覆寫 akashic home(預設 `~/.akashic`)。**同時決定 registry(`config.yaml`)與衍生 index(`index/<key>-<化身>.sqlite`)的位置**——兩者必須同源,否則會出現「registry 讀一個 home、index 寫另一個 home」的跨 profile 混用(#101 修正)。CLI / MCP / App 三面一致遵守 |
| `AKASHIC_LIBRARY` | 直接指定 library root,等同 `--library`。路徑已註冊時**反查 registry 帶 key**(#105)——同一個 store 不因開法不同而有兩份 index |
| `AKASHIC_SOURCE_DIR` | Akashic-Library 原始碼 checkout 的根目錄(預設 `~/Developer/Akashic-Library`)。只有 akashic-mcp plugin 的 SessionStart 檢查(`plugin/hooks/check-cli.sh`,#775)讀它:拿 `akashic --version` 說的建置 commit 跟那裡的 `origin/main`(上次 fetch 時;沒有這個 ref 才用 HEAD)比,CLI 落後時在開 session 時說出來。目錄不存在時只比 fulltext 契約;存在但不是 repo 的根目錄、或 PATH 上找不到 git 時會說明、不比對。判定看內容:分支自己撤掉 main 的某個改動時算最新(那是建置自己的改動;merge 時解衝突丟掉了 main 的修正也算);判定規則與已知的界線寫在 hook 檔頭。請寫絕對路徑(相對路徑是相對於開 session 時的工作目錄)。CLI、MCP、App 都不讀這個變數 |

Library root 的解析順序:`--library` → `$AKASHIC_LIBRARY` → `$AKASHIC_HOME/config.yaml`(`current` 指向的
`files:` 項)。三條路都會解析 registry key:前兩者對已註冊路徑**反查**(#105),未註冊才 keyless。
Expand Down
9 changes: 9 additions & 0 deletions Sources/akashic/BuildVersion.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
/// 這個 binary 是從哪一個 commit 建置的(#775)。`akashic --version` 印它。
///
/// 這個受追蹤的檔只放佔位值 `unknown`。`scripts/stamp-version.sh` 在建置期間把它改寫成 `git describe` 的結果
/// (裸的 `<12 位 hash>[-dirty]`),建完一定還原,所以一般的 `swift build`、`swift test` 讀到的都是 `unknown`,
/// 不會失敗。這一行不得手改成其他值,也不得 commit 戳記過的版本——值只能由那支腳本在建置期間寫入。
///
/// 讀它的是 akashic-mcp plugin 的 SessionStart hook(`plugin/hooks/check-cli.sh`):拿這個 commit 跟原始碼 checkout
/// 比,說出 CLI 落後幾個動到 package 原始碼的 commit;是 `unknown` 時改比檔案時間。
enum BuildVersion { static let value = "unknown" }
2 changes: 2 additions & 0 deletions Sources/akashic/CLI.swift
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,8 @@ struct AkashicCLI: ParsableCommand {
static let configuration = CommandConfiguration(
commandName: "akashic",
abstract: "Akashic-Library — 檔案為本的文獻整合系統",
// #775:建置時的 commit(`scripts/stamp-version.sh` 寫入;平常的建置是 `unknown`)。SessionStart hook 讀它判斷 CLI 是否過期
version: BuildVersion.value,
subcommands: [
ImportZotero.self, Validate.self, ExportBib.self,
ResolvePeople.self, Doctor.self, Query.self, Graph.self, Rename.self, RenamePerson.self, LibraryCmd.self, FileCmd.self,
Expand Down
14 changes: 14 additions & 0 deletions Tests/AkashicCLITests/CLIVersionTests.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
import XCTest

/// `akashic --version`(#775):印建置時的 commit(`scripts/stamp-version.sh` 寫進 `BuildVersion.swift`)。
///
/// 沒經過戳記腳本的建置——包括這支測試跑的建置——印佔位值 `unknown`、結束碼 0。比 #775 舊的 CLI 對這個旗標回 64
/// (ArgumentParser 的用法錯誤)。akashic-mcp plugin 的 SessionStart hook(`plugin/hooks/check-cli.sh`)把兩者分開處理:
/// `unknown` 比檔案時間;回 64 而比對的基準上已經有 `BuildVersion.swift`,就是必定落後,基準上還沒有才比檔案時間。
final class CLIVersionTests: XCTestCase {
func testUnstampedBuildPrintsThePlaceholder() throws {
let r = try CLITestHarness.run(["--version"], env: [:])
XCTAssertEqual(r.status, 0, r.output)
XCTAssertEqual(r.output.trimmingCharacters(in: .whitespacesAndNewlines), "unknown")
}
}
Loading
Loading