Run any Skill in Manus with one click

doc-shard-manager

Stars3

Forks0

UpdatedMay 9, 2026 at 00:22

文件分片管理 SKILL — 管理「大型文件 → shard 目錄群」的生命週期。 USE FOR: 任何大型 .md / .json 檔案需要拆分為小分片、更新分片後重建索引、驗證分片完整性，或新增 shard 目錄給新的大型文件。 DO NOT USE FOR: 程式碼編輯、UI layout 調整、任務卡狀態更新（那些直接改對應 JSON）。

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

eaglhuang

eaglhuang/3klife

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

Doc Shard Manager SKILL

概念與用途

大型文件（>6000 tokens）會觸發 Token 節流警戒線。解法是將其拆分為「shard 目錄群」：

原始大檔變成一個輕量的「索引 stub」（< 1 KB），列出各分片路徑
實際內容拆入各 shard 檔案（通常 3–10 KB 各自獨立）
Agent 只按需讀取相關分片，大幅降低每輪 token 消耗

本 SKILL 的核心工具是 tools_node/shard-manager.js，設定檔為各 shard 目錄下的 .shardrc.json。

本專案現有 Shard Groups

索引 stub	Shard 目錄	分片數	類型	備註
`docs/keep.md (doc_index_0011)` (doc_index_0011)	`docs/keep-shards/`	4	`markdown-h2`	主共識文件
`docs/ui-quality-todo.json`	`docs/tasks/`	4	`json-array`	按 id 前綴分
`docs/cross-reference-index.md (doc_index_0005)` (doc_index_0005)	`docs/cross-ref/`	3	`markdown-h2`	A/B/C 節
`docs/tasks/tasks-ui.json`	`docs/tasks-ui-shards/`	2	`json-array`	按 status 細拆（子分片，`keepSourceIntact`）
`docs/tasks/tasks-ui.json`	`docs/tasks/tasks-ui/`	4	`auto-parts`	auto-split 從 112 KB 等分為 4 parts
`docs/tasks/tasks-dc.json`	`docs/tasks/tasks-dc/`	2	`auto-parts`	auto-split 從 41 KB 等分為 2 parts

可用命令

# 初始分片（首次拆分 or 原始大檔有重大更新後重跑）
node tools_node/shard-manager.js shard  <shardDir>

# 反向維護：分片有修改 → 重建索引 stub
node tools_node/shard-manager.js rebuild-index  <shardDir>

# 完整性驗證（CI 前 / 收工前必跑）
node tools_node/shard-manager.js validate  <shardDir>

# 狀態瀏覽（大小 + 修改時間）
node tools_node/shard-manager.js status  <shardDir>

# 一次分片多個 shard 目錄
node tools_node/shard-manager.js shard-all  docs/keep-shards docs/tasks docs/cross-ref

# 偵測未管理的大型文件（> 6 KB）
node tools_node/shard-manager.js scan  docs
node tools_node/shard-manager.js scan  docs  --threshold 10   # 自訂門檻（KB）

# 動態等分拆分：偵測 > 門檻的分片並自動產生 N 個 parts
node tools_node/shard-manager.js auto-split  <shardDir>
node tools_node/shard-manager.js auto-split  docs/tasks  --threshold 30   # 預設 30 KB

auto-split 特性：

計算每個現有 shard 的大小，超過門檻才觸發
分片數 N = ceil(shardSize / threshold)，動態決定，不必寫死
輸出到 <shardDir>/<shardName>/ 子目錄，.shardrc.json 標記 _autoGenerated: true
re-run auto-split 會依最新 shard 內容重新產生 parts（冪等操作）
validate 執行 >40 KB 警告，並遞迴驗證 auto-parts 子目錄

Workflow A：維護既有分片（最常見）

觸發時機：某個 shard 檔案的內容被修改（加新條目、更新狀態、新增章節等）。

Step 1 — 直接編輯對應分片

不要改索引 stub，直接找到對應的 shard 檔案修改：

新的 keep 共識 → 對應的 docs/keep-shards/keep-*.md
任務狀態 → docs/tasks/tasks-<prefix>.json
交叉索引 → docs/cross-ref/cross-ref-*.md

Step 2 — 重建索引

node tools_node/shard-manager.js rebuild-index docs/keep-shards
# 或
node tools_node/shard-manager.js rebuild-index docs/tasks
# 或
node tools_node/shard-manager.js rebuild-index docs/cross-ref

→ 索引 stub 自動更新為最新分片大小。

Step 3 — 驗證

node tools_node/shard-manager.js validate docs/keep-shards

Workflow B：全新大型文件 → 新 Shard Group

觸發時機：遇到 > 6000 tokens 的新文件需要拆分。

Step 1 — 規劃拆分策略

文件類型	建議 `type`	拆分依據
Markdown 筆記（有 `##` 章節）	`markdown-h2`	章節前綴 regex（如 `^(1
JSON 陣列（如任務清單）	`json-array`	每 item 的特定 field 值 regex

目標：每個 shard ~3–10 KB，單份讀入不超過 6000 tokens（約 4 KB）。

Step 2 — 建立 shard 目錄與 .shardrc.json

docs/
  my-new-large-file.md         ← 原始大檔（稍後會變成 stub）
  my-new-shards/               ← 新建目錄
    .shardrc.json              ← 設定檔（見下方格式）
    README.md                  ← 選填：給人讀的說明

.shardrc.json 格式（markdown-h2）：

{
  "version": 1,
  "source": "../my-new-large-file.md",
  "indexTitle": "My Document Title",
  "indexPath": "docs/my-new-large-file.md",
  "type": "markdown-h2",
  "preambleShard": "shard-a",
  "defaultShard": "shard-a",
  "shards": [
    { "name": "shard-a", "title": "A 部分（§1–§5）",  "pattern": "^[1-5]\\." },
    { "name": "shard-b", "title": "B 部分（§6–§10）", "pattern": "^([6-9]|10)\\." }
  ]
}

.shardrc.json 格式（json-array）：

{
  "version": 1,
  "source": "../items.json",
  "indexTitle": "Items Index",
  "type": "json-array",
  "arrayPath": "items",
  "splitField": "category",
  "defaultShard": "items-other",
  "shards": [
    { "name": "items-a", "title": "Category A",  "pattern": "^A-" },
    { "name": "items-b", "title": "Category B",  "pattern": "^B-" },
    { "name": "items-other", "title": "Others", "pattern": "." }
  ]
}

Step 3 — 執行分片

node tools_node/shard-manager.js shard docs/my-new-shards

→ 產生各 shard 檔案，原始大檔自動被索引 stub 取代。

Step 4 — 驗證

node tools_node/shard-manager.js validate docs/my-new-shards

Step 5 — 更新相關 Guard 文件

若新的 shard group 對應本專案的重要参考文件，請同步更新：

docs/keep.summary.md (doc_index_0012) (doc_index_0012) — 新增分片路徑提示
.github/instructions/token-guard.instructions.md (doc_ai_0015) (doc_ai_0015) — 新增禁止整份讀入的規則

Workflow C：原始大檔有重大更新

若大檔有大量新章節（非單章節修改），需重新執行 shard：

# 1. 先確認大檔有原始內容（不是 stub）
# 2. 若已是 stub，從 git 恢復原版或手動合併分片
git show HEAD:docs/keep.md (doc_index_0011) > docs/keep.md (doc_index_0011)   # 範例

# 3. 重新分片
node tools_node/shard-manager.js shard docs/keep-shards

# 4. 驗證
node tools_node/shard-manager.js validate docs/keep-shards

Pattern 注意事項

.shardrc.json 的 pattern 欄位是 JavaScript 正規表達式字串，作用於 h2 標題除去前置 ## 之後的文字（markdown-h2）或 splitField 欄位值（json-array）。

常見情境	推薦 pattern
`## 3. 標題`	`"^3\\."`
`## 2b. 標題`	`"^2b\\."`
`## P0. 標題`	`"^P0\\."`
`## A. 標題`	`"^A\\."`
id 以 `UI-` 開頭	`"^UI-"`
fallback（任何）	`"."`

多章節 alternation："^(3|4|5|6|13)\\." 匹配 3.、4.、5.、6.、13.。

警告：避免使用過短的前綴（如 "^1" 不加 \\.），否則會誤匹配 10.、11. 等。

Workflow D：子分片（Sub-Shard）— 針對仍然過大的分片細拆

觸發時機：某個 shard 仍然 > 30 KB（例如 tasks-ui.json 112 KB），需要依另一個欄位再次細拆。

關鍵旗標："keepSourceIntact": true — 告訴 shard-manager 不要用 index stub 覆蓋來源檔（因為來源本身是父層的 shard 檔）。

範例：docs/tasks-ui-shards/.shardrc.json

{
  "version": 1,
  "source": "../tasks/tasks-ui.json",
  "type": "json-array",
  "arrayPath": "tasks",
  "splitField": "status",
  "keepSourceIntact": true,
  "shards": [
    { "name": "tasks-ui-open", "title": "Active（open + in-progress）", "pattern": "^(open|in-progress)$" },
    { "name": "tasks-ui-done", "title": "Done（done + completed）",   "pattern": "^(done|completed)$" }
  ]
}

分片讀取策略：

只需看待辦事項 → 讀 docs/tasks-ui-shards/tasks-ui-open.json（約 35 KB）
查歷史已完成 → 讀 docs/tasks-ui-shards/tasks-ui-done.json（約 71 KB）

Workflow F：Auto-Split — 動態等分過大的分片

觸發時機：某 shard 超過 30 KB，且無法透過欄位/章節路由進一步細分，需要等分拆成 N 個 parts。

核心差異（vs Workflow D 子分片）：

	Workflow D（Sub-Shard）	Workflow F（Auto-Split）
設定方式	手動寫 `.shardrc.json`，指定路由規則	全自動，無需手寫設定
分片策略	依業務欄位值（status、category…）	純等分（item count 或 line count）
分片數	固定寫在設定中	動態計算：`ceil(size / threshold)`
適用情境	有業務語意的拆法（active vs done）	內容均勻、無明顯分類軸
產出 `.shardrc.json`	手寫（`keepSourceIntact: true`）	自動產生（`_autoGenerated: true`）

Step 1 — 執行 validate 確認是否有超標分片

node tools_node/shard-manager.js validate docs/tasks
# WARN: tasks-ui.json is 112.6 KB > 40 KB.
#        Consider: node tools_node/shard-manager.js auto-split docs/tasks

Step 2 — 執行 auto-split

node tools_node/shard-manager.js auto-split docs/tasks --threshold 30

→ 輸出範例：

[shard-manager]   tasks-ui.json  112.6 KB  > 30 KB → auto-split
[shard-manager]     → docs/tasks/tasks-ui/tasks-ui-part-1.json  (25 items, 18.3 KB)
[shard-manager]     → docs/tasks/tasks-ui/tasks-ui-part-2.json  (25 items, 26.5 KB)
[shard-manager]     → docs/tasks/tasks-ui/tasks-ui-part-3.json  (25 items, 26.0 KB)
[shard-manager]     → docs/tasks/tasks-ui/tasks-ui-part-4.json  (25 items, 35.3 KB)
[shard-manager] OK: Auto-split tasks-ui.json → 4 parts in docs/tasks/tasks-ui/

Step 3 — validate 確認 auto-parts 也通過

node tools_node/shard-manager.js validate docs/tasks
# ... ✓ auto-parts sub-dir OK: docs/tasks/tasks-ui/

重新執行（原 shard 內容更新後）：

# 先重建 shard（若 source 有改）或直接 auto-split（若只是分片大小변化）
node tools_node/shard-manager.js auto-split docs/tasks

auto-split 為冪等操作，每次都從當前 shard 檔重新等分。

Workflow G：人工編輯被索引文件的操作規則

觸發時機：需要直接修改 shard 管理範圍內的文件（任務狀態、keep 共識、交叉索引等）。

✅ 可以直接修改

直接編輯分片檔內容（docs/tasks/tasks-ui.json、docs/keep-shards/keep-workflow.md (doc_index_0009) (doc_index_0009)…）
新增 JSON 任務 item（末端 append，preserve id 前綴路由）
更新任務的 status、notes、completed-date 等業務欄位
在 Markdown 分片的既有 section 內增加段落（不跨 ## 邊界）

修改後必須：

node tools_node/shard-manager.js rebuild-index <shardDir>
node tools_node/shard-manager.js validate <shardDir>

❌ 禁止的操作

禁止行為	理由
直接編輯 index stub 的分片索引表	stub 是 auto-generated，下次 `rebuild-index` 會覆蓋
更改任務 `id` 的前綴（`PROG-001` → `UI-001`）	id 前綴決定路由，改了會在下次 `shard` 落入錯誤分片
把 Markdown `##` section 貼進錯誤分片不重跑 `shard`	路由依然按舊設定，下次 shard 才修正
直接編輯 `auto-parts` 子目錄的 `part-*.json`	auto-parts 由 `auto-split` 全量重產，手改會被覆蓋
刪除 `.shardrc.json`	整個分片群失去設定

⚠️ 大幅改動後需重跑的情境

情境	命令
keep.md (doc_index_0011) 新增整個 `##` section	`shard docs/keep-shards`
tasks-ui.json 新增 >10 筆後接近/超過 40 KB	`validate docs/tasks` → 出現 WARN 則 `auto-split docs/tasks`
某分片已超過 40 KB（validate 警告）	`auto-split <shardDir> --threshold 30`

Workflow E：自動偵測新大型文件 → 建立 Shard Group

觸發時機：不確定 docs/ 下是否有新的大型文件需要納管；或定期健康檢查。

Step 1 — 執行 scan

node tools_node/shard-manager.js scan docs

→ 列出所有 > 6 KB 且未在任何 .shardrc.json 中管理的 .md / .json 檔案。

Step 2 — 評估優先順序

優先處理：

單檔 > 30 KB（肯定超過 6000 tokens）
常被 Agent 讀入的規格書 / 任務 JSON
有明確結構（章節 / id 欄位）可以切的文件

跳過：

docs/遊戲規格文件/討論來源/ — 歷史討論，不常讀
一次性參考圖說明文件

Step 3 — 建立 shard group（參考 Workflow B）

# 確認結構後建立目錄 + .shardrc.json，再執行分片
node tools_node/shard-manager.js shard docs/my-new-shards

validate 所有 shard groups 全 pass（包含 auto-parts sub-dirs）
若任何 shard 超過 40 KB → 已執行或確認不需要 auto-split
索引 stub 已更新（rebuild-index 後大小顯示最新）
若有人工編輯 shard 檔 → 確認沒有違反 Workflow G 禁止事項
encoding check：node tools_node/check-encoding-touched.js --files <修改的檔案>
git commit 含 shard 目錄、stub 檔與 .shardrc.json

doc_id	doc_agentskill_0015
name	doc-shard-manager
description	文件分片管理 SKILL — 管理「大型文件 → shard 目錄群」的生命週期。 USE FOR: 任何大型 .md / .json 檔案需要拆分為小分片、更新分片後重建索引、驗證分片完整性，或新增 shard 目錄給新的大型文件。 DO NOT USE FOR: 程式碼編輯、UI layout 調整、任務卡狀態更新（那些直接改對應 JSON）。
argument-hint	Describe which document group needs work: 'keep-shards', 'tasks', 'cross-ref', or a new file path. Specify intent: 'shard (initial split)', 'rebuild-index', 'validate', or 'status'.

doc_id	doc_agentskill_0015
name	doc-shard-manager
description	文件分片管理 SKILL — 管理「大型文件 → shard 目錄群」的生命週期。 USE FOR: 任何大型 .md / .json 檔案需要拆分為小分片、更新分片後重建索引、驗證分片完整性，或新增 shard 目錄給新的大型文件。 DO NOT USE FOR: 程式碼編輯、UI layout 調整、任務卡狀態更新（那些直接改對應 JSON）。
argument-hint	Describe which document group needs work: 'keep-shards', 'tasks', 'cross-ref', or a new file path. Specify intent: 'shard (initial split)', 'rebuild-index', 'validate', or 'status'.

doc-shard-manager

More from this repository

More from this repository

Doc Shard Manager SKILL

概念與用途

本專案現有 Shard Groups

可用命令

Workflow A：維護既有分片（最常見）

Step 1 — 直接編輯對應分片

Step 2 — 重建索引

Step 3 — 驗證

Workflow B：全新大型文件 → 新 Shard Group

Step 1 — 規劃拆分策略

Step 2 — 建立 shard 目錄與 .shardrc.json

Step 3 — 執行分片

Step 4 — 驗證

Step 5 — 更新相關 Guard 文件

Workflow C：原始大檔有重大更新

Pattern 注意事項

Workflow D：子分片（Sub-Shard）— 針對仍然過大的分片細拆

Workflow F：Auto-Split — 動態等分過大的分片

Step 1 — 執行 validate 確認是否有超標分片

Step 2 — 執行 auto-split

Step 3 — validate 確認 auto-parts 也通過

Workflow G：人工編輯被索引文件的操作規則

✅ 可以直接修改

❌ 禁止的操作

⚠️ 大幅改動後需重跑的情境

Workflow E：自動偵測新大型文件 → 建立 Shard Group

Step 1 — 執行 scan

Step 2 — 評估優先順序

Step 3 — 建立 shard group（參考 Workflow B）

Doc Shard Manager SKILL

概念與用途

本專案現有 Shard Groups

可用命令

Workflow A：維護既有分片（最常見）

Step 1 — 直接編輯對應分片

Step 2 — 重建索引

Step 3 — 驗證

Workflow B：全新大型文件 → 新 Shard Group

Step 1 — 規劃拆分策略

Step 2 — 建立 shard 目錄與 .shardrc.json

Step 3 — 執行分片

Step 4 — 驗證

Step 5 — 更新相關 Guard 文件

Workflow C：原始大檔有重大更新

Pattern 注意事項

Workflow D：子分片（Sub-Shard）— 針對仍然過大的分片細拆

Workflow F：Auto-Split — 動態等分過大的分片

Step 1 — 執行 validate 確認是否有超標分片

Step 2 — 執行 auto-split

Step 3 — validate 確認 auto-parts 也通過

Workflow G：人工編輯被索引文件的操作規則

✅ 可以直接修改

❌ 禁止的操作

⚠️ 大幅改動後需重跑的情境

Workflow E：自動偵測新大型文件 → 建立 Shard Group

Step 1 — 執行 scan

Step 2 — 評估優先順序

Step 3 — 建立 shard group（參考 Workflow B）