@stellar_ai/mcp_fossil_scm 0.1.2 → 0.1.3

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/chat.md ADDED
@@ -0,0 +1,152 @@
1
+ # Chat 能力(`-c c`)工具說明
2
+
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.1.3` 及之後,fossil 2.21 實測。
4
+
5
+ `-c c` 註冊 4 個工具:`fossil_chat_url` / `fossil_chat_send` / `fossil_chat_pull` / `fossil_chat_read`。
6
+
7
+ Chat 資料既不在 check-out 裡,也不在倉庫的普通表裡:訊息存在 chat 伺服器(`chat` 表),
8
+ 必須 `fossil chat pull` 之後才會出現在本地 clone 的 `chat` 表,或 `--out` 指定的獨立歸檔庫裡。
9
+
10
+ ---
11
+
12
+ ## 1. 通用約定
13
+
14
+ - `url` / `send` / `pull` 需要**倉庫配置裡定義了 remote**,否則 fossil 原文 `no "remote" repository defined`。
15
+ - `url` / `send` / `pull` 走 `FOSSIL_NETWORK_TIMEOUT_MS`(預設 `600000` ms = 10 分鐘;普通命令是
16
+ `FOSSIL_TIMEOUT_MS`,預設 `30000` ms);`read` 走普通超時。
17
+ - 傳送與拉取還需要 chat 伺服器上的登入憑據/權限(pull 需要 setup 權限)。
18
+ - `workspace` 語義見 `docs/admin.md` §2.1。
19
+
20
+ ---
21
+
22
+ ## 2. `fossil_chat_url`
23
+
24
+ ```bash
25
+ fossil chat url [--remote URL]
26
+ ```
27
+
28
+ | 參數 | 類型 | 必填/預設 | 說明 |
29
+ | --- | --- | --- | --- |
30
+ | `remote` | string | — | 用這個 URL 代替預設 remote |
31
+ | `workspace` | string | 見 admin §2.1 | check-out 目錄 |
32
+
33
+ 實測失敗(沒有 remote):
34
+
35
+ ```
36
+ ERROR: Fossil command failed (exit code 1).
37
+ no "remote" repository defined
38
+ COMMAND: fossil chat url
39
+ WORKSPACE: /tmp/tw
40
+ ```
41
+
42
+ `remote` 只作用於這一條命令。
43
+
44
+ ---
45
+
46
+ ## 3. `fossil_chat_send`
47
+
48
+ ```bash
49
+ fossil chat send -m <message> [--file <abs path>] [--as NAME] [--remote URL]
50
+ ```
51
+
52
+ | 參數 | 類型 | 必填/預設 | 說明 |
53
+ | --- | --- | --- | --- |
54
+ | `message` | string | **必填** | 訊息正文(`-m`) |
55
+ | `file` | string | — | 附件;**相對路徑以 workspace 為基準**解析成絕對路徑 |
56
+ | `attachment_name` | string | — | 附件的顯示名(`--as`),必須配合 `file` |
57
+ | `remote` | string | — | 代替預設 remote |
58
+ | `workspace` | string | 見 admin §2.1 | check-out 目錄 |
59
+
60
+ 只給 `attachment_name` 不給 `file` 時,不 spawn fossil:
61
+
62
+ ```
63
+ ERROR: 'attachment_name' requires 'file'.
64
+ ```
65
+
66
+ 成功時 fossil 列印伺服器響應,工具追加 `Message sent to the chatroom.`
67
+
68
+ ---
69
+
70
+ ## 4. `fossil_chat_pull`
71
+
72
+ ```bash
73
+ fossil chat pull [--all] [--out <abs db file>] [--remote URL]
74
+ ```
75
+
76
+ | 參數 | 類型 | 必填/預設 | 說明 |
77
+ | --- | --- | --- | --- |
78
+ | `all` | boolean | `false` | `--all`:拉全部歷史,而不是只拉新訊息 |
79
+ | `out` | string | — | `--out`:把 CHAT 表存到獨立資料庫檔案(**相對路徑以 workspace 為基準**) |
80
+ | `remote` | string | — | 代替預設 remote |
81
+ | `workspace` | string | 見 admin §2.1 | check-out 目錄 |
82
+
83
+ 成功 note:`Chat history pulled into the local clone.`(用 `out` 時實際寫到該檔案)。
84
+
85
+ 需要在遠端有 setup 權限;普通使用者拉取會被伺服器拒絕。
86
+
87
+ ---
88
+
89
+ ## 5. `fossil_chat_read`
90
+
91
+ 直接讀 SQL(`fossil sql --readonly`),不聯網:
92
+
93
+ ```sql
94
+ SELECT * FROM chat ORDER BY msgid DESC LIMIT <limit>
95
+ ```
96
+
97
+ | 參數 | 類型 | 必填/預設 | 說明 |
98
+ | --- | --- | --- | --- |
99
+ | `limit` | number | `50` | 1..2000,最新在前 |
100
+ | `database` | string | — | 讀 `pull --out` 生成的歸檔庫(相對路徑以 workspace 為基準);省略則讀 clone |
101
+ | `workspace` | string | 見 admin §2.1 | — |
102
+
103
+ 輸出格式(每行一條):`<ISO 時間>Z <author>: <message>`,author 取 `xfrom`,缺失時取 `src`,
104
+ 再預設為 `unknown`;訊息體取 `xmsg`,缺失時取 `msg`,都缺失就輸出整行 JSON。
105
+
106
+ 沒有本地 chat 資料時專門給出指引(`no such table: chat`):
107
+
108
+ ```
109
+ ERROR: no local chat data found.
110
+ Run fossil_chat_pull (requires setup privilege on the remote) to download the chatroom,
111
+ or pass `database` pointing at an archive created with fossil_chat_pull + out.
112
+
113
+ ERROR: fossil sql failed.
114
+ Error: in prepare, no such table: chat
115
+ ```
116
+
117
+ 有表但為空 → `No chat messages stored locally.`
118
+
119
+ ---
120
+
121
+ ## 6. 典型流程
122
+
123
+ ```
124
+ fossil_chat_url # 確認 remote 可用
125
+ fossil_chat_send { message: 'standup: 今天做 wiki 匯出' }
126
+ fossil_chat_pull { all: true, out: 'chat-archive.db' }
127
+ fossil_chat_read { limit: 20, database: 'chat-archive.db' }
128
+ ```
129
+
130
+ 把歸檔庫換成 clone:`fossil_chat_pull {}` → `fossil_chat_read {}`。
131
+
132
+ ---
133
+
134
+ ## 7. 已知邊界
135
+
136
+ 1. **`send`/`pull` 需要網路與權限**,失敗資訊是 fossil 原文(`not authorized` / `no "remote" repository defined`)。
137
+ 2. **`read` 只讀本地**:沒 `pull` 過就沒有資料。
138
+ 3. **`--out` 的歸檔庫只是 CHAT 表**,不能當倉庫用。
139
+ 4. **時間格式化**:`mtime` 秒級(>1e12 視為毫秒)轉 ISO,去掉毫秒部分。
140
+ 5. **沒有刪除/編輯訊息的工具**(fossil chat 也沒有對應 CLI)。
141
+ 6. **`xfrom`/`src`、`xmsg`/`msg` 列名差異**已在格式化裡相容(不同 fossil 版本/表結構)。
142
+
143
+ ---
144
+
145
+ ## 8. 原始碼位置
146
+
147
+ | 檔案 | 內容 |
148
+ | --- | --- |
149
+ | `src/tools/chat.ts` | 4 個工具 + `formatChatRow` / `formatTime` |
150
+ | `src/core/sql.ts` | `runSql`(`fossil sql --readonly -json`,stderr 非空即失敗) |
151
+ | `src/core/fossil.ts` | `runFossil` / `renderOutcome` / `truncateOutput` |
152
+ | `src/config.ts` | `NETWORK_TIMEOUT_MS`(`FOSSIL_NETWORK_TIMEOUT_MS`) |
package/docs/forum.md ADDED
@@ -0,0 +1,146 @@
1
+ # Forum 能力(`-c f`)工具說明
2
+
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.1.3` 及之後,fossil 2.21 實測。
4
+
5
+ `-c f` 註冊 3 個工具,**全部只讀**:`fossil_forum_list` / `fossil_forum_read` / `fossil_forum_search`。
6
+
7
+ > 為什麼只讀:Fossil 2.x 沒有建立論壇帖的 CLI/JSON 介面,發帖只在 Web UI 裡。所以本能力直接讀
8
+ > fossil 存在 `event` / `blob` 表裡的 `F` 工件。
9
+
10
+ ---
11
+
12
+ ## 1. 資料來源
13
+
14
+ 論壇帖是類型為 `f` 的事件,正文是 `blob` 表裡的工件,工件格式:
15
+
16
+ ```
17
+ F <title> # 新主題
18
+ F <title> <parent-hash> # 回覆(parent 是 40~64 位十六進位制雜湊)
19
+ <body...> # 第一行之後都是正文
20
+ ```
21
+
22
+ 工具用的 SQL(`src/tools/forum.ts` 的 `forumEventsSql`):
23
+
24
+ ```sql
25
+ SELECT b.uuid AS uuid,
26
+ datetime(e.mtime) AS at,
27
+ e.user AS user,
28
+ e.comment AS comment,
29
+ content(b.uuid) AS body
30
+ FROM event e JOIN blob b ON b.rid = e.objid
31
+ WHERE e.type = 'f' [AND instr(lower(content(b.uuid)), lower('<query>')) > 0]
32
+ ORDER BY e.mtime DESC
33
+ LIMIT <limit>
34
+ ```
35
+
36
+ 搜尋用 `instr()` 而不是 `LIKE`:不需要轉義 `%` / `_`。字面量經 `escapeSqlLiteral()` 轉義。
37
+
38
+ 解析規則(`parseForumPost`):
39
+
40
+ - 工件首行必須以 `F ` 開頭,否則整段當作正文、標題回退成 `e.comment`。
41
+ - 首行最後一個 token 若匹配 `^[0-9a-f]{40,64}$` 且至少有兩個 token,則它是 `parent`,其餘是標題。
42
+
43
+ ---
44
+
45
+ ## 2. `fossil_forum_list`
46
+
47
+ 列出最近 N 個論壇事件,**最新在前**。
48
+
49
+ | 參數 | 類型 | 必填/預設 | 說明 |
50
+ | --- | --- | --- | --- |
51
+ | `limit` | number | `20` | 1..500,掃描多少個論壇事件 |
52
+ | `workspace` | string | 見 admin §2.1 | — |
53
+
54
+ 輸出每行:`<at> <10 位雜湊> <user> <title> <後綴>`,後綴三種:
55
+
56
+ - 根帖且視窗內有回覆:`(N replies)` / `(1 reply)`
57
+ - 根帖但沒有回覆:`(thread)`
58
+ - 回覆:`↳ reply in thread <根帖雜湊>`
59
+
60
+ 示例(一個根帖 + 一個回覆):
61
+
62
+ ```
63
+ 2026-11-17 00:23:27 c4d5e6f7a8 bob Welcome ↳ reply in thread a1b2c3d4e5
64
+ 2026-11-17 00:09:03 a1b2c3d4e5 alice Welcome (1 reply)
65
+ ```
66
+
67
+ 沒有帖子 → `No forum posts found in the last 20 forum events. …`(附帶只讀說明)。
68
+
69
+ ---
70
+
71
+ ## 3. `fossil_forum_read`
72
+
73
+ 列印整條執行緒:根帖 + 視窗內所有回覆,按時間深度優先展開,回覆縮排兩格。
74
+
75
+ ```bash
76
+ # 無外部命令:仍是 forumEventsSql + 記憶體裡的父子連結
77
+ ```
78
+
79
+ | 參數 | 類型 | 必填/預設 | 說明 |
80
+ | --- | --- | --- | --- |
81
+ | `thread` | string | **必填** | 根帖雜湊,或執行緒內**任意**帖的雜湊(支援前綴) |
82
+ | `limit` | number | `500` | 1..2000,掃描多少事件去找回復 |
83
+ | `workspace` | string | 見 admin §2.1 | — |
84
+
85
+ 真實輸出:
86
+
87
+ ```
88
+ [2026-11-17 00:09:03] a1b2c3d4e5 (alice) Welcome
89
+ hello all
90
+
91
+ [2026-11-17 00:23:27] c4d5e6f7a8 (bob) Re: Welcome
92
+ thanks
93
+ ```
94
+
95
+ 找不到(雜湊不在視窗內):
96
+
97
+ ```
98
+ ERROR: no forum post matching 'ffff' among the last 500 forum events. Increase 'limit' or run fossil_forum_list to find the thread hash.
99
+ ```
100
+
101
+ 實現要點:
102
+
103
+ - `resolvePost()` 先精確命中,再按前綴線性匹配;給回覆的雜湊也能定位執行緒(`findRoot()` 沿 `parent` 回溯,
104
+ 帶環檢測)。
105
+ - 視窗外看不到的父帖會讓 `findRoot` 停在當前節點,此時該帖被當作根帖渲染。
106
+
107
+ ---
108
+
109
+ ## 4. `fossil_forum_search`
110
+
111
+ 對**正文與標題**做大小寫不敏感的子串搜尋(SQL 側 `instr(lower(...))`)。
112
+
113
+ | 參數 | 類型 | 必填/預設 | 說明 |
114
+ | --- | --- | --- | --- |
115
+ | `query` | string | **必填** | 子串,大小寫不敏感 |
116
+ | `limit` | number | `20` | 1..200,**最多返回多少條匹配** |
117
+ | `workspace` | string | 見 admin §2.1 | — |
118
+
119
+ 輸出每條兩塊:`<at> <hash> <user> <title>` + 縮排兩格的正文(截到 400 字元,超出加 `…`)。
120
+
121
+ 無匹配 → `No forum posts match '<query>'.`
122
+
123
+ 注意:`limit` 同時是 SQL 的 `LIMIT`,匹配數超過 `limit` 時只返回最新的 `limit` 條。
124
+
125
+ ---
126
+
127
+ ## 5. 已知邊界
128
+
129
+ 1. **只讀**:不能發帖/編輯/刪除。需要寫論壇請用 `fossil ui` 或 Web 介面。
130
+ 2. **視窗限制**:`list` / `read` 只掃描最近 N 個論壇事件,更早的帖子需要調大 `limit`
131
+ (`read` 最大 2000,`list` 最大 500)。
132
+ 3. **雜湊短於 10 位時 `list` 顯示會被截斷到 10 位**;`read` 接受任意長度前綴(含更短)。
133
+ 4. **標題裡不能含結尾的雜湊形態**:標題最後一個是 40~64 位 hex 時會被當成 parent。
134
+ 5. **搜尋不帶分頁**,深層歷史需配合 `limit`。
135
+ 6. **所有工具都要求 check-out**(fossil sql 需要倉庫上下文)。
136
+
137
+ ---
138
+
139
+ ## 6. 原始碼位置
140
+
141
+ | 檔案 | 內容 |
142
+ | --- | --- |
143
+ | `src/tools/forum.ts` | 3 個工具 + `forumEventsSql` / `parseForumPost` / `resolvePost` / `findRoot` / `countDescendants` / `renderPost` |
144
+ | `src/core/sql.ts` | `runSql`(只讀 `fossil sql --readonly -json`) |
145
+ | `src/core/fossil.ts` | `escapeSqlLiteral` / `truncateOutput` / `TextResult` |
146
+ | `src/tools/common.ts` | `workspaceParam` |
@@ -0,0 +1,39 @@
1
+ # 提示(MCP prompts)
2
+
3
+ 伺服器依啟用的能力註冊下列提示。客戶端以 `prompts/list` 取得清單、`prompts/get` 取回內容,
4
+ 再把回傳的使用者訊息交給模型執行;工具本身仍由 `tools/call` 呼叫。
5
+
6
+ | 提示 | 作用 | 需要的能力 |
7
+ | --- | --- | --- |
8
+ | `fossil-review-changes` | 讀 `fossil_status` / `fossil_changes` / `fossil_diff`,分組說明未提交的改動並建議提交訊息 | `v` |
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` |
12
+ | `fossil-bisect-hunt` | 標記 good/bad、反覆 `fossil_bisect` 收斂到出問題的 check-in,最後 `reset` 並 `fossil_update` 復原 | `v` |
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` |
15
+ | `fossil-ticket-triage` | 讀 `fossil_ticket_list`、分組,再用 `fossil_ticket_update` 更新正在處理的工單狀態 | `t` |
16
+
17
+ 提示只在對應能力啟用時註冊;伺服器在至少一個提示可用時宣告 `prompts` 能力。
18
+
19
+ ## 呼叫範例
20
+
21
+ ```json
22
+ {"jsonrpc":"2.0","id":2,"method":"prompts/get",
23
+ "params":{"name":"fossil-review-changes","arguments":{"workspace":"/srv/checkout"}}}
24
+ ```
25
+
26
+ 回傳:
27
+
28
+ ```json
29
+ {"messages":[{"role":"user","content":{"type":"text","text":"Review the uncommitted work in this Fossil check-out.\nPass `workspace: \"/srv/checkout\"` to every tool call.\n…"}}]}
30
+ ```
31
+
32
+ `workspace` 參數只是把路徑寫進提示文字;工具呼叫仍要各自帶 `workspace`。
33
+
34
+ ## 原始碼位置
35
+
36
+ | 檔案 | 內容 |
37
+ | --- | --- |
38
+ | `src/prompts.ts` | `registerPrompts`,依能力註冊提示並組出提示文字 |
39
+ | `src/server.ts` | `createServer` 在註冊完工具後呼叫 `registerPrompts` |
@@ -0,0 +1,179 @@
1
+ # Tickets 能力(`-c t`)工具說明
2
+
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.1.3` 及之後,fossil 2.21 實測。
4
+
5
+ `-c t` 註冊 4 個工具:`fossil_ticket_list` / `fossil_ticket_show` / `fossil_ticket_create` / `fossil_ticket_update`。
6
+ (check-out 用 admin 的 `fossil_init` / `fossil_open`,組合啟用寫 `-c at`。)
7
+
8
+ ---
9
+
10
+ ## 1. 通用約定
11
+
12
+ - 所有工具都要 **check-out**(`.fslckout`);只有倉庫檔案時報 `use --repository or -R to specify the repository database`。
13
+ - `workspace` 語義見 `docs/admin.md` §2.1。
14
+ - 寫入類工具成功後 fossil 自己會列印 `<cmd> succeeded for <uuid>`,工具再追加一行 note。
15
+ - ticket 的欄位集合由倉庫的 ticket 表定義(預設 `title/status/type/subsystem/priority/severity/comment`)。
16
+
17
+ ---
18
+
19
+ ## 2. `fossil_ticket_list`
20
+
21
+ ```bash
22
+ fossil ticket show <report> # report 預設 '1'
23
+ ```
24
+
25
+ | 參數 | 類型 | 必填/預設 | 說明 |
26
+ | --- | --- | --- | --- |
27
+ | `report` | string | `'1'` | 報表編號或名字 |
28
+ | `workspace` | string | 見 admin §2.1 | — |
29
+
30
+ 真實輸出(預設報表 1,製表符分隔):
31
+
32
+ ```
33
+ bgcolor # mtime type status subsystem title
34
+ #f2dcdc 9907979d87 2026-11-17 00:22:33 Bug Open Login broken
35
+ ```
36
+
37
+ 空倉庫 → `No tickets.`
38
+
39
+ **SQL 回退**:倉庫裡沒有定義該報表時(`fossil ticket show` 失敗),工具改用
40
+
41
+ ```sql
42
+ SELECT substr(tkt_uuid, 1, 10) AS id, title, status FROM ticket ORDER BY tkt_mtime DESC
43
+ ```
44
+
45
+ 並透過 `fossil sql --readonly -header -column` 渲染(只讀),輸出首行標註來源:
46
+
47
+ ```
48
+ --- TICKET LIST (SQL fallback: report '99' is unavailable) ---
49
+ id title status
50
+ ---------- ------------ ------
51
+ 9907979d87 Login broken Fixed
52
+ ```
53
+
54
+ 兩條路都失敗時返回**第一次**(`ticket show`)的原始錯誤,資訊量更大。
55
+
56
+ ---
57
+
58
+ ## 3. `fossil_ticket_show`
59
+
60
+ ```bash
61
+ fossil ticket show <report> ["<filter>"] [-l <separator>] [-q]
62
+ ```
63
+
64
+ | 參數 | 類型 | 必填/預設 | 說明 |
65
+ | --- | --- | --- | --- |
66
+ | `report` | string | `'0'` | 報表編號或標題;`0` 列出 ticket 表的全部欄位 |
67
+ | `filter` | string | — | 追加的 WHERE 條件,例如 `status = 'Open'` |
68
+ | `separator` | string | 製表符 | 欄位分隔字元(`-l`) |
69
+ | `quote` | boolean | `false` | 把空白、換行等編成 `\s`、`\n`(`-q`) |
70
+ | `workspace` | string | 見 admin §2.1 | — |
71
+
72
+ 真實輸出(`report: '0'`):
73
+
74
+ ```
75
+ tkt_id tkt_uuid tkt_mtime tkt_ctime type status subsystem priority severity foundin private_contact resolution title comment
76
+ 1 fd1ede011a04a314991efbcd0e94f6699b8a5b6e 2461361.61752586 2461361.61752586 Open Probe ticket
77
+ ```
78
+
79
+ 加了 `filter` 之後只留下符合的列:
80
+
81
+ ```
82
+ $ fossil ticket show 0 "status = 'Open'"
83
+ 1 fd1ede011a04a314991efbcd0e94f6699b8a5b6e … Open … Probe ticket
84
+ ```
85
+
86
+ `filter` 直接接在報表名後面,是 fossil 自己的 WHERE 片段,不經 SQL 解析器;寫錯時 fossil 會以
87
+ `no such column` 之類的錯誤結束。
88
+
89
+ ## 4. `fossil_ticket_create`
90
+
91
+ ```bash
92
+ fossil ticket add title <title> status <status> [field value ...]
93
+ ```
94
+
95
+ | 參數 | 類型 | 必填/預設 | 說明 |
96
+ | --- | --- | --- | --- |
97
+ | `title` | string | **必填** | 標題 |
98
+ | `status` | string | `'Open'` | 初始狀態,如 `Open` / `Verified` / `Fixed` |
99
+ | `additional_fields` | string[] | — | **扁平**的 field/value 序列,偶數個 |
100
+ | `workspace` | string | 見 admin §2.1 | — |
101
+
102
+ `additional_fields: ['type','Bug','priority','High']` 拼成
103
+ `fossil ticket add title Login broken status Open type Bug priority High`。
104
+
105
+ 真實輸出:
106
+
107
+ ```
108
+ ticket add succeeded for 9907979d878e90d1b6050f7690adbbed228586b5
109
+
110
+ Ticket created.
111
+ ```
112
+
113
+ 奇數個 `additional_fields` 時**不 spawn fossil**,直接:
114
+
115
+ ```
116
+ ERROR: additional_fields must contain an even number of entries (field, value, field, value, ...).
117
+ ```
118
+
119
+ 注意:`title`/`status` 之外的欄位由 Fossil 的 ticket 表定義決定必填性;
120
+ 用不存在的欄位名時 fossil 會報 `no such field: xxx`。
121
+
122
+ ---
123
+
124
+ ## 5. `fossil_ticket_update`
125
+
126
+ ```bash
127
+ fossil ticket set <ticket_id> <field_name> <field_value>
128
+ ```
129
+
130
+ | 參數 | 類型 | 必填/預設 | 說明 |
131
+ | --- | --- | --- | --- |
132
+ | `ticket_id` | string | **必填** | 完整 UUID 或列表裡顯示的 10 位前綴 |
133
+ | `field_name` | string | **必填** | 要改的欄位(`status`/`subsystem`/`priority`/`comment`…) |
134
+ | `field_value` | string | **必填** | 新值,可為空字串(清空欄位) |
135
+ | `workspace` | string | 見 admin §2.1 | check-out 目錄 |
136
+
137
+ 真實輸出:
138
+
139
+ ```
140
+ ticket set succeeded for 9907979d878e90d1b6050f7690adbbed228586b5
141
+
142
+ Ticket '9907979d87' updated: status = 'Fixed'.
143
+ ```
144
+
145
+ 一次只能改一個欄位;改多個欄位就呼叫多次(每次都會產生一條新的 ticket 變更事件)。
146
+
147
+ ---
148
+
149
+ ## 6. 典型流程
150
+
151
+ ```
152
+ fossil_ticket_create { title: 'Login broken', additional_fields: ['type','Bug','priority','High'] }
153
+ fossil_ticket_show { report: '0', filter: "status = 'Open'" } # 只列還沒處理的
154
+ fossil_ticket_list
155
+ fossil_ticket_update { ticket_id: '9907979d87', field_name: 'status', field_value: 'Fixed' }
156
+ fossil_ticket_list # 狀態列已變
157
+ ```
158
+
159
+ 用 `fossil_timeline { type_filter: 't' }`(VCS 組)可以看到 ticket 變更事件。
160
+
161
+ ---
162
+
163
+ ## 7. 已知邊界
164
+
165
+ 1. **`ticket_id` 原樣傳給 fossil**,寫錯時得到 `no such ticket: xxx` 錯誤。
166
+ 2. **報表依賴倉庫定義**:報表不存在時靜默走 SQL 回退,輸出格式與報表不同(列更少)。
167
+ 3. **欄位名原樣傳給 fossil**,非法欄位由 fossil 拒絕。
168
+ 4. **沒有刪除 ticket 的工具**:刪除需要在 ticket 裡改 `status` 或直接操作資料庫,屬於設計取捨。
169
+ 5. **日期/時間欄位**用文字傳入(fossil ticket 表的 `comment` 支援 wiki 語法)。
170
+
171
+ ---
172
+
173
+ ## 8. 原始碼位置
174
+
175
+ | 檔案 | 內容 |
176
+ | --- | --- |
177
+ | `src/tools/tickets.ts` | 4 個工具 + `TICKET_FALLBACK_SQL` + 奇偶校驗 |
178
+ | `src/core/fossil.ts` | `runFossil` / `renderOutcome` / `truncateOutput` |
179
+ | `src/tools/common.ts` | `workspaceParam` |