xEdit 自動化 — 中樞技能
此技能是所有 xEdit 工作的必載入口點。它是「使用哪條路徑」和「絕對不能做什麼」的單一事實來源。專門的任務技能(例如 xedit-conflict-audit)會繼承其路由、反模式和驗證紀律;它們不會重複這些內容。
工具箱一覽(逐步揭露,r6 感知)
分支版 xEdit 守護程式最好視為一個逐步揭露的表面:從小型的 MCP 意圖工具開始,詢問即時守護程式支援哪些 r6 功能區塊,然後僅在相應的 system.capabilities.supports.* 金鑰存在時,才切換到更豐富的一次呼叫模式。
- 發現與會議 —
xedit_session、xedit_list_capabilities。每次對話先呼叫xedit_session。然後呼叫一次xedit_list_capabilities以查看命令摘要、contractVersionExpected和 r6supports.*錨點。 - 讀取記錄與衝突 —
xedit_find_record、xedit_read_record、xedit_inspect_conflicts。這些是 W2(衝突審計)的骨幹;當 W2 需要一個尚未由任何意圖工具公開的 r6 回應區塊時,分支到原子透傳。 - 原子透傳 —
xedit_call(command, args)。用於尚未有對應意圖工具的任何原生守護程式命令。它仍會執行完整管線(驗證 → 狀態 → 規則 → 審計)。當意圖工具不適用時,請使用它。
如需深入參考資料,請先查詢結構化的 BGS KB(bgs_kb_query / bgs_kb_get)。深入參考記錄位於 knowledge/bgs-kb/packs/core/records/xedit/(可透過 bgs_kb_query / bgs_kb_get 查詢)。
路由原則(使用哪條路徑)
| 任務形狀 | 路徑 |
|---|---|
| 高頻已知意圖(審計衝突、讀取記錄、執行任務、撰寫補丁) | MCP 意圖工具 |
| 新穎 / 除錯 / 原生命令的自由組合 | MCP 原子透傳:xedit_call(command, args) — 仍在框架內 |
| 探索性原子操作風暴(試錯、重複讀取評估、假設測試) | 委派給一個唯讀調查員子代理,並載入此技能;子代理耗用自己的上下文,返回一個提煉的摘要 |
| 大型可形式化的批量修改 | MCP xedit_run_script(批次 4+)搭配試執行 + 快照 |
| 守護程式明確處於預設(非 MCP)模式,僅限手動除錯 | 直接使用 xedit-client.ps1 是可以接受的 — 但僅限於使用者已明確接受風險且守護程式不在 -automation-mcp-mode 模式時 |
代理絕不應有理由繞過 MCP。 原子透傳的存在就是為了處理這種情況。
補丁創作判斷
概述
補丁創作的目標不是「消除紅色」。它是一個小的相容性論證:保留當前的勝者,僅轉發仍然應該存續的上游值,並留下一個可逆的補丁插件,其內容說明了您的意圖。排序是一個單一選擇的槓桿;補丁是您同時保留兩個模組預期值的方式。但「原則上正確」不等於「套件規模上正確」:如果計劃是因為「xEdit 可以修復任何東西」而拼接每個 FormID,那麼這個計劃已經失敗。
當您準備透過 MCP 創作或判斷一個補丁時,請使用此部分。當問題仍然是「誰勝出、誰衝突、應該用補丁還是重新排序」時,請先使用 xedit-conflict-audit。該技能擁有補丁與重新排序決策的所有權;此部分僅擁有您即將撰寫的補丁是否格式良好的決定權。
決策流程:此補丁格式是否良好?
digraph patch_authoring_judgment {
// 待關閉存檔會阻止生命週期操作;請參閱下方的髒狀態和重啟控制。重新啟動不是持久性機制。
rankdir=TB;
node [shape=box];
start [shape=doublecircle, label="需要補丁?"];
audit [label="審計實際勝者 + 衝突欄位\n(如果尚未完成,則使用 xedit-conflict-audit)"];
reorder [shape=diamond, label="重新排序是否足夠\n而不會遺失所需的值?"];
no_patch [shape=doublecircle, label="無需補丁:重新排序 / 保留勝者\n然後驗證回讀"];
winner [label="複製/目標為目前的勝者\n而非較舊的敗者"];
intent [label="命名要轉發的每個值\n它的作用是什麼?為什麼它應該存續?"];
noise [shape=diamond, label="是否存在任何未更改的複製值\n或綠色/ITM 風格的雜訊?"];
clean [label="移除未更改/無意圖的值"];
refs [shape=diamond, label="正在刪除或標記刪除\n記錄/元素?"];
referenced [label="執行 referenced_by / reference 審計\n如果後果未知,則停止"];
esl [label="刻意選擇補丁形式\n通常在安全情況下使用標記為 ESL 的 ESP;如果排序自由度很重要,則避免原生 ESL/ESM"];
reversible [shape=diamond, label="獨立可逆補丁\n(不直接編輯原始模組,不進行非託管覆蓋溢出)?"];
fix_shape [label="移至受管理的 MO2 模組\n或建立專用補丁插件"];
verify [label="儲存 + 重啟 + 回讀\n勝出覆蓋顯示預期的值"];
pass [shape=doublecircle, label="格式良好的補丁"];
start -> audit -> reorder;
reorder -> no_patch [label="是"];
reorder -> winner [label="否,需要合併值"];
winner -> intent -> noise;
noise -> clean [label="是"];
noise -> refs [label="否"];
clean -> refs;
refs -> referenced [label="是"];
refs -> esl [label="否"];
referenced -> esl;
esl -> reversible;
reversible -> fix_shape [label="否"];
reversible -> verify [label="是"];
fix_shape -> verify -> pass;
// 合約 0.23 待處理存檔使用 xedit_flush;單獨重啟不是證明。
verify [label="儲存 + 檢查待處理狀態;如果需要,使用 xedit_flush;進行全新回讀"];
}
延遲存檔修正: 圖表中歷史上的
儲存 + 重啟 + 回讀節點已被取代。如果session.save報告非零的savePendingShutdownCount,請檢查xedit_dirty,然後在合約 0.23 守護程式上使用xedit_flush。該工具會驗證排空回應並確認守護程式承諾的自我退出。partial或未知的lastFlush不是持久性證明。在存在活動待處理佇列時,正常的停止/重啟仍然被拒絕;force:true會放棄狀態,並且絕不能作為持久性的證據。
創作檢查清單
- 轉發勝者。 遊戲讀取 FormID 的最終/勝出覆蓋。從目前的勝者建立補丁,然後僅轉發仍然需要存續的較舊模組值。
- 沒有未更改的貨物。 如果一個複製的值沒有改變意義,它就是 ITM 風格的雜訊,而不是相容性。移除它,除非您可以說明為什麼它被有意保留。
- 補丁作為獨立圖層。 不要僅僅因為某個模組今天是右側欄位,就將值直接拖入該原始模組。補丁應該可以透過停用/移除補丁圖層來逆轉,而不是透過手動刪除他人插件中的欄位。
- 保留引用。 如果刪除或標記刪除進入計劃,請停止並先執行被引用/回讀路徑。未知的引用意味著未知的影響範圍。
- 刻意選擇插件形式。 普通的相容性補丁通常希望在安全的情況下,使用正常的 ESP 排序自由度加上 ESL 標記。原生 ESL/ESM 的載入順序行為不是免費的整潔升級。
- 良好補丁 vs 權宜補丁。 一個良好補丁對每個轉發的值都有命名的意圖,並減少了衝突債務。一個權宜補丁會複製整個記錄、編輯原始模組、或嘗試拼接每個 FormID,因為排序被視為無關緊要。
KB 查詢紀律
此判斷部分與遊戲無關。查詢 KB 以獲取特定遊戲的補丁陷阱、記錄系列注意事項和當前工具鏈事實,而不是將它們固化在此處。
bgs_kb_query({ query: "xedit patch authoring gotchas", domains: ["xedit", "load-order"], games: ["<current game>"] })
如果 KB 無回應,請標記 [GAP] 並將補丁規則保留在框架層級,而不是發明一個特定遊戲的指導原則。
紅旗(STOP)
| 想法 | 現實 |
|---|---|
| 「它是紅色的,所以複製左邊的值。」 | 紅色是提示你去檢查。它不是一個裁決,表示失敗的值應該存續。 |
| 「最右邊的模組是錯的;我會直接編輯它。」 | 那麼你就把原始模組變成了補丁。使用一個獨立的覆蓋補丁,以便乾淨地逆轉。 |
| 「排序不重要,因為 xEdit 可以修補任何東西。」 | 原則上,是的;橫跨數十萬個 FormID,則不是。使用排序來減少修復債務,然後修補有意義的剩餘部分。 |
| 「綠色/未更改的複製值是無害的。」 | 它們是沒有意圖的貨物。如果它們沒有改變意義,就移除它們。 |
| 「原生 ESL 比標記為 ESL 的 ESP 更乾淨。」 | 原生 ESL/ESM 可能會失去正常的排序自由度。當安全的補丁形狀時,使用標記為 ESL 的 ESP。 |
| 「這看起來沒有使用;刪除它。」 | 先檢查被引用。在未了解引用前進行刪除是未知的影響範圍。 |
合理化藉口
| 藉口 | 現實 |
|---|---|
| 「我只會把一個欄位拖入勝出的插件。」 | 一個欄位仍然是對原始模組的編輯。建立一個補丁圖層,否則未來的你將一個接一個地手動移除散落的欄位。 |
| 「補丁應該保留任何模組觸及過的所有內容。」 | 保留意圖,而不是歷史。有些編輯是模組的核心;有些是偶然的作者偏好,應該輸給系統規則。 |
| 「我不知道這個欄位是做什麼的,所以我會複製看起來合理的版本。」 | 未知的欄位意義是一個研究任務,而不是擲骰子。閱讀記錄結構、CK/維基/社群範例以及實際的套件內行為。 |
| 「覆蓋沒關係;MO2 會處理它。」 | 覆蓋是溢出。一個真正的補丁屬於一個受管理的模組圖層,其名稱要使未來的你能夠理解。 |
| 「回應說 OK;補丁完成了。」 | 補丁的接受度是在儲存/重啟後,勝出覆蓋的回讀,其中預期的值可見且沒有未預期的貨物。 |
R6 逐步揭露能力檢查
不要假設每個守護程式都是 r6。讀取一次 xedit_list_capabilities 並根據下面的支援金鑰進行分支。在 pre-r6 守護程式上,回退到較舊的顯式記錄清單/子元素遍歷/每記錄循環模式;在 r6+ 守護程式上,使用一次呼叫或分頁感知形式以減少往返次數並保留上下文。
| 能力金鑰 | 合約 | 偏好此模式 | KB 記錄 |
|---|---|---|---|
supports.childGroupNavigation | 0.13 | 透過 elements.children 存根導航 CELL/WRLD/DIAL/QUST 的子群組 | xedit.childgroup-navigation.v1 |
supports.createParentSpec | 0.16 / 0.18 | 使用 records.create 的 parent 直接在父級子群組下建立記錄 | xedit.records-create-parent-spec.v1 |
supports.elementsChildrenPagination | 0.17 | 使用 limit / offset 對 elements.children 進行分頁 | xedit.elements-children-pagination.v1 |
supports.reverseNavigation | 0.19 | 添加 includeParents:true 並讀取 relations.parents | xedit.reverse-navigation.v1 |
如需完整的 r6 合約差異,請查詢 KB 記錄 xedit.r6-contract-summary.v1。
子群組導航(supports.childGroupNavigation)
在 r6+ 守護程式上,CELL、WRLD、DIAL 和 QUST 記錄上的 elements.children 會返回一個虛擬子條目,其 kind: "child_group"。將該條目視為唯讀的導航存根,而不是一個真正的可變元素。
一次使用一個世代:
elements.children({ file, formId, path: "\\Child Group" })
elements.children({ file, formId, path: "\\Child Group\\Persistent" })
elements.children({ file, formId, path: "\\Child Group\\Temporary" })
elements.children({ file, formId, path: "\\Child Group\\Visible when Distant" })
elements.children({ file, formId, path: "\\Child Group\\Block X, Y" })
elements.children({ file, formId, path: "\\Child Group\\Block X, Y\\Sub-Block M, N" })
- 僅遍歷下一層;當一個頁面或一個子群組標籤足夠時,不要請求整個樹。
\\Child Group...路徑是合成的並且是唯讀的。修改操作必須使用扁平的 FormID 定位器({ file, formId })或records.create.parent規格;不要將合成的定位器路徑傳遞給修改器。- 對於 WRLD 細胞,根據目標子群組使用
Persistent或區塊/子區塊/座標路線。 - 深入參考:
xedit.childgroup-navigation.v1。
elements.children 分頁(supports.elementsChildrenPagination)
在 r6+ 守護程式上,elements.children 接受 limit 和 offset:
elements.children({ file, formId, path, limit: 200, offset: 0 })
limit被限制在 1-1000,預設為 200。- 回應包括
count、total、offset和truncated。 - 如果
truncated為 true,保持相同的limit,將count加到offset,然後獲取下一頁,直到覆蓋所有資料。 - 不要假設 CELL 子群組很小:FO4 原版 CELL
00000025的Temporary包含 742 筆記錄。 - 深入參考:
xedit.elements-children-pagination.v1。
反向導航(supports.reverseNavigation)
在 r6+ 守護程式上,當你需要知道所有權或包含關係而無需第二個操作時,添加 includeParents: true。支援的讀取呼叫包括:
records.getrecords.find_by_form_id/records.find_by_editor_id以及 MCP 包裝器,如xedit_find_recordrecords.master_or_selfrecords.winning_overrideelements.getelements.children
回應可能包括:
relations.parents: [{ locator, object }, ...]
父級採用最近優先的順序,守護程式深度上限為 16。這是對「哪個 CELL 擁有這個 REFR?」或「哪個 QUST/DIAL 群組包含這個子項?」的首選答案。使用父級鏈作為回讀證據;除非缺少支援金鑰,否則不要建立自訂的反向索引循環。深入參考:xedit.reverse-navigation.v1。
records.create 父級規格(supports.createParentSpec)
在子群組中建立可變記錄是 r6 限制的操作,並且仍然需要正常的 MCP 修改同意路徑。當支援時,明確指定目標父級,而不是嘗試修改合成的 \\Child Group