feat: ingest 寫入端 + deprecate + get_source/refresh + wiki 合併 (issue #1 T3) (#2)

* chore(wiki): 導入 system-dev-template + 合併 wiki 到新位置 - system-dev/ 模板包進版控（VERSION/docs/scripts/wiki 骨架） - 逐檔合併舊 .claude/wiki/ → system-dev/wiki/： - status/mistakes/decisions-summary 真資料覆蓋空範本 - INDEX 新「多角度視圖」結構 + 舊決策/導航併入（過時詞「萬物皆 Block」改 API-as-Wall） - principles/TAXONOMY 為新位置獨有，保留 - 刪舊 .claude/wiki/（git 識別為 rename，內容完整搬移） - 三層機敏防護 hooks + wiki 命令更新 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(sdd): 立 ingest-contract SDD + 搬入 ingest-candidate 契約 (T3.1+T3.8) 對應 issue #1（頂層 mira-dissolve T3）。 - contracts/ingest-candidate.json：ingest→graph 邊界契約（自頂層搬入） - contracts/README.md：標明候選(輸入)≠已存(triplet) - docs/3-specs/ingest-contract/design.md + tasks.md： - ensureTemplate 改 slot-diff 補丁（取代 early-return，免遷移腳本） - 補 KbdbClient.updateRecord（base PATCH /records/:id） - ingest 流程：驗證(422)→idempotency(uri+hash)→先 append 後 deprecate - triplet template 增 source_uri+content_hash slot 承載 idempotency - 跨 repo 協調點（3.6 圖工具併 KBDB MCP）明列需 arcrun 配合總管已認可四個設計決定（issue #1 comment）。鐵律：零建表/零 SQL/零 migration。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(ingest): POST /triplets/ingest 寫入端 + deprecate-then-append (T3.2-3.5) 對應 issue #1 T3 B 段。 - templates: TRIPLET_SLOTS 加 status/superseded_by/source_uri/content_hash； ENTITY_SLOTS 加 gloss；recordToTriplet 映射新欄位（缺省 status=active 相容舊資料） - kbdb-client: ensureTemplate 改 slot-diff 補丁（既有 template 走 PATCH /templates/:id 補缺 slot，取代 early-return → 免遷移腳本）；新增 updateRecord（PATCH /records/:id） - triplet-ingest action（88 行純函式）：Zod strict 鏡射 ingest-candidate 契約 → idempotency（uri+hash 同→no-op）→ 先 append 後 deprecate（無「全無 active」空窗） - POST /triplets/ingest route：strict 驗證失敗 → 422（禁送 graph 領域欄位） - queryTriplets 預設 active-only（traverse/search/neighbors 皆經此）， includeDeprecated opt-out 供 rollback/考古 - 6 測試案全綠（vitest 16 passed）；mock-client 同步 slot-diff + updateRecord gates: zero SQL / zero migration / 無 D1·Vectorize·AI 綁定 / dry-run bundle 乾淨 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(graph): get_source + refresh 端點 + keyword 收斂 (T3.6-3.7) 對應 issue #1 T3 C 段（圖工具 HTTP API 備好，MCP 註冊薄殼待 arcrun）。 - get_source (3.7): graph-source.ts + GET /graph/source/:name — 回節點的 active triplet 來源指標（uri/anchor/block_id/content_hash），去重。連帶加 source_anchor slot，ingest 從 source.anchor 帶入 - refresh (3.6/3.6b): graph-refresh.ts + POST /graph/refresh — 純被動代轉 ingest（KBDB_INGEST_URL），只人發起、無排程/webhook（fan-out 紅線）。未設 URL → 誠實 forwarded:false，不假綠 - 3.6d: POST /search 移除公開 keyword 模式（重複 KBDB MCP），收斂 suggest-only； keywordSearch helper 留作 suggest 內部建構塊 - 3 新測試（get_source uri+anchor / active-only / refresh 未就緒誠實回報） gates: vitest 19 passed / zero SQL / 無新綁定 / dry-run bundle 乾淨待接：MCP 註冊薄殼併 arcrun u6u-mcp-server；refresh 端到端待 ingest(T4) 部署 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: richblack <leo21c@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-26 19:00:54 +08:00
parent 3a1faf19f4
commit 7a29dee357
44 changed files with 2773 additions and 96 deletions
@@ -0,0 +1,104 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "IngestCandidateEnvelope",
+  "description": "ingest 插件 → graph 插件 的唯一邊界契約。一個 envelope = 一個來源檔(canonical MD)一次萃取的產物。graph 收下後負責正規化/clusters/bridge_score/embed,並以『翻 triplet template 實例的 status slot』做取代:同 source.uri 出新 content_hash 時,graph 把舊 active 實例 PATCH 成 deprecated、append 新批 active(可查、可 rollback、可清),ingest 對這些一無所知。注意:這是【輸入候選】,不是【已存三元組】(後者見 triplet.json)。",
+  "type": "object",
+  "required": ["source", "extractor", "triplets"],
+  "additionalProperties": false,
+  "properties": {
+    "source": {
+      "type": "object",
+      "description": "這批候選來自哪個 canonical MD。同時是『指回原文的指標』與『append-only 快照鍵』。",
+      "required": ["uri", "content_hash"],
+      "additionalProperties": false,
+      "properties": {
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "description": "來源的穩定識別 = 快照鍵 + get_source 指標。格式: 'github:<owner>/<repo>@<path>' 例如 'github:uncle6me-web/LLM-Wiki-for-n8n@.claude/wiki/graph-rag.md'。同一 uri 的後續 envelope 會【取代】(latest-wins)前一批,而非疊加。"
+        },
+        "content_hash": {
+          "type": "string",
+          "minLength": 1,
+          "description": "來源檔內容的 hash(快照鍵)。graph 比對: 與該 uri 現存快照同 hash → no-op 跳過;不同 → 寫新快照。"
+        },
+        "anchor": {
+          "type": "string",
+          "description": "檔內定位(heading slug / block id),供 get_source 精準回跳。選填。"
+        },
+        "commit": {
+          "type": "string",
+          "description": "git commit sha(可追溯)。選填。"
+        },
+        "block_id": {
+          "type": "string",
+          "description": "向後相容: Logseq Block ID(= 既有 triplet.json 的 source_block_id)。非 git 來源時用。選填。"
+        }
+      }
+    },
+    "extractor": {
+      "type": "object",
+      "description": "萃取出處。供『升級率』觀測與『要不要重萃』判斷;不影響圖結構。",
+      "required": ["model", "tier"],
+      "additionalProperties": false,
+      "properties": {
+        "model": {
+          "type": "string",
+          "minLength": 1,
+          "description": "產生這批的模型,例如 'workers-ai/@cf/...' 或 'claude-sonnet-4-6'。"
+        },
+        "tier": {
+          "type": "string",
+          "enum": ["shallow", "deep"],
+          "description": "shallow = Workers AI 淺萃;deep = Claude API 深萃(淺萃 JSON-fail/過稀時升級)。"
+        },
+        "extracted_at": {
+          "type": "integer",
+          "description": "萃取的 unix 時間(秒)。快照排序用。選填(graph 收件時可補)。"
+        }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "description": "節點層附帶資訊(選填)。entity_type 與 gloss 是【節點】屬性,不是【邊】屬性 → 放這裡,不放 triplets。graph 用 gloss 去 embed(每節點一句,不是裸詞)、用 entity_type 去 typing。",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "節點名(須對應某 triplet 的 subject 或 object 原字面)。"
+          },
+          "gloss": {
+            "type": "string",
+            "description": "一句話描述,供 embedding。例如 'Graph RAG — 用關係遍歷檢索、保住異見的 RAG 變體'。選填(建議 deep tier 產出)。"
+          },
+          "entity_type": {
+            "type": "string",
+            "enum": ["person", "event", "product", "market", "org"],
+            "description": "節點類型提示。graph 最終決定;ingest 只提示。選填。"
+          }
+        }
+      }
+    },
+    "triplets": {
+      "type": "array",
+      "minItems": 1,
+      "description": "邊(關係)。ingest 只產原始 (s,p,o) + confidence。",
+      "items": {
+        "type": "object",
+        "required": ["subject", "predicate", "object"],
+        "additionalProperties": false,
+        "properties": {
+          "subject":   { "type": "string", "minLength": 1, "description": "主詞(實體名,須與 nodes[].name 對得上若有提供)" },
+          "predicate": { "type": "string", "minLength": 1, "description": "謂詞(關係)" },
+          "object":    { "type": "string", "minLength": 1, "description": "受詞(目標實體或值)" },
+          "confidence":{ "type": "number", "minimum": 0, "maximum": 1, "default": 1.0, "description": "萃取可信度。淺萃可附自評;graph 不據此過濾,只記錄。" }
+        }
+      }
+    }
+  },
+  "$comment": "禁止欄位(graph 領域,ingest 絕不可送): id / clusters / bridge_score / created_at / updated_at / 以及 triplet 上的 subject_entity_type|object_entity_type(類型只走 nodes[])。送了即違反 ingest=純餵食器的邊界,graph 應拒收或忽略。"
+}