@stellar_ai/mcp_fossil_scm 0.1.3 → 0.2.0

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/vcs.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # VCS 能力(`-c v`)工具說明
2
2
 
3
- 適用於 `@stellar_ai/mcp_fossil_scm@0.1.3` 及之後。所有行為都在 fossil 2.21 上實測。
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.0` 及之後。所有行為都在 fossil 2.21 上實測。
4
4
 
5
5
  `-c v` 註冊 40 個工具;要連 admin 一起用 `-c av`。
6
6
 
@@ -58,9 +58,9 @@
58
58
 
59
59
  ## 2. 通用約定
60
60
 
61
- - **`workspace`**:所有工具都接受,語義見 `docs/admin.md` §2.1。倉庫檔案不由這些工具指定——
62
- 它們作用於 `workspace` 裡已經 open 的 check-out(`.fslckout`)。
63
- - **沒有 check-out 時報錯**:fossil 原文 `use --repository or -R to specify the repository database`,
61
+ - **`workspace`**:所有工具都接受,語義見 `docs/admin.md` §2.1。工具作用於 `workspace` 裡已經 open 的
62
+ check-out(`.fslckout`)。
63
+ - **需要 check-out**:缺 check-out 時 fossil 回 `use --repository or -R to specify the repository database`,
64
64
  包裝為 `isError: true`。
65
65
  - **失敗格式** 與 admin 一致:
66
66
 
@@ -73,7 +73,7 @@ WORKSPACE: /tmp/vd
73
73
 
74
74
  - **空輸出**:不同工具給不同的提示(`No differences found.` / `No untracked files.` / `No events.` 等),
75
75
  見各工具小節。
76
- - **路徑參數不插入 `--`**:以 `-` 開頭的檔名會被 fossil 當成選項,需要呼叫方自行加 `./` 前綴。
76
+ - **路徑參數原樣傳給 fossil**:以 `-` 開頭的檔名會被當成選項,呼叫方需自己加 `./` 前綴。
77
77
 
78
78
  ---
79
79
 
@@ -84,17 +84,28 @@ WORKSPACE: /tmp/vd
84
84
  一次呼叫併發執行兩條命令,輸出分兩段:
85
85
 
86
86
  ```bash
87
- fossil status [-b]
88
- fossil extra [--dotfiles] [--ignore GLOBS] # cwd = workspace,兩條並行
87
+ fossil status|changes [--dotfiles] [--ignore GLOBS] [--hash] [--abs-paths|--rel-paths]
88
+ [--edited|--updated|--changed|--missing|--added|--deleted|--renamed|--conflict
89
+ |--meta|--unchanged|--all|--differ|--extra ...] [--classify] [--header] [-v]
90
+ fossil extra [--dotfiles] [--ignore GLOBS] # cwd = workspace,未指定 select 時並行
89
91
  ```
90
92
 
91
93
  | 參數 | 類型 | 必填/預設 | 說明 |
92
94
  | --- | --- | --- | --- |
93
- | `brief` | boolean | `false` | `-b`:只輸出狀態關鍵字 |
94
- | `dotfiles` | boolean | `false` | `extra` 時包含點檔案 |
95
+ | `brief` | boolean | `false` | 只列出變更檔案清單(`fossil changes`) |
96
+ | `dotfiles` | boolean | `false` | 包含點檔案(`--dotfiles`) |
95
97
  | `ignore` | string | — | `--ignore` 逗號分隔的 glob |
98
+ | `select` | string[] | — | 只回報這些變更類型:`edited`、`updated`、`changed`、`missing`、`added`、`deleted`、`renamed`、`conflict`、`meta`、`unchanged`、`all`、`differ`、`extra` |
99
+ | `classify` | boolean | `false` | 每行開頭標出變更類型(`--classify`);`brief` 時才有作用 |
100
+ | `hash` | boolean | `false` | 用雜湊而非大小+mtime 判斷狀態(`--hash`) |
101
+ | `header` | boolean | `false` | 非空報告前印倉庫名(`--header`);`brief` 時才有作用 |
102
+ | `verbose` | boolean | `false` | 空報告時印 `(none)`(`-v`);`brief` 時才有作用 |
103
+ | `abs_paths` | boolean | `false` | 絕對路徑(`--abs-paths`) |
104
+ | `rel_paths` | boolean | `false` | 相對於目前目錄的路徑(`--rel-paths`) |
96
105
  | `workspace` | string | 見 admin §2.1 | — |
97
106
 
107
+ 指定 `select` 且含 `extra` 或 `differ` 時,未跟蹤檔案已在同一段輸出裡,工具只跑一條命令。
108
+
98
109
  真實輸出(乾淨 check-out):
99
110
 
100
111
  ```
@@ -117,7 +128,8 @@ comment: first (user: stellar)
117
128
 
118
129
  ```bash
119
130
  fossil diff [--from X] [--to Y] [--branch B] [-ci C] [--brief] [--numstat]
120
- [-c N] [-y] [-v] [--undo] [-w] [files...]
131
+ [-c N] [-y] [-v] [--undo] [-w] [-Z] [-i] [--unified] [-h] [--json] [-W N]
132
+ [files...]
121
133
  ```
122
134
 
123
135
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -133,7 +145,13 @@ fossil diff [--from X] [--to Y] [--branch B] [-ci C] [--brief] [--numstat]
133
145
  | `side_by_side` | boolean | `false` | `-y` 並排顯示 |
134
146
  | `verbose` | boolean | `false` | `-v` 完整印出新增或刪除的檔案內容 |
135
147
  | `undo` | boolean | `false` | `--undo` 與 undo 緩衝區比較 |
136
- | `ignore_whitespace` | boolean | `false` | `-w` |
148
+ | `ignore_whitespace` | boolean | `false` | `-w` 忽略空白差異 |
149
+ | `ignore_trailing_space` | boolean | `false` | `-Z` 忽略行尾空白差異 |
150
+ | `internal` | boolean | `false` | `-i` 用內建 diff |
151
+ | `unified` | boolean | `false` | `--unified` 輸出 unified patch |
152
+ | `versions_header` | boolean | `false` | `-h` 在標頭列出比較的版本 |
153
+ | `json` | boolean | `false` | `--json` 以 JSON 輸出 |
154
+ | `width` | number | — | `-W` 並排顯示的行寬(≥20) |
137
155
  | `workspace` | string | 見 admin §2.1 | — |
138
156
 
139
157
  不給版本時是“工作區 vs 最近一次 check-in”。版本名寫錯時 fossil 報
@@ -189,8 +207,8 @@ $ fossil finfo -s a.txt
189
207
  unchanged 5f3e19ce7a
190
208
  ```
191
209
 
192
- `-n` / `--offset` / `-b` 只在 `log` 模式送出;fossil 對 `finfo -i -n 20` 會回
193
- `unrecognized command-line option or missing argument: -n`。
210
+ `-b` / `-n` / `--offset` 只在 `log` 模式送出,`-r` 只在 `id` 與 `print` 模式送出,`-v` 只在 `id` 模式送出;
211
+ 其餘組合 fossil 會回 `unrecognized command-line option or missing argument`。
194
212
 
195
213
  ### 3.5 `fossil_extras`
196
214
 
@@ -214,6 +232,7 @@ fossil extras [--dotfiles] [--ignore GLOBS] [--abs-paths|--rel-paths] [--header]
214
232
 
215
233
  ```bash
216
234
  fossil timeline -n <limit> [-p PATH] [-t TYPE] [-b BRANCH] [-c] [WHEN CHECKIN] [-F FORMAT] [-v]
235
+ [--offset N] [-W N]
217
236
  ```
218
237
 
219
238
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -227,6 +246,8 @@ fossil timeline -n <limit> [-p PATH] [-t TYPE] [-b BRANCH] [-c] [WHEN CHECKIN] [
227
246
  | `checkin` | string | — | `when` 相對的 check-in 雜湊或日期 |
228
247
  | `format` | string | — | 條目格式(`-F`):`oneline` / `medium` / `full` 或 `%h %d %c` 這類樣板 |
229
248
  | `verbose` | boolean | `false` | 每個 check-in 後面列出變更的檔案(`-v`) |
249
+ | `offset` | number | — | 跳過前 N 條(`--offset`) |
250
+ | `width` | number | — | 輸出寬度(`-W`,≥20) |
230
251
  | `workspace` | string | 見 admin §2.1 | — |
231
252
 
232
253
  真實輸出(`limit: 3`):
@@ -242,7 +263,7 @@ fossil timeline -n <limit> [-p PATH] [-t TYPE] [-b BRANCH] [-c] [WHEN CHECKIN] [
242
263
  ### 3.7 `fossil_info`
243
264
 
244
265
  ```bash
245
- fossil info [target]
266
+ fossil info [target] [-v]
246
267
  ```
247
268
 
248
269
  `target` 可以是檔名、check-in 雜湊、分支名;省略時給倉庫/check-out 元資訊(真實輸出見 §3.1 的 STATUS 段同源)。
@@ -251,6 +272,7 @@ fossil info [target]
251
272
  | 參數 | 類型 | 必填/預設 | 說明 |
252
273
  | --- | --- | --- | --- |
253
274
  | `target` | string | — | 檔名、check-in 雜湊或分支名 |
275
+ | `verbose` | boolean | `false` | 額外資訊,如 SQLite 版本與倉庫大小(`-v`) |
254
276
  | `workspace` | string | 見 admin §2.1 | — |
255
277
 
256
278
  ---
@@ -258,7 +280,9 @@ fossil info [target]
258
280
 
259
281
  ```bash
260
282
  fossil changes [--edited|--updated|--added|--deleted|--renamed|--conflict|--meta]
261
- [--classify] [--no-merge] [--dotfiles] [--abs-paths] [files...]
283
+ [--changed|--missing|--unchanged|--extra|--differ|--all]
284
+ [--classify] [--no-merge] [--hash] [--header] [-v]
285
+ [--dotfiles] [--abs-paths|--rel-paths] [files...]
262
286
  ```
263
287
 
264
288
  純工作區的變更清單(不讀 `extras`,所以未跟蹤檔案不會出現)。
@@ -267,10 +291,15 @@ fossil changes [--edited|--updated|--added|--deleted|--renamed|--conflict|--meta
267
291
  | --- | --- | --- | --- |
268
292
  | `files` | string[] | — | 只報告這些路徑 |
269
293
  | `edited` / `updated` / `added` / `deleted` / `renamed` / `conflict` / `meta` | boolean | `false` | 變更類型過濾,可疊加 |
294
+ | `changed` / `missing` / `unchanged` / `extra` / `differ` / `all` | boolean | `false` | 其餘變更類型過濾,可疊加 |
270
295
  | `classify` | boolean | `false` | 每行前面加變更類型 |
271
296
  | `no_merge` | boolean | `false` | 隱藏 merge 貢獻者 |
297
+ | `hash` | boolean | `false` | 用雜湊而非大小+mtime 判斷狀態(`--hash`) |
298
+ | `header` | boolean | `false` | 非空報告前印倉庫名(`--header`) |
299
+ | `verbose` | boolean | `false` | 空報告時印 `(none)`(`-v`) |
272
300
  | `dotfiles` | boolean | `false` | 包含以 `.` 開頭的未管理檔案 |
273
301
  | `absolute_paths` | boolean | `false` | 輸出絕對路徑 |
302
+ | `relative_paths` | boolean | `false` | 輸出相對於目前目錄的路徑 |
274
303
  | `workspace` | string | 見 admin §2.1 | — |
275
304
 
276
305
  真實輸出(`classify: true`):
@@ -498,7 +527,7 @@ fossil ls ?PATHS ...? [-r REV] [--age] [-v] [-t] [--hash]
498
527
  | `age` | boolean | `false` | 顯示提交時間(`--age`) |
499
528
  | `verbose` | boolean | `false` | 額外資訊:無 `-r` 時是變更狀態,有 `-r` 時是提交時間與大小(`-v`) |
500
529
  | `time_order` | boolean | `false` | 按時間排序(`-t`);搭配 `--age` 或 `-r` 時按提交時間 |
501
- | `hash` | boolean | `false` | 用雜湊(而非大小+mtime)判斷檔案狀態(`--hash`) |
530
+ | `hash` | boolean | `false` | 用雜湊而非大小+mtime 判斷檔案狀態(`--hash`),自動加上 `--verbose` |
502
531
  | `workspace` | string | 見 admin §2.1 | — |
503
532
 
504
533
  真實輸出:
@@ -519,7 +548,7 @@ fossil search [-a] [-n N] [-W WIDTH] pattern
519
548
 
520
549
  | 參數 | 類型 | 必填/預設 | 說明 |
521
550
  | --- | --- | --- | --- |
522
- | `pattern` | string | — | 要搜尋的字詞;全部都要命中 |
551
+ | `pattern` | string | **必填** | 要搜尋的字詞;全部都要命中 |
523
552
  | `all` | boolean | `false` | 輸出全部命中,而不是只給高分者(`--all`) |
524
553
  | `limit` | number | — | 最多輸出幾筆(`-n`) |
525
554
  | `width` | number | — | 輸出寬度,`0` 表示不折行(`-W`) |
@@ -545,7 +574,7 @@ fossil artifact <ARTIFACT-ID>
545
574
 
546
575
  | 參數 | 類型 | 必填/預設 | 說明 |
547
576
  | --- | --- | --- | --- |
548
- | `artifact` | string | — | 工件雜湊,可用唯一前綴 |
577
+ | `artifact` | string | **必填** | 工件雜湊,可用唯一前綴 |
549
578
  | `workspace` | string | 見 admin §2.1 | — |
550
579
 
551
580
  真實輸出(檔案版本工件):
@@ -569,7 +598,7 @@ fossil describe ?VERSION? [--digits N] [--dirty] [--long] [--match GLOB]
569
598
  | --- | --- | --- | --- |
570
599
  | `version` | string | — | 要描述的版本;省略時為當前 check-out |
571
600
  | `digits` | number | — | 雜湊位數(`--digits`,4..40) |
572
- | `dirty` | boolean | `false` | 一併顯示是否有未提交改動(`--dirty`) |
601
+ | `dirty` | boolean | `false` | 一併顯示是否有未提交改動(`--dirty`);只適用當前 check-out |
573
602
  | `long` | boolean | `false` | 即使三者可折疊也全部顯示(`--long`) |
574
603
  | `match` | string | — | 只考慮符合此 glob 的非傳播標籤(`--match`) |
575
604
  | `workspace` | string | 見 admin §2.1 | — |
@@ -625,21 +654,25 @@ Wrote snap.zip from tip.
625
654
  ### 3.22 `fossil_unversioned`
626
655
 
627
656
  ```bash
628
- fossil unversioned list [--glob PATTERN] [--like PATTERN]
629
- fossil unversioned cat|add|remove|touch FILE ...
657
+ fossil unversioned list|remove [--glob PATTERN] [--like PATTERN]
658
+ fossil unversioned cat|add|remove|touch FILE ... [--mtime TIMESTAMP]
659
+ fossil unversioned sync|revert [URL] [-v] [-n]
630
660
  ```
631
661
 
632
662
  | 參數 | 類型 | 必填/預設 | 說明 |
633
663
  | --- | --- | --- | --- |
634
- | `action` | `list` / `cat` / `add` / `remove` / `touch` | `list` | `list` 列出、`cat` 印內容、`add`/`remove` 改集合、`touch` 更新時間戳 |
664
+ | `action` | `list` / `cat` / `add` / `remove` / `touch` / `sync` / `revert` | `list` | `list` 列出、`cat` 印內容、`add`/`remove` 改集合、`touch` 更新時間戳、`sync`/`revert` 與遠端交換 |
635
665
  | `files` | string[] | — | 動作套用的檔案 |
636
- | `glob` | string | — | 只比對符合此 glob 的名字(`--glob`) |
637
- | `like` | string | — | 只比對符合此模式的名字(`--like`) |
666
+ | `glob` | string | — | 只比對符合此 glob 的名字(`--glob`),用於 `list`/`remove` |
667
+ | `like` | string | — | 只比對符合此模式的名字(`--like`),用於 `list`/`remove` |
668
+ | `url` | string | 預設遠端 | `sync`/`revert` 的遠端 URL |
669
+ | `mtime` | string | — | 取代 `now` 的時間戳,用於 `add`/`remove`/`touch`(`--mtime`) |
670
+ | `verbose` | boolean | `false` | 額外診斷輸出,用於 `sync`/`revert`(`-v`) |
671
+ | `dry_run` | boolean | `false` | 只顯示會做什麼,用於 `sync`/`revert`(`-n`) |
638
672
  | `workspace` | string | 見 admin §2.1 | — |
639
673
 
640
- unversioned file(UV-file)只保留最新版本、不保存歷史,變更不可撤銷。`action` 不是 `list` 時,
641
- `files`、`glob`、`like` 至少要給一個,否則工具直接返回
642
- `ERROR: action 'cat' needs \`files\`, \`glob\` or \`like\`.`(不 spawn fossil)。
674
+ unversioned file(UV-file)只保留最新版本、不保存歷史,變更不可撤銷。`cat`/`add`/`touch` 必須給 `files`,
675
+ 否則工具直接返回 ``ERROR: action 'cat' needs `files`.``
643
676
 
644
677
  真實輸出:
645
678
 
@@ -657,13 +690,18 @@ unversioned body
657
690
  ### 3.23 `fossil_touch`
658
691
 
659
692
  ```bash
660
- fossil touch [--now|-c|--checkin|-C|--checkout] [FILES...]
693
+ fossil touch [--now|-c|--checkin|-C|--checkout] [-g GLOBS] [-G] [-v] [-n] [-q] [FILES...]
661
694
  ```
662
695
 
663
696
  | 參數 | 類型 | 必填/預設 | 說明 |
664
697
  | --- | --- | --- | --- |
665
698
  | `files` | string[] | — | 檔案或 glob;省略時套用所有受管理檔案 |
666
699
  | `mode` | `now` / `checkin` / `checkout` | `now` | `--now` 目前時間、`-c` 該檔最後一次 check-in 的時間、`-C` 當前 check-out 的時間 |
700
+ | `glob` | string | — | 逗號分隔的 glob,從原始碼樹頂端計算(`-g`) |
701
+ | `glob_file` | string | — | 讀取 fossil glob 清單檔(`-G`) |
702
+ | `verbose` | boolean | `false` | 印出 glob 與每個碰到的檔案(`-v`) |
703
+ | `dry_run` | boolean | `false` | 只列出需要更新的檔案(`-n`) |
704
+ | `quiet` | boolean | `false` | 略過未管理或樹外檔案的警告(`-q`) |
667
705
  | `workspace` | string | 見 admin §2.1 | — |
668
706
 
669
707
  Fossil 用檔案大小與 mtime 判斷是否變更,所以在同一個時間戳內改檔案可能被忽略;`fossil_touch { mode: "now" }`
@@ -672,16 +710,22 @@ Fossil 用檔案大小與 mtime 判斷是否變更,所以在同一個時間戳
672
710
  ### 3.24 `fossil_amend`
673
711
 
674
712
  ```bash
675
- fossil amend <check-in> [-n] [-m COMMENT] [--author USER] [--date WHEN] [--tag TAG] [--cancel TAG]
676
- [--branch NAME] [--hide] [--close]
713
+ fossil amend <check-in> [-n] [-m COMMENT|-M FILE] [--author USER] [--date WHEN]
714
+ [--bgcolor COLOR] [--branchcolor] [--date-override WHEN] [--user-override USER]
715
+ [--tag TAG] [--cancel TAG] [--branch NAME] [--hide] [--close]
677
716
  ```
678
717
 
679
718
  | 參數 | 類型 | 必填/預設 | 說明 |
680
719
  | --- | --- | --- | --- |
681
- | `checkin` | string | — | 要改的 check-in(`tip` 或雜湊) |
720
+ | `checkin` | string | **必填** | 要改的 check-in(`tip` 或雜湊) |
682
721
  | `comment` | string | — | 換掉註解(`-m`) |
722
+ | `message_file` | string | — | 從工作區的檔案讀取新註解(`-M`) |
683
723
  | `author` | string | — | 換掉作者(`--author`) |
684
724
  | `date` | string | — | 換掉 check-in 時間,或 `now`(`--date`) |
725
+ | `bgcolor` | string | — | 這個 check-in 的背景色(`--bgcolor`) |
726
+ | `branchcolor` | boolean | `false` | 把 `bgcolor` 套用到整個分支(`--branchcolor`) |
727
+ | `date_override` | string | — | control artifact 的變更時間(`--date-override`) |
728
+ | `user_override` | string | — | control artifact 上的使用者名(`--user-override`) |
685
729
  | `tag` | string[] | — | 加上標籤(`--tag`,可重複) |
686
730
  | `cancel` | string[] | — | 移除標籤(`--cancel`,可重複) |
687
731
  | `branch` | string | — | 以此 check-in 開新分支(`--branch`) |
@@ -690,8 +734,8 @@ fossil amend <check-in> [-n] [-m COMMENT] [--author USER] [--date WHEN] [--tag T
690
734
  | `dry_run` | boolean | `false` | 只印出 control artifact,不改倉庫(`-n`) |
691
735
  | `workspace` | string | 見 admin §2.1 | — |
692
736
 
693
- `comment`/`author`/`date`/`tag`/`cancel`/`branch`/`hide`/`close` 至少要給一個,否則工具直接返回
694
- `ERROR: pass at least one of \`comment\`, \`author\`, …`(不 spawn fossil)。
737
+ `comment`/`message_file`/`author`/`date`/`bgcolor`/`date_override`/`user_override`/`tag`/`cancel`/`branch`/`hide`/`close`
738
+ 至少要給一個,否則工具直接返回 `ERROR: pass at least one of \`comment\`, \`message_file\`, …`(不 spawn fossil)。
695
739
 
696
740
  真實輸出(`dry_run: true`):
697
741
 
@@ -705,7 +749,9 @@ U stellar
705
749
  ### 3.25 `fossil_patch`
706
750
 
707
751
  ```bash
708
- fossil patch create|diff|apply [-f] [-n] [-v] <file>
752
+ fossil patch create [-f] <file>
753
+ fossil patch diff [-f] <file>
754
+ fossil patch apply [-f] [-n] [-v] <file>
709
755
  ```
710
756
 
711
757
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -713,8 +759,8 @@ fossil patch create|diff|apply [-f] [-n] [-v] <file>
713
759
  | `action` | `create` / `diff` / `apply` | `create` | 產生、顯示或套用 binary patch |
714
760
  | `file` | string | **必填** | patch 檔案路徑(相對路徑以 `workspace` 為基準) |
715
761
  | `force` | boolean | `false` | 覆寫既有 patch,或在有未提交改動時套用(`-f`) |
716
- | `dry_run` | boolean | `false` | 只印出會做什麼(`-n`) |
717
- | `verbose` | boolean | `false` | 額外說明(`-v`) |
762
+ | `dry_run` | boolean | `false` | `-n` 只印出 `apply` 會做什麼 |
763
+ | `verbose` | boolean | `false` | `-v` 讓 `apply` 額外說明 |
718
764
  | `workspace` | string | 見 admin §2.1 | — |
719
765
 
720
766
  真實輸出:
@@ -802,7 +848,7 @@ ERROR: the query must start with SELECT, WITH, PRAGMA or EXPLAIN.
802
848
  ### 4.1 `fossil_add`
803
849
 
804
850
  ```bash
805
- fossil add [--dotfiles] [-f] [--ignore GLOBS] <files...>
851
+ fossil add [--dotfiles] [-f] [--ignore GLOBS] [--case-sensitive 1|0] [--clean CSG] [--allow-reserved] <files...>
806
852
  fossil add --reset [-v] # reset: true,不需要 files
807
853
  ```
808
854
 
@@ -812,6 +858,9 @@ fossil add --reset [-v] # reset: true,不需要 files
812
858
  | `force` | boolean | `true` | 預設加 `-f`,否則命中 `ignore-glob` 的檔案會讓 fossil 互動式詢問,服務端會卡住 |
813
859
  | `dotfiles` | boolean | `false` | `--dotfiles` 遞迴點檔案 |
814
860
  | `ignore` | string | — | `--ignore` 的 CSG,用於略過未管理檔案 |
861
+ | `clean` | string | — | `--clean` 的 CSG,把符合的未管理檔案移出版本控制 |
862
+ | `case_sensitive` | boolean | 依設定 | `--case-sensitive 1\|0` 覆寫大小寫規則 |
863
+ | `allow_reserved` | boolean | `false` | 允許加入 Windows 保留檔名(`--allow-reserved`) |
815
864
  | `reset` | boolean | `false` | `--reset` 清掉 ADDED 狀態,只回報不新增 |
816
865
  | `verbose` | boolean | `false` | `-v` 逐檔回報;只在 `reset: true` 時送出 |
817
866
  | `workspace` | string | 見 admin §2.1 | — |
@@ -823,8 +872,8 @@ fossil add --reset [-v] # reset: true,不需要 files
823
872
  ### 4.2 `fossil_rm`
824
873
 
825
874
  ```bash
826
- fossil rm [--hard] [--soft] [-n] <files...>
827
- fossil rm --reset [--verbose] <files...>
875
+ fossil rm [--hard|--soft] [--case-sensitive 1|0] [-n] <files...>
876
+ fossil rm --reset [--verbose] [-n] <files...>
828
877
  ```
829
878
 
830
879
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -835,15 +884,17 @@ fossil rm --reset [--verbose] <files...>
835
884
  | `dry_run` | boolean | `false` | `-n` 只列出會移除什麼 |
836
885
  | `reset` | boolean | `false` | `--reset` 清掉 DELETED 狀態 |
837
886
  | `verbose` | boolean | `false` | `--verbose` 逐檔回報(配合 `reset`) |
887
+ | `case_sensitive` | boolean | 依設定 | `--case-sensitive 1\|0` 覆寫大小寫規則 |
838
888
  | `workspace` | string | 見 admin §2.1 | — |
839
889
 
840
- 兩個都給時參數是 `fossil rm --hard --soft <files>`——fossil 不報錯,實測後一個 flag 生效(檔案仍在磁碟上),
841
- 所以 `keep` 覆蓋 `force`。
890
+ `keep` 與 `force` 同時給時只送 `--soft`(fossil 的 `--soft` 本來就覆蓋 `--hard`)。
891
+ `reset: true` 時只送 `--reset`,`--verbose` 與 `-n` 一併帶上;`force`/`keep` 在這種情況不送出,
892
+ 因為 fossil 只接受 `--verbose` 與 `--dry-run` 搭配 `--reset`。
842
893
 
843
894
  ### 4.3 `fossil_mv`
844
895
 
845
896
  ```bash
846
- fossil mv --hard|--soft [--case-sensitive 1|0] <old> <new>
897
+ fossil mv --hard|--soft [--case-sensitive 1|0] [-n] <old> <new>
847
898
  ```
848
899
 
849
900
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -852,6 +903,7 @@ fossil mv --hard|--soft [--case-sensitive 1|0] <old> <new>
852
903
  | `new_name` | string | **必填** | 目標路徑 |
853
904
  | `hard` | boolean | `true` | `--hard` 同步改磁碟;`false` 時用 `--soft` 只記錄 RENAME 事件 |
854
905
  | `case_sensitive` | boolean | 依設定 | `--case-sensitive 1\|0` 覆寫大小寫規則 |
906
+ | `dry_run` | boolean | `false` | 只印出 RENAME 事件(`-n`) |
855
907
  | `workspace` | string | 見 admin §2.1 | — |
856
908
 
857
909
  `hard` 預設 `true`:既記錄 RENAME 事件也在磁碟改名;`hard: false` 只記錄。
@@ -859,8 +911,8 @@ fossil mv --hard|--soft [--case-sensitive 1|0] <old> <new>
859
911
  ### 4.4 `fossil_addremove`
860
912
 
861
913
  ```bash
862
- fossil addremove [--dotfiles] [--ignore GLOBS] [--clean GLOBS] [-n]
863
- fossil addremove --reset [-n] # reset: true
914
+ fossil addremove [--dotfiles] [--ignore GLOBS] [--clean GLOBS] [--case-sensitive 1|0] [-n]
915
+ fossil addremove --reset [-n] [-v] # reset: true
864
916
  ```
865
917
 
866
918
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -868,7 +920,9 @@ fossil addremove --reset [-n] # reset: true
868
920
  | `dotfiles` | boolean | `false` | `--dotfiles` 一併處理 `.` 開頭的檔案 |
869
921
  | `ignore` | string | — | `--ignore` 覆蓋 `ignore-glob` |
870
922
  | `clean` | string | — | `--clean` 追加忽略的 glob |
923
+ | `case_sensitive` | boolean | 依設定 | `--case-sensitive 1\|0` 覆寫大小寫規則 |
871
924
  | `reset` | boolean | `false` | `--reset` 清掉 ADDED/DELETED 狀態,其餘參數被忽略 |
925
+ | `verbose` | boolean | `false` | `-v` 逐檔回報;只在 `reset: true` 時送出 |
872
926
  | `dry_run` | boolean | `false` | `-n` 只列出將要 add / rm 的檔案,工作區不變 |
873
927
  | `workspace` | string | 見 admin §2.1 | — |
874
928
 
@@ -878,8 +932,8 @@ fossil addremove --reset [-n] # reset: true
878
932
 
879
933
  ```bash
880
934
  fossil commit -m <message> [--branch B] [--no-warnings] [--allow-empty] [--close]
881
- [--bgcolor COLOR] [--mtime DATE] [--tag TAG ...] [--user-override U] [files...]
882
- # stdin = "a\n"
935
+ [--bgcolor COLOR] [--date-override DATE] [--tag TAG ...] [--user-override U] [files...]
936
+ # stdin = "y\na\n"
883
937
  ```
884
938
 
885
939
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -891,13 +945,13 @@ fossil commit -m <message> [--branch B] [--no-warnings] [--allow-empty] [--close
891
945
  | `allow_empty` | boolean | `false` | `--allow-empty`(無檔案變更也能提交) |
892
946
  | `close` | boolean | `false` | `--close` 提交後關閉所在分支 |
893
947
  | `bgcolor` | string | — | `--bgcolor` 只套用在這一個 check-in 的背景色 |
894
- | `mtime` | string | — | `--mtime` 指定提交時間(如 `2026-11-17 12:00:00`) |
948
+ | `date_override` | string | — | `--date-override` 指定提交時間(如 `2026-11-17 12:00:00`) |
895
949
  | `tags` | string[] | — | 每個元素一個 `--tag`,把標籤打在這個 check-in 上 |
896
950
  | `user_override` | string | — | `--user-override` |
897
951
  | `workspace` | string | 見 admin §2.1 | — |
898
952
 
899
- **關鍵點**:工具固定向 stdin 寫 `a\n`,因為提交二進位制檔案時 fossil 會問
900
- `commit anyhow (a=all/y/N)?`,沒有 stdin 就會永久阻塞。副作用是該提示被自動回答為“全部”。
953
+ **關鍵點**:工具固定向 stdin 寫 `y\na\n`。fossil 在檔案參數未知時先問 `continue (y/N)?`,
954
+ 再問 `commit anyhow (a=all/y/N)?`;沒有 stdin 就會永久阻塞。
901
955
 
902
956
  ### 4.6 `fossil_revert`
903
957
 
@@ -916,7 +970,7 @@ fossil revert [-r REV] [files...]
916
970
  ### 4.7 `fossil_clean`
917
971
 
918
972
  ```bash
919
- fossil clean -n # dry_run: true
973
+ fossil clean [--dotfiles] [--ignore GLOBS] [--clean CSG] [-x] [--temp] [--dirsonly] [--emptydirs] [-v] [-n]
920
974
  fossil clean -f # all_files: true
921
975
  fossil clean --no-prompt # 都不給(預設)
922
976
  ```
@@ -925,9 +979,17 @@ fossil clean --no-prompt # 都不給(預設)
925
979
  | --- | --- | --- | --- |
926
980
  | `dry_run` | boolean | `false` | 只列出會刪除的檔案(`-n`) |
927
981
  | `all_files` | boolean | `false` | 不確認直接刪除(`-f`) |
982
+ | `dotfiles` | boolean | `false` | 一併處理 `.` 開頭的檔案(`--dotfiles`) |
983
+ | `ignore` | string | — | `--ignore` 覆蓋 `ignore-glob` |
984
+ | `clean` | string | — | `--clean` 追加忽略的 glob |
985
+ | `verily` | boolean | `false` | `-x` 連被忽略的檔案也處理 |
986
+ | `temp` | boolean | `false` | 連暫存檔一起清(`--temp`) |
987
+ | `dirs_only` | boolean | `false` | 只刪空目錄(`--dirsonly`) |
988
+ | `empty_dirs` | boolean | `false` | 一併刪除空目錄(`--emptydirs`) |
989
+ | `verbose` | boolean | `false` | 逐檔回報(`-v`) |
928
990
  | `workspace` | string | 見 admin §2.1 | — |
929
991
 
930
- 三態互斥,優先順序 `dry_run` > `all_files` > `--no-prompt`。預設 `--no-prompt` 是為了不阻塞;
992
+ 三態互斥,優先順序 `dry_run` > `all_files` > `--no-prompt`;`verily` 時不送 `--no-prompt`。預設 `--no-prompt` 是為了不阻塞;
931
993
  它等於“刪除所有未跟蹤檔案且不再確認”,所以**先 `dry_run: true` 預覽**。空輸出 → `Nothing to clean.`
932
994
 
933
995
  ### 4.8 `fossil_stash`
@@ -953,16 +1015,27 @@ fossil stash ls|pop|apply|drop|diff [STASH_ID]
953
1015
  ### 5.1 `fossil_tag`
954
1016
 
955
1017
  ```bash
956
- fossil tag ls
957
- fossil tag add <tag> <checkin>
958
- fossil tag cancel <tag> [<checkin>] # checkin 預設 'tip'
1018
+ fossil tag ls [--raw] [--tagtype TYPE] [-v] [--prefix PREFIX]
1019
+ fossil tag find <tag> [--raw] [-t TYPE] [-n LIMIT]
1020
+ fossil tag add <tag> <checkin> [--raw] [--propagate] [--date-override WHEN] [--user-override USER] [-n]
1021
+ fossil tag cancel <tag> [<checkin>] [--raw] [--date-override WHEN] [--user-override USER] [-n]
959
1022
  ```
960
1023
 
961
1024
  | 參數 | 類型 | 必填/預設 | 說明 |
962
1025
  | --- | --- | --- | --- |
963
- | `action` | `ls` / `add` / `cancel` | `ls` | 要執行的 tag 動作 |
964
- | `tag_name` | string | `add` / `cancel` 時必填 | 標籤名 |
1026
+ | `action` | `ls` / `find` / `add` / `cancel` | `ls` | 要執行的 tag 動作 |
1027
+ | `tag_name` | string | `find` / `add` / `cancel` 時必填 | 標籤名,`find` 支援前綴比對 |
965
1028
  | `checkin` | string | `add` 時必填;`cancel` 預設 `tip` | 要標記或取消的 check-in |
1029
+ | `raw` | boolean | `false` | 不做 shell 轉義(`--raw`) |
1030
+ | `propagate` | boolean | `false` | 把標籤傳播到後代 check-in(`--propagate`),只用於 `add` |
1031
+ | `date_override` | string | — | control artifact 的時間(`--date-override`) |
1032
+ | `user_override` | string | — | control artifact 的使用者(`--user-override`) |
1033
+ | `dry_run` | boolean | `false` | 只印出 control artifact(`-n`),用於 `add`/`cancel` |
1034
+ | `type` | `ci` / `w` / `e` / `f` / `t` | — | 只找這些型別上的標籤(`-t`),用於 `find` |
1035
+ | `limit` | number | — | 最多列出的筆數(`-n`),用於 `find` |
1036
+ | `tagtype` | `propagated` / `singleton` / `cancel` | — | 只列這些種類的標籤(`--tagtype`),用於 `ls` |
1037
+ | `inverse` | boolean | `false` | 反轉 `tagtype` 的篩選(`-v`),用於 `ls` |
1038
+ | `prefix` | string | — | 只列以此開頭的標籤(`--prefix`),用於 `ls` |
966
1039
  | `workspace` | string | 見 admin §2.1 | — |
967
1040
 
968
1041
  `fossil tag cancel` 必須有 artifact id,所以工具補 `tip`;空輸出 → `No tags.`(實測 `fossil tag ls` 輸出 `trunk`)。
@@ -970,25 +1043,38 @@ fossil tag cancel <tag> [<checkin>] # checkin 預設 'tip'
970
1043
  ### 5.2 `fossil_branch`
971
1044
 
972
1045
  ```bash
973
- fossil branch ls
974
- fossil branch new <name> [<basis>] # basis 預設 'current'
1046
+ fossil branch ls [-a] [-c] [-p] [-r] [-t]
1047
+ fossil branch new <name> [<basis>] [--private] [--bgcolor COLOR] [--date-override WHEN] [--user-override USER]
1048
+ fossil branch info|close|reopen|hide|unhide <name> [-n] [-v] [--date-override WHEN] [--user-override USER]
1049
+ fossil branch current
975
1050
  ```
976
1051
 
977
- `branch_name` 在 `action: 'new'` 時必填,否則工具直接返回 `ERROR: 'branch_name' is required for action 'new'.`。
1052
+ `branch_name` 在需要具名分支的動作必填,否則工具直接返回 `ERROR: 'branch_name' is required for action '<action>'.`。
978
1053
  `basis` 省略時補 `current`(fossil 要求顯式 basis)。實測 `fossil branch ls` → `* trunk`。
979
1054
 
980
1055
  | 參數 | 類型 | 必填/預設 | 說明 |
981
1056
  | --- | --- | --- | --- |
982
- | `action` | `ls` / `new` | `ls` | 列出分支或建立新分支 |
983
- | `branch_name` | string | `new` 時必填 | 新分支名 |
1057
+ | `action` | `ls` / `new` / `info` / `current` / `close` / `reopen` / `hide` / `unhide` | `ls` | 分支動作 |
1058
+ | `branch_name` | string | `new` / `info` / `close` / `reopen` / `hide` / `unhide` 時必填 | 分支名 |
984
1059
  | `basis` | string | `current` | 新分支的起點(check-in 或分支) |
1060
+ | `all` | boolean | `false` | 連關閉的分支一起列出(`-a`) |
1061
+ | `closed` | boolean | `false` | 只列關閉的分支(`-c`) |
1062
+ | `private_branches` | boolean | `false` | 連私有分支一起列出(`-p`) |
1063
+ | `reverse` | boolean | `false` | 反向排序(`-r`) |
1064
+ | `time_order` | boolean | `false` | 依時間而非名稱排序(`-t`) |
1065
+ | `private_branch` | boolean | `false` | 新分支標為私有(`--private`) |
1066
+ | `bgcolor` | string | — | 新分支的背景色(`--bgcolor`) |
1067
+ | `dry_run` | boolean | `false` | 只顯示會做什麼(`-n`) |
1068
+ | `verbose` | boolean | `false` | 額外輸出(`-v`) |
1069
+ | `date_override` | string | — | control artifact 的時間(`--date-override`) |
1070
+ | `user_override` | string | — | control artifact 的使用者(`--user-override`) |
985
1071
  | `workspace` | string | 見 admin §2.1 | — |
986
1072
 
987
1073
  ### 5.3 `fossil_merge`
988
1074
 
989
1075
  ```bash
990
- fossil merge [-n] [--integrate] [--cherrypick|--backout] [--baseline V] [--binary G] [-f] [-K] [-v]
991
- <branch_or_version>
1076
+ fossil merge [-n] [--integrate] [--cherrypick|--backout] [--baseline V] [--binary G]
1077
+ [--force-missing] [-f] [-K] [-v] <branch_or_version>
992
1078
  ```
993
1079
 
994
1080
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -1002,6 +1088,7 @@ fossil merge [-n] [--integrate] [--cherrypick|--backout] [--baseline V] [--binar
1002
1088
  | `binary` | string | — | 符合此 glob 的檔案不做平行合併(`--binary`) |
1003
1089
  | `force` | boolean | `false` | 即使合併無效也照做(`-f`) |
1004
1090
  | `keep_merge_files` | boolean | `false` | 衝突時保留暫存檔(`-K`) |
1091
+ | `force_missing` | boolean | `false` | 即使有一側內容缺失也合併(`--force-missing`) |
1005
1092
  | `verbose` | boolean | `false` | 逐檔報告合併結果(`-v`) |
1006
1093
  | `workspace` | string | 見 admin §2.1 | — |
1007
1094
 
@@ -1010,7 +1097,7 @@ fossil merge [-n] [--integrate] [--cherrypick|--backout] [--baseline V] [--binar
1010
1097
  ### 5.4 `fossil_update`
1011
1098
 
1012
1099
  ```bash
1013
- fossil update [--latest] [--nosync] [--setmtime] [-K] [-v] [target]
1100
+ fossil update [--latest] [--nosync] [--setmtime] [--force-missing] [-K] [-v] [target]
1014
1101
  fossil update -n [target] # dry_run: true
1015
1102
  ```
1016
1103
 
@@ -1022,7 +1109,9 @@ fossil update -n [target] # dry_run: true
1022
1109
  | `no_sync` | boolean | `false` | `--nosync` 跳過更新前自動 sync |
1023
1110
  | `set_mtime` | boolean | `false` | `--setmtime` 把檔案時間戳設成最後一次相關提交的時間 |
1024
1111
  | `keep_merge_files` | boolean | `false` | `-K` 衝突時保留 `*-baseline` / `*-original` / `*-merge` |
1112
+ | `force_missing` | boolean | `false` | `--force-missing` 即使有一側內容缺失也更新 |
1025
1113
  | `verbose` | boolean | `false` | `-v` 列出每個檔案的處理結果 |
1114
+ | `workspace` | string | 見 admin §2.1 | check-out 目錄 |
1026
1115
 
1027
1116
  **破壞性**:會覆蓋工作區本地改動。`target` 省略時更新當前分支。
1028
1117
 
@@ -1064,17 +1153,21 @@ fossil_timeline { limit: 5 }
1064
1153
 
1065
1154
  1. **`fossil_status` 的未跟蹤檔案來自第二條命令**(`fossil extra`),兩者併發執行。單條失敗時該段渲染成
1066
1155
  `--- STATUS ---` + `ERROR: …`,但 `isError` 只為 `true` 當**兩段都失敗**(`renderSections` 的規則)。
1067
- 2. **`commit` 自動回答互動提示為 `a`(all)**:二進位制檔案與忽略規則的衝突一律照交。
1068
- 3. **`add` 預設 `-f`**:`force: false` 時命中 `ignore-glob` 的檔案會讓 fossil 互動詢問 → 服務端可能掛住,
1069
- 不要在沒有 stdin 支援的情況下傳 `force: false`。
1156
+ 2. **`commit` 自動回答兩個互動提示**:未知檔名參數的 `continue (y/N)?` 答 `y`,內容警告的
1157
+ `Commit anyhow (a=all/y/N)?` 答 `a`(all);二進位制檔案與忽略規則的衝突一律照交。
1158
+ 3. **`add` 預設 `-f`**:`force: false` 時命中 `ignore-glob` 的檔案會讓 fossil 互動詢問,服務端因此停住;
1159
+ 保持預設 `force: true`。
1070
1160
  4. **`clean` 無參數即 `--no-prompt`**(直接刪),不是“只預覽”。先用 `dry_run`。
1071
1161
  5. **`tag cancel` / `branch new` 的預設值**(`tip` / `current`)是工具補的,不是 fossil 原生預設。
1072
1162
  6. **版本表示式**只支援 fossil 自身語法(`tip`、雜湊前綴、`branch:name` 等);`tip-1` 這類寫法會失敗。
1073
- 7. **路徑沒有 `--` 屏障**:以 `-` 開頭的檔名需要 `./` 前綴。
1163
+ 7. **路徑原樣傳遞**:以 `-` 開頭的檔名需要 `./` 前綴。
1074
1164
  8. **除 `fossil_sql` 可用 `repository` 直接查詢外,工具都要求已 open 的 check-out**;只有倉庫檔案(.fossil)時用 admin 的 `fossil_open`。
1075
1165
  9. **`fossil_ignore_from_gitignore` 沿用 fossil 的深度語意**:git 的 `*` 不跨 `/`,fossil 的跨,所以含斜線的樣式
1076
1166
  (`src/*.o`)在 fossil 會連更深的路徑一起匹配。
1077
1167
  10. **`ignore-glob` 沒有否定**:`!` 開頭的行只能略過並在 `NOTE:` 說明,被 git 重新納入的檔案在 fossil 仍被忽略。
1168
+ 11. **`fossil_mv` 的 `--hard`**:目標位置已有未管理的同名檔案時,該檔案被覆寫;來源在先前
1169
+ `hard: false` 只記錄 RENAME 後已不在磁碟上,`--hard` 會以 `cannot open "…" for reading` 失敗,
1170
+ 但 RENAME 事件已寫入。
1078
1171
 
1079
1172
  ---
1080
1173
 
package/docs/wiki.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Wiki 能力(`-c w`)工具說明
2
2
 
3
- 適用於 `@stellar_ai/mcp_fossil_scm@0.1.3` 及之後,fossil 2.21 實測。
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.0` 及之後,fossil 2.21 實測。
4
4
 
5
5
  `-c w` 註冊 3 個工具:`fossil_wiki_ls` / `fossil_wiki_read` / `fossil_wiki_write`。
6
6
  (組合啟用:`-c aw`。)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@stellar_ai/mcp_fossil_scm",
3
- "version": "0.1.3",
3
+ "version": "0.2.0",
4
4
  "description": "Capability-scoped MCP server for Fossil SCM: Admin, VCS, Forum, Tickets, Wiki and Chat",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",