@stellar_ai/mcp_fossil_scm 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/admin.md CHANGED
@@ -1,9 +1,9 @@
1
1
  # Admin 能力(`-c a`)說明
2
2
 
3
3
  本文件對應 `src/tools/admin.ts`(實現)與 `src/core/fossil.ts`(執行器),描述 `fossil-scm` 在
4
- `-c a`(Admin)能力下暴露的 **11 個工具**、它們的確切行為、成功/失敗輸出形態,以及當前已知的邊界問題。
4
+ `-c a`(Admin)能力下暴露的 **12 個工具**、它們的確切行為、成功/失敗輸出形態,以及當前已知的邊界問題。
5
5
 
6
- 適用於 `@stellar_ai/mcp_fossil_scm@0.2.0` 及之後。
6
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.2` 及之後。
7
7
 
8
8
  > 執行要求:Node.js >= 20。包內是編譯後的 `dist/**/*.js`(無 source map、無 `.d.ts`)。
9
9
 
@@ -22,8 +22,8 @@
22
22
  | `fossil_push` | 把本地可分享的變更送到遠端倉庫 |
23
23
  | `fossil_pull` | 把遠端倉庫的可分享變更拉回本地 |
24
24
  | `fossil_sync` | 與遠端倉庫雙向交換可分享的變更 |
25
- | `fossil_rebuild` | 重建倉庫資料庫 |
26
25
  | `fossil_config` | 匯出 / 匯入 / 合併 / 拉取 / 推送 / 重設設定區 |
26
+ | `fossil_rebuild` | 重建倉庫資料庫 |
27
27
 
28
28
  `fossil_close`、`fossil_rebuild` 標記 destructive;`fossil_push`、`fossil_pull`、`fossil_sync`、`fossil_config` 標記 openWorld;`fossil_close`、`fossil_settings` 標記 idempotent。
29
29
 
@@ -68,7 +68,7 @@ FOSSIL_WORKSPACE=/path/to/workspace fossil-scm -c a
68
68
 
69
69
  | 參數 | 類型 | 必填/預設 | 說明 |
70
70
  | --- | --- | --- | --- |
71
- | `repository` | string | **必填** | 倉庫資料庫檔案路徑 |
71
+ | `repository` | string | **必填** | 倉庫資料庫檔案路徑,例如 `repos/app.fossil` |
72
72
 
73
73
  解析規則(`resolveRepoPath`):
74
74
 
@@ -138,6 +138,7 @@ Point `workspace` (or --workspace) at a directory that exists and retry.
138
138
  | `template` | string | — | 複製設定來源的倉庫檔(`--template`) |
139
139
  | `project_desc` | string | — | 寫入倉庫的專案描述(`--project-desc`) |
140
140
  | `date_override` | string | — | 初始 check-in 的時間(`--date-override`) |
141
+ | `sha1` | boolean | `false` | 用 SHA1 而非 SHA3-256 命名 artifact(`--sha1`) |
141
142
  | `reveal_secrets` | boolean | `false` | 原樣返回 admin 初始密碼(預設脫敏為 `***`) |
142
143
  | `workspace` | string | 見 §2.1 | 命令執行目錄 / 相對路徑基準 |
143
144
 
@@ -202,6 +203,8 @@ WORKSPACE: /tmp/ws2
202
203
  | `set_mtime` | boolean | `false` | `--setmtime`:把每個檔案的時間戳設成其 check-in 時間 |
203
204
  | `force_missing` | boolean | `false` | `--force-missing`:內容缺失時仍開啟 |
204
205
  | `workdir` | string | workspace | `--workdir`;**相對路徑以 workspace 為基準**解析成絕對路徑 |
206
+ | `repodir` | string | — | `repository` 是 URL 時,clone 下來的倉庫放在這個目錄(`--repodir DIR`) |
207
+ | `verbose` | boolean | `false` | `repository` 是 URL 時印出 clone 進度(`--verbose`) |
205
208
  | `workspace` | string | 見 §2.1 | 命令執行目錄 |
206
209
 
207
210
  執行:
@@ -287,14 +290,18 @@ WORKSPACE: /tmp/adoc/ws
287
290
  | 參數 | 類型 | 必填/預設 | 說明 |
288
291
  | --- | --- | --- | --- |
289
292
  | `repository_uri` | string | **必填** | 源倉庫 URL 或本地路徑 |
290
- | `target_file` | string | **必填** | 目標 `.fossil`;**相對路徑以 workspace 為基準**,父目錄自動建立 |
293
+ | `target_file` | string | **必填** | 目標倉庫檔,例如 `repos/app.fossil`;**相對路徑以 workspace 為基準**,父目錄自動建立 |
291
294
  | `http_proxy` | string | — | 傳給 `--proxy` |
292
295
  | `httpauth` | string | — | `user:pass`,傳給 `-B` |
293
296
  | `ssl_identity` | string | — | SSL 客戶端憑證檔(`--ssl-identity`) |
294
297
  | `ssh_command` | string | — | 當作 ssh 客戶端的命令(`-c`) |
298
+ | `transport_command` | string | — | 搬運訊息到遠端再搬回來的外部命令(`--transport-command`) |
295
299
  | `workdir` | string | — | 同時在這個目錄開 check-out(`--workdir`) |
296
300
  | `admin_user` | string | — | 把這個使用者設為管理員(`-A`) |
297
301
  | `nested` / `once` / `private` / `unversioned` / `verbose` | boolean | `false` | `--nested` / `--once` / `--private` / `-u` / `-v` |
302
+ | `no_compress` | boolean | `false` | 省掉額外的 delta 壓縮(`--nocompress`) |
303
+ | `no_open` | boolean | `false` | 只克隆,不開 check-out(`--no-open`) |
304
+ | `save_http_password` | boolean | `false` | 記住 HTTP 密碼,之後不再詢問(`--save-http-password`) |
298
305
  | `reveal_secrets` | boolean | `false` | 原樣返回輸出中的憑據 |
299
306
  | `workspace` | string | 見 §2.1 | 命令執行目錄 |
300
307
 
@@ -453,7 +460,7 @@ https://example.com/x.fossil
453
460
  ### 3.7 `fossil_push` / `fossil_pull` / `fossil_sync`
454
461
 
455
462
  ```bash
456
- fossil push [URL] [--all] [--private] [--once] [--verily] [-v] [--proxy P] [--httpauth U:P] [--ssl-identity F]
463
+ fossil push [URL] [--all] [--private] [--once] [--verily] [-v] [--proxy P] [--httpauth U:P] [--ssl-identity F] [-R REPO] [--transport-command CMD] [--no-http-compression] [--ipv4]
457
464
  fossil pull [URL] [--from-parent-project] [--project-code CODE] …同上的網路選項
458
465
  fossil sync [URL] [--unversioned] …同上的網路選項
459
466
  ```
@@ -469,6 +476,10 @@ fossil sync [URL] [--unversioned] …同上的網路選項
469
476
  | `proxy` | string | — | `--proxy` |
470
477
  | `httpauth` | string | — | `--httpauth` 的 `USER:PASS` |
471
478
  | `ssl_identity` | string | — | `--ssl-identity` |
479
+ | `transport_command` | string | — | 搬運訊息到遠端再搬回來的外部命令(`--transport-command`) |
480
+ | `repository` | string | check-out 的倉庫 | 直接指定要操作的倉庫檔(`-R`) |
481
+ | `no_http_compression` | boolean | `false` | HTTP 流量不壓縮(`--no-http-compression`) |
482
+ | `ipv4` | boolean | `false` | 連線只用 IPv4(`--ipv4`) |
472
483
  | `reveal_secrets` | boolean | `false` | 原樣顯示輸出裡的憑據 |
473
484
  | `workspace` | string | 見 §2.1 | — |
474
485
 
@@ -495,7 +506,48 @@ fossil 用 `\r` 覆寫同一行進度,因此 `Round-trips:` 可能連續出現
495
506
 
496
507
  ---
497
508
 
498
- ### 3.8 `fossil_rebuild`
509
+ ### 3.8 `fossil_config`
510
+
511
+ ```bash
512
+ fossil config export <area> <file>
513
+ fossil config import|merge <file>
514
+ fossil config pull|push <area> [<url>] [--overwrite]
515
+ fossil config reset <area>
516
+ ```
517
+
518
+ | 參數 | 類型 | 必填/預設 | 說明 |
519
+ | --- | --- | --- | --- |
520
+ | `action` | enum | **必填** | `export` / `import` / `merge` / `pull` / `push` / `reset` |
521
+ | `area` | enum | `export` / `pull` / `push` / `reset` 時必填 | `all` / `email` / `interwiki` / `project` / `shun` / `skin` / `ticket` / `user` / `alias` / `subscriber` |
522
+ | `file` | string | `export` / `import` / `merge` 時必填 | 要寫出或讀入的檔案 |
523
+ | `url` | string | 預設遠端 | `pull`/`push` 的來源或目的 |
524
+ | `repository` | string | check-out 的倉庫 | 直接指定要設定哪個倉庫檔(`-R`) |
525
+ | `overwrite` | boolean | `false` | `pull` 時以遠端內容覆蓋本地設定(`--overwrite`) |
526
+ | `workspace` | string | 見 §2.1 | — |
527
+
528
+ 缺少 `area` 或 `file` 時工具直接報錯:
529
+
530
+ ```
531
+ ERROR: `export` requires `file`.
532
+ ERROR: `reset` requires `area`.
533
+ ```
534
+
535
+ 真實輸出(`action: 'export'`、`area: 'ticket'`):
536
+
537
+ ```
538
+ $ fossil config export ticket /tmp/ticket-config.txt
539
+ (無輸出,exit 0)
540
+ $ head -3 /tmp/ticket-config.txt
541
+ # The "ticket" configuration exported from
542
+ # repository "/tmp/pw/repo.fossil"
543
+ # on 2026-11-17 02:53:53
544
+ ```
545
+
546
+ `pull` / `push` 走 600s 網路超時,其餘動作走一般超時。
547
+
548
+ ---
549
+
550
+ ### 3.9 `fossil_rebuild`
499
551
 
500
552
  ```bash
501
553
  fossil rebuild [--ifneeded] [--compress] [--compress-only] [--vacuum] [--stats]
@@ -505,7 +557,7 @@ fossil rebuild [--ifneeded] [--compress] [--compress-only] [--vacuum] [--stats]
505
557
 
506
558
  | 參數 | 類型 | 必填/預設 | 說明 |
507
559
  | --- | --- | --- | --- |
508
- | `repository` | string | 目前 check-out 的倉庫 | 要重建的倉庫檔;省略時由 check-out 決定 |
560
+ | `repository` | string | 目前 check-out 的倉庫 | 要重建的倉庫檔,例如 `repos/app.fossil`;省略時由 check-out 決定 |
509
561
  | `ifneeded` | boolean | `false` | 只在 schema 版本會改變時重建(`--ifneeded`) |
510
562
  | `compress` / `compress_only` | boolean | `false` | 一邊重建一邊壓縮 / 只做壓縮 |
511
563
  | `vacuum` / `analyze` | boolean | `false` | 重建後 `VACUUM` / `ANALYZE` |
@@ -535,44 +587,6 @@ $ fossil rebuild --compress --quiet
535
587
  Extra delta compression... none found
536
588
  ```
537
589
 
538
- ### 3.9 `fossil_config`
539
-
540
- ```bash
541
- fossil config export <area> <file>
542
- fossil config import|merge <file>
543
- fossil config pull|push <area> [<url>] [--overwrite]
544
- fossil config reset <area>
545
- ```
546
-
547
- | 參數 | 類型 | 必填/預設 | 說明 |
548
- | --- | --- | --- | --- |
549
- | `action` | enum | **必填** | `export` / `import` / `merge` / `pull` / `push` / `reset` |
550
- | `area` | enum | `export` / `pull` / `push` / `reset` 時必填 | `all` / `email` / `interwiki` / `project` / `shun` / `skin` / `ticket` / `user` / `alias` / `subscriber` |
551
- | `file` | string | `export` / `import` / `merge` 時必填 | 要寫出或讀入的檔案 |
552
- | `url` | string | 預設遠端 | `pull`/`push` 的來源或目的 |
553
- | `overwrite` | boolean | `false` | `pull` 時以遠端內容覆蓋本地設定(`--overwrite`) |
554
- | `workspace` | string | 見 §2.1 | — |
555
-
556
- 缺少 `area` 或 `file` 時工具直接報錯:
557
-
558
- ```
559
- ERROR: `export` requires `file`.
560
- ERROR: `reset` requires `area`.
561
- ```
562
-
563
- 真實輸出(`action: 'export'`、`area: 'ticket'`):
564
-
565
- ```
566
- $ fossil config export ticket /tmp/ticket-config.txt
567
- (無輸出,exit 0)
568
- $ head -3 /tmp/ticket-config.txt
569
- # The "ticket" configuration exported from
570
- # repository "/tmp/pw/repo.fossil"
571
- # on 2026-11-17 02:53:53
572
- ```
573
-
574
- `pull` / `push` 走 600s 網路超時,其餘動作走一般超時。
575
-
576
590
  ## 4. 典型流程
577
591
 
578
592
  ```text
package/docs/chat.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Chat 能力(`-c c`)工具說明
2
2
 
3
- 適用於 `@stellar_ai/mcp_fossil_scm@0.2.0` 及之後,fossil 2.21 實測。
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.2` 及之後,fossil 2.21 實測。
4
4
 
5
5
  `-c c` 註冊 4 個工具:`fossil_chat_url` / `fossil_chat_send` / `fossil_chat_pull` / `fossil_chat_read`。
6
6
 
package/docs/forum.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Forum 能力(`-c f`)工具說明
2
2
 
3
- 適用於 `@stellar_ai/mcp_fossil_scm@0.2.0` 及之後,fossil 2.21 實測。
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.2` 及之後,fossil 2.21 實測。
4
4
 
5
5
  `-c f` 註冊 3 個工具,**全部只讀**:`fossil_forum_list` / `fossil_forum_read` / `fossil_forum_search`。
6
6
 
package/docs/prompts.md CHANGED
@@ -7,14 +7,14 @@
7
7
  | --- | --- | --- |
8
8
  | `fossil-review-changes` | 讀 `fossil_status` / `fossil_changes` / `fossil_diff`,分組說明未提交的改動並建議提交訊息 | `v` |
9
9
  | `fossil-commit-workflow` | 用 `fossil_addremove`(先 `dry_run`)暫存、以 `fossil_diff` 確認、`fossil_commit` 提交、`fossil_timeline` 覆核 | `v` |
10
- | `fossil-ignore-conversion` | 先預覽 `.gitignore` → `ignore-glob` 的轉換、逐條讀 `NOTE:`,再寫入檔案並用 `fossil_extras` 驗證 | `v` |
11
- | `fossil-trace-change` | 以 `fossil_whatis` / `fossil_finfo` / `fossil_annotate` / `fossil_timeline` / `fossil_search` / `fossil_describe` 追一條變更的來歷 | `v` |
10
+ | `fossil-trace-change` | 以 `fossil_finfo` / `fossil_annotate` / `fossil_timeline` / `fossil_diff` / `fossil_describe` 追一個檔案的變更來歷 | `v` |
12
11
  | `fossil-bisect-hunt` | 標記 good/bad、反覆 `fossil_bisect` 收斂到出問題的 check-in,最後 `reset` 並 `fossil_update` 復原 | `v` |
12
+ | `fossil-ignore-conversion` | 先預覽 `.gitignore` → `ignore-glob` 的轉換、逐條讀 `NOTE:`,再寫入檔案並回報規則數 | `u` |
13
13
  | `fossil-sync-remote` | 用 `fossil_remote` 設定遠端,依序 `fossil_pull` / `fossil_push` / `fossil_sync` | `a` |
14
- | `fossil-repair-repository` | 用 `fossil_info` / `fossil_sql` 記錄現況,`fossil_rebuild` + `ifneeded: true` 判斷後再重建並比對 | `a` |
14
+ | `fossil-repair-repository` | 以 `fossil_rebuild` 依 `ifneeded` → `stats` → `compress` 判斷與重建,再回報結果 | `a` |
15
15
  | `fossil-ticket-triage` | 讀 `fossil_ticket_list`、分組,再用 `fossil_ticket_update` 更新正在處理的工單狀態 | `t` |
16
16
 
17
- 提示只在對應能力啟用時註冊;伺服器在至少一個提示可用時宣告 `prompts` 能力。
17
+ 每個提示只用一個能力組的工具,`需要的能力` 就是註冊它的條件;伺服器在至少一個提示可用時宣告 `prompts` 能力。
18
18
 
19
19
  ## 呼叫範例
20
20
 
package/docs/tickets.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Tickets 能力(`-c t`)工具說明
2
2
 
3
- 適用於 `@stellar_ai/mcp_fossil_scm@0.2.0` 及之後,fossil 2.21 實測。
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.2` 及之後,fossil 2.21 實測。
4
4
 
5
5
  `-c t` 註冊 4 個工具:`fossil_ticket_list` / `fossil_ticket_show` / `fossil_ticket_create` / `fossil_ticket_update`。
6
6
  (check-out 用 admin 的 `fossil_init` / `fossil_open`,組合啟用寫 `-c at`。)
package/docs/utils.md ADDED
@@ -0,0 +1,262 @@
1
+ # Utils 能力(`-c u`)工具說明
2
+
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.2` 及之後。所有行為都在 fossil 2.21 上實測。
4
+
5
+ `-c u` 註冊 7 個工具;要連 VCS 一起用 `-c uv`。
6
+
7
+ ---
8
+
9
+ ## 1. 能力概覽
10
+
11
+ | 工具 | 作用 |
12
+ | --- | --- |
13
+ | `fossil_cat` | `fossil cat <file> [-r REV]` |
14
+ | `fossil_grep` | `fossil grep <pattern> <files>` |
15
+ | `fossil_whatis` | `fossil whatis <name>` |
16
+ | `fossil_ignore_from_gitignore` | 讀 `.gitignore`,寫 `.fossil-settings/ignore-glob` |
17
+ | `fossil_search` | `fossil search [-a] [-n N] [-W WIDTH] <pattern>` |
18
+ | `fossil_artifact` | `fossil artifact <hash>` |
19
+ | `fossil_sql` | `fossil sql --readonly -json <query>` |
20
+
21
+ `fossil_ignore_from_gitignore` 只在 Node 裡轉換檔案內容;`fossil_cat`、`fossil_artifact`、`fossil_sql` 可用 `repository` 直接讀倉庫檔;`fossil_grep`、`fossil_whatis`、`fossil_search` 需要在 check-out 裡執行(見 §2)。除了 `fossil_ignore_from_gitignore`,其餘工具都標記 readOnly。
22
+
23
+ 重建整個倉庫資料庫的 `fossil_rebuild` 列在 Admin 能力。
24
+
25
+ ---
26
+
27
+ ## 2. 通用約定
28
+
29
+ - **`workspace`**:所有工具都接受,語義見 `docs/admin.md` §2.1。
30
+ - **直接讀倉庫檔**:`fossil_cat`、`fossil_artifact`、`fossil_sql` 給 `repository` 時不需要 check-out。
31
+ - **失敗格式** 與 admin 一致:
32
+
33
+ ```
34
+ ERROR: Fossil command failed (exit code 1).
35
+ <fossil stderr/stdout 原文>
36
+ COMMAND: fossil <argv>
37
+ WORKSPACE: /tmp/vd
38
+ ```
39
+
40
+ - **路徑參數原樣傳給 fossil**:以 `-` 開頭的檔名會被當成選項,呼叫方需自己加 `./` 前綴。
41
+
42
+ ---
43
+
44
+ ## 3. 工具
45
+
46
+ ### 3.1 `fossil_cat`
47
+
48
+ ```bash
49
+ fossil cat <file> [-r REV]
50
+ ```
51
+
52
+ 列印檔案內容。`revision` 省略時讀當前 check-out 的版本。
53
+
54
+ | 參數 | 類型 | 必填/預設 | 說明 |
55
+ | --- | --- | --- | --- |
56
+ | `file` | string | **必填** | 要列印的檔案 |
57
+ | `revision` | string | — | 指定 check-in 或版本(`-r`) |
58
+ | `repository` | string | — | `-R` 直接讀這個倉庫檔案,不需要 check-out |
59
+ | `workspace` | string | 見 admin §2.1 | — |
60
+
61
+ ### 3.2 `fossil_grep`
62
+
63
+ ```bash
64
+ fossil grep [-i] [-c] [-l] [--once] [-v] [-s] [--verbose] <pattern> <files...>
65
+ ```
66
+
67
+ 在檔案的**歷史版本**裡搜尋(由新到舊),不是工作區。
68
+
69
+ | 參數 | 類型 | 必填/預設 | 說明 |
70
+ | --- | --- | --- | --- |
71
+ | `pattern` | string | 必填 | POSIX 延伸正規表示式 |
72
+ | `files` | string[] | 必填,至少 1 | 要搜的檔案 |
73
+ | `ignore_case` | boolean | `false` | `-i` |
74
+ | `count` | boolean | `false` | `-c` 只印匹配檔案數 |
75
+ | `files_with_matches` | boolean | `false` | `-l` 每個匹配檔案印一個 artifact |
76
+ | `once` | boolean | `false` | `--once` 第一次命中就停 |
77
+ | `invert_match` | boolean | `false` | `-v` 只列沒有命中的檔案 |
78
+ | `no_messages` | boolean | `false` | `-s` 靜音讀檔訊息 |
79
+ | `verbose` | boolean | `false` | `--verbose` 邊分析邊回報 |
80
+ | `workspace` | string | 見 admin §2.1 | — |
81
+
82
+ 真實輸出(`fossil grep alpha a.txt`):
83
+
84
+ ```
85
+ == 2026-11-17 02:06 a.txt f3a27a552e checkin 86454b6394
86
+ 1:alpha
87
+ ```
88
+
89
+ 空輸出 → `No matches.`
90
+
91
+ ### 3.3 `fossil_whatis`
92
+
93
+ ```bash
94
+ fossil whatis [-f] [--type ci|t|w|g|e] [-v] <name>
95
+ ```
96
+
97
+ 把名字(標籤、分支、雜湊前綴、檔名)解析成 artifact。
98
+
99
+ | 參數 | 類型 | 必填/預設 | 說明 |
100
+ | --- | --- | --- | --- |
101
+ | `name` | string | 必填 | 要解析的名字 |
102
+ | `file` | boolean | `false` | `-f` 把 `name` 當檔名,查內容雜湊 |
103
+ | `type` | `ci` \| `t` \| `w` \| `g` \| `e` | — | `--type` 只匹配該 artifact 類型 |
104
+ | `verbose` | boolean | `false` | `-v` 附內部 record id |
105
+ | `workspace` | string | 見 admin §2.1 | — |
106
+
107
+ 真實輸出(`name: 'tip'`):
108
+
109
+ ```
110
+ name: tip
111
+ artifact: 86454b6394a3b2d2e2c0e2c7a6ee2f4e0b3b5a1a5f2e0d6a0e0f0a1b2c3d4e5f
112
+ size: 340 bytes
113
+ tags: trunk
114
+ type: Check-in by stellar on 2026-11-17 02:06:59
115
+ comment: second commit
116
+ ```
117
+
118
+ ### 3.4 `fossil_ignore_from_gitignore`
119
+
120
+ 把 `.gitignore` 的規則翻成 `ignore-glob` 認得的 glob 清單,可選擇寫成 `.fossil-settings/ignore-glob`。
121
+
122
+ | 參數 | 類型 | 必填/預設 | 說明 |
123
+ | --- | --- | --- | --- |
124
+ | `source` | string | `.gitignore` | 要轉換的檔案,相對 workspace |
125
+ | `write` | boolean | `false` | 寫入 `.fossil-settings/ignore-glob` |
126
+ | `overwrite` | boolean | `false` | 覆蓋已存在的 `.fossil-settings/ignore-glob` |
127
+ | `workspace` | string | 見 admin §2.1 | — |
128
+
129
+ | `.gitignore` 寫法 | 產出的 glob | 原因 |
130
+ | --- | --- | --- |
131
+ | `# 註解`、空行 | 丟棄 | `ignore-glob` 只有樣式 |
132
+ | `!name` | 略過,並在 `NOTE:` 列出 | `ignore-glob` 沒有否定 |
133
+ | `name` | `name`、`*/name` | 沒有斜線的規則在 git 是任意深度,fossil 比對完整路徑 |
134
+ | `*.log` | `*.log` | 開頭就是萬用字元,fossil 的 `*` 已跨目錄 |
135
+ | `dir/` | `dir` | fossil 命中目錄即略過整個子樹 |
136
+ | `/name` | `name` | 錨定在該 `.gitignore` 所在目錄,前綴沿用目錄名 |
137
+ | `a/**/b` | `a/b`、`a/*/b` | `**` 展開成零層與多層兩條 |
138
+ | 含逗號、空白、引號 | 用 `'…'` 或 `"…"` 包住 | fossil 的清單以空白與逗號分隔 |
139
+
140
+ fossil 的 `*` 會跨越 `/`,所以 `logs/*.log` 也會匹配 `logs/a/b.log`;git 的 `*` 只匹配一層。
141
+
142
+ 真實輸出:
143
+
144
+ ```
145
+ Converted 5 rules from .gitignore into 7 ignore-glob patterns.
146
+
147
+ node_modules
148
+ */node_modules
149
+ *.log
150
+ doc/gen
151
+ doc/*/gen
152
+ dist
153
+ */dist
154
+
155
+ NOTE: `**` in doc/**/gen expanded to 2 patterns.
156
+ NOTE: negation !keep.log skipped: ignore-glob has no negation, so the path stays visible.
157
+ ```
158
+
159
+ `write: true` 時第 2 行是 `Wrote .fossil-settings/ignore-glob.`;檔案落地後立刻生效,`fossil_extras`(VCS 能力)不再列出被忽略的路徑。
160
+
161
+ ### 3.5 `fossil_search`
162
+
163
+ ```bash
164
+ fossil search [-a] [-n N] [-W WIDTH] pattern
165
+ ```
166
+
167
+ | 參數 | 類型 | 必填/預設 | 說明 |
168
+ | --- | --- | --- | --- |
169
+ | `pattern` | string | **必填** | 要搜尋的字詞;全部都要命中 |
170
+ | `all` | boolean | `false` | 輸出全部命中,而不是只給高分者(`--all`) |
171
+ | `limit` | number | — | 最多輸出幾筆(`-n`) |
172
+ | `width` | number | — | 輸出寬度,`0` 表示不折行(`-W`) |
173
+ | `workspace` | string | 見 admin §2.1 | — |
174
+
175
+ 真實輸出:
176
+
177
+ ```
178
+ $ fossil search second
179
+ === 2026-11-17 ===
180
+ 02:24:18 [5f3e19ce7a] *CURRENT* second
181
+ +++ no more data (1) +++
182
+ ```
183
+
184
+ 沒有命中時 fossil 只印 `+++ no more data (0) +++` 並以 0 結束,工具改寫成 `No matches.`。
185
+
186
+ ### 3.6 `fossil_artifact`
187
+
188
+ ```bash
189
+ fossil artifact <ARTIFACT-ID> [-R FILE]
190
+ ```
191
+
192
+ | 參數 | 類型 | 必填/預設 | 說明 |
193
+ | --- | --- | --- | --- |
194
+ | `artifact` | string | **必填** | 工件雜湊,可用唯一前綴 |
195
+ | `repository` | string | — | `-R` 直接讀這個倉庫檔案,不需要 check-out |
196
+ | `workspace` | string | 見 admin §2.1 | — |
197
+
198
+ 真實輸出(檔案版本工件):
199
+
200
+ ```
201
+ $ fossil artifact 17995fe087b0f2ff8b60d47f4005eb1fbab7aa3bc9e3061b09f4a446a5f5dcb8
202
+ hi
203
+ more
204
+ ```
205
+
206
+ 對 check-in 的雜湊則會印出 manifest 原文(`D`/`F`/`P`/`U` 等卡片行)。
207
+ 雜湊可由 `fossil_finfo { mode: "id" }`(VCS 能力)、`fossil_whatis` 或 `fossil_leaves` 取得。
208
+
209
+ ### 3.7 `fossil_sql`
210
+
211
+ ```bash
212
+ fossil sql --readonly [-R FILE] -json "<query>"
213
+ fossil sql --readonly --no-repository FILE -json "<query>"
214
+ ```
215
+
216
+ | 參數 | 類型 | 必填/預設 | 說明 |
217
+ | --- | --- | --- | --- |
218
+ | `query` | string | **必填** | 以 `SELECT` / `WITH` / `PRAGMA` / `EXPLAIN` 開頭的語句;`LIMIT` 寫在 SQL 裡 |
219
+ | `repository` | string | — | `-R` 指定倉庫檔,例如 `repos/app.fossil`;不需要 check-out |
220
+ | `database` | string | — | 查一般的 SQLite 檔而非倉庫(`--no-repository`),例如 chat 存檔 |
221
+ | `workspace` | string | 見 admin §2.1 | — |
222
+
223
+ 輸出是製表符分隔的表格,最後一行是 `N row(s).`;空結果印 `No rows.`。資料庫以 `--readonly` 開啟,
224
+ `fossil sql` 的錯誤(例如 `no such column: name`)由工具轉成 `isError`。
225
+
226
+ 真實輸出:
227
+
228
+ ```
229
+ $ fossil sql --readonly -json "SELECT count(*) AS n FROM event"
230
+ n
231
+ 2
232
+
233
+ 1 row(s).
234
+ ```
235
+
236
+ 不是 `SELECT` / `WITH` / `PRAGMA` / `EXPLAIN` 開頭的語句在交給 fossil 前就被拒絕:
237
+
238
+ ```
239
+ ERROR: the query must start with SELECT, WITH, PRAGMA or EXPLAIN.
240
+ ```
241
+
242
+ ---
243
+
244
+ ## 4. 已知邊界
245
+
246
+ 1. **`fossil_grep` 搜歷史、`fossil_search` 搜註解**:前者逐版本掃描指定檔案,後者只比對 timeline / event 的
247
+ 註解,不含檔案內容、文件或論壇文章。
248
+ 2. **`ignore-glob` 沒有否定**:`!` 開頭的行只能略過並在 `NOTE:` 說明,被 git 重新納入的檔案在 fossil 仍被忽略。
249
+ 3. **含斜線的樣式在 fossil 會匹配更深的路徑**:`src/*.o` 也命中 `src/a/b.o`。
250
+ 4. **`fossil_ignore_from_gitignore` 一次只讀一個檔案**:子目錄的 `.gitignore` 要另外呼叫,`source` 指到該檔,
251
+ 產出的樣式自動帶上目錄前綴。
252
+
253
+ ---
254
+
255
+ ## 5. 原始碼位置
256
+
257
+ | 檔案 | 內容 |
258
+ | --- | --- |
259
+ | `src/tools/utils.ts` | 7 個工具的註冊、參數 schema、argv 拼裝 |
260
+ | `src/core/sql.ts` | `runSql`(`fossil sql --readonly -json` 的包裝與列轉換) |
261
+ | `src/core/gitignore.ts` | `.gitignore` → `ignore-glob` 的轉換規則 |
262
+ | `src/capabilities.ts` | 能力註冊表(`u` → 本檔案 7 個工具) |