Leo/Arcrun
1
0
Fork 0
Code Issues 49 Pull Requests 5 Actions Packages Projects Releases Wiki Activity

merge: 機械 wiki ingest workflow（Arcrun#8）——code 節點 card→envelope，Phase B live 驗過

Browse Source
This commit is contained in:
Leo
2026-07-06 05:48:10 +00:00
parent 08a79229a5 b87c18df60
commit 4439880bbd
6 changed files with 1221 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
registry/examples/km-wiki-ingest/description.md
+74
View File
@@ -0,0 +1,74 @@
# km-wiki-ingest — 機械式 wiki 卡片 → KBDB ingest（Arcrun#8 / 頂層 SDD T2–T4）
> Phase A 產物：機械 ingest 邏輯 + 乾跑證據 + workflow 設計。**不部署、不寫 live KBDB。**
## 解決什麼問題
把各 repo 的 `system-dev/wiki/cards/**/*.md`（人工精耕卡）**機械地**（無 LLM）灌進 leo21c KBDB：
- **卡片 → base entry**（`metadata.embed=true`，供語意搜尋）。
- **`## 實體` → graph node**；**`## 關聯` 的 typed-edge（`A >> 關係 >> B`）與 `[[wikilink]]` → graph triplet**。
取代舊 `kbdb-ingest-plugin/scripts/ingest-cli.mjs` 的 `raw → Haiku → 三元組` 路：新路純解析卡片內既有結構，**決定性、零 token、零幻覺**。
## 形式選擇與理由（給總管）
**形式 = Arcrun workflow（YAML 編排）＋ 通用 `code` 零件（sandbox inline JS，Arcrun#10）承載卡片→envelope 解析 ＋ 現成零件（`cron` / `http_request` / `foreach_control` / `kbdb_upsert_block`）。** 不再鑄 domain 零件 `km_wiki_card_parse`（Arcrun#10 裁定：一次性解析走通用逃生口）。
理由：
1. **編排本來就是 arcrun 的主場**：cron 限速 drain、Gitea webhook 只吃 delta、foreach 小批、冪等 upsert——這些跟現成零件 1:1 對得上，且 leo 要「Arcrun workflow 慢慢做」、arcrun 哲學禁一次性腳本。
2. **arcrun 唯一缺的是「卡片 → envelope」的解析**。那是一段**決定性純轉換**（無 LLM、無網路、無檔案）——正好是 `code` 零件 sandbox 的理想形狀（`stdin_stdout_json` + `no_network_syscall` + `no_filesystem_syscall`）。用通用 `code` 節點內聯這段 JS（而非鑄 domain 零件、也非在 YAML 裡塞 `string_ops` 正則）：workflow 可讀、解析可單元測試、且 registry 不因一次性邏輯增生 domain 零件。
3. **小批是結構性的，不是靠祈禱**：一卡一 tick，每卡在 graph worker 的 fan-out ≈ `7+4N+M` subrequest（notes 卡 N≈4/M≈5 → est 28~33，穩壓 CF 50 頂下）；`code` 節點內聯解析會**預先把超大卡以 `source_uri` anchor 分段**，任何單一 graph 呼叫都不破頂。
**Phase A 交付**：純解析＋打包核心（`lib/card-to-envelope.mjs`，現在就能跑，＝ `code` 節點內聯 JS 的權威來源）＋乾跑驗證器（`lib/dry-run.mjs`，印出「將寫入什麼」）＋本 workflow.yaml（parse_card = `code` 節點）。解析零件＝通用 `code`（Arcrun#10 分支，已就緒待部署）；本 example 不再自帶 domain 零件契約。部署被閘控，故 live 接線是「設計而非執行」。
## 診斷小結：fan-out 精確來源 + 小批為何解得掉
讀 `kbdb-graph-plugin` 現役寫入路徑（`triplet-ingest.ts` / `triplet-crud.ts` / `templates.ts` / `kbdb-client.ts`）逐行拆帳：
```
POST /triplets/ingest（graph worker 單次 invocation）對 base 的 subrequest：
ensurePluginTemplates(3) # 頂層一次
+ listRecordsByTemplate(1) # 抓同 source 現存 active（冪等分組）
+ Σ_triplet [ createTriplet → ensurePluginTemplates(3) + createRecord(1) ] # ★ 每條邊重跑 ensure！
+ persistNodes [ ensurePluginTemplates(3) + Σ_node createRecord(1) ]
+ Σ_deprecated updateRecord(1)
= 7 + 4*N_triplets + M_nodes + D_deprecated
```
- **精確炸點還原**：07_01 單一 envelope 吞 `N=11, M=10, D=0` → `7+44+10 = 61 > 50` → 破頂半殘。**放大器＝`createTriplet` 內每條邊都重呼 `ensurePluginTemplates`（3 個 GET）**，佔了 33/61。
- **小批為何解得掉**：把「整檔一 envelope」改成「一卡一 envelope、必要時再 anchor 分段」，把 `N` 壓到讓 `7+4N+M ≤ 40`。notes 三卡實測 est 上限 = 33，全綠。超大卡（自測 20 邊/22 節點＝114）→ 自動分 4 段，每段 ≤ 38。
- **附帶建議（非本 Phase 必改）**：graph 端把 `createTriplet`/`persistNodes` 內重複的 `ensurePluginTemplates` 提到 ingest 入口只跑一次，可把每 envelope 省下 `3*(N+1)` 個 subrequest（單卡 est 33→約 18），批量還能更大。此為 graph-plugin 的可選優化，記此存查。
## 冪等設計
| 對象 | 冪等鍵 | 行為 |
|---|---|---|
| **entry** | `page_name`（穩定：`wikicard:<repo>/<canonical>`）+ `metadata.content_hash` | 找到同 page_name：hash 相同 → skip；不同 → PATCH content（觸發重嵌）。沒有 → POST 新建。 |
| **triplet envelope** | `source.uri` + `source.content_hash` | graph 現役 per-source 冪等：同 hash 整包 no-op（`triplet-ingest.ts:65`）。 |
| **分段** | 各段 `source.uri = <基uri>#segNN` | 各段獨立 uri → 各自獨立冪等，**繞開 per-source content_hash 整包 skip**（否則同 uri 第 2 段起會被判定「已落地」而整包跳過）。節點只放進「首次引用它的段」，跨段不重送（避免 graph 重建 entity）。 |
## 觸發（兩階段，對齊 SDD R3）
- **Phase 0（一次性 backfill）**：`cron */2` 每 tick drain 一張卡（限速慢推），反覆跑到全庫清空。冪等 → 可續傳、重跑零寫入。
- **穩態（日常增量）**：**Gitea push webhook → arcrun workflow**，只吃 `commits[].{added,modified}` 中的 `system-dev/wiki/cards/**/*.md`。⚠️ Gitea → Cloudflare(arcrun)，**非 GitHub Actions**，不觸 GitHub flag 紅線（D4/D20）。量小、不撞頂、不限速。
## 乾跑證據（Phase A，不寫 live）
```
node lib/dry-run.mjs --repo-path <notes clone> --repo Leo/notes --self-test
```
對 `Leo/notes` 的 3 張卡實測：3 entries（embed=true）+ 3 envelopes、15 triplets、16 nodes；
**單次 graph 呼叫 subrequest 上限 = 33（< 50），無任一 envelope 破頂**。
self-test 合成超大卡（不分段 est=114 會炸）→ 自動分 4 段、每段 ≤ 38，全綠。
## 待 live 部署 + 寫入（總管過 leo 閘用）
1. **部署通用 `code` 零件**（Arcrun#10 分支 `feat/issue-10-code-component`，已就緒）：`cd registry/components/code && npm install && npx wrangler deploy`（→ `code.arcrun.dev`）＋ `register-component.sh code`。本 workflow 的 parse_card 以 `component: code` 引用它，解析 JS 已內聯在 workflow.yaml（＝ `lib/card-to-envelope.mjs` 邏輯）。不再部署 domain 零件 `km_wiki_card_parse`。
2. **部署 workflow**：`km_wiki_ingest_drain`（cron drain）；`wrangler` 直推 leo21c（**禁 `acr update`**——codeload 綁 GitHub 假綠，Arcrun#4）。
3. **注入環境變數**（不放 repo）：`repo=Leo/notes ref=main gitea_token kbdb_url=https://arcrun-kbdb.leo21c.workers.dev kbdb_api_key graph_url graph_api_key=leo`。`CLOUDFLARE_ACCOUNT_ID=leo21c`（別讓官方 58309b 污染）。
4. **entry 寫入路徑確認**：若 `kbdb_upsert_block` 尚不透傳 `metadata_json`（需 `embed:true`/`content_hash`），entry 改用 `http_request` 直打 base `POST/PATCH /entries` 帶 `body_json.metadata_json`。
5. **預期寫入量（Leo/notes 現況 3 卡）**：3 entries + 15 triplets + 16 node records（去重後更少）；分 3 次 graph 呼叫（每次 ≤ 33 subrequest）+ 3 次 entry upsert。全庫鋪開時照 cron 一卡一 tick 慢推。
6. **驗收**：ingest 後 `GET /embed/backfill/status` 應見 pending 上升→drain 後歸零、embedded 增加；三模式（關鍵字/語意/圖）curl 驗。
registry/examples/km-wiki-ingest/dry-run-evidence.json
+176
View File
@@ -0,0 +1,176 @@
{
"repo": "Leo/notes",
"commit": "4b9a53c1c99d596c23b1b449fd79728610f6995b",
"budget": 40,
"ceiling": 50,
"cards": [
{
"relPath": "system-dev/wiki/cards/notes/Gitea當後端編輯器全CF化網站構想.md",
"canonical": "Gitea當後端編輯器全CF化網站構想",
"entry": {
"page_name": "wikicard:Leo/notes/Gitea當後端編輯器全CF化網站構想",
"entry_type": "wiki_card",
"metadata.embed": true,
"content_hash": "64b402952fe0…",
"content_bytes": 2324,
"tags": [
"系統設計",
"工具教學"
]
},
"envelopeCount": 1,
"envelopes": [
{
"source.uri": "gitea:Leo/notes@system-dev/wiki/cards/notes/Gitea當後端編輯器全CF化網站構想.md",
"source.anchor": null,
"nodes": 6,
"triplets": 5,
"est_subrequests": 33,
"under_ceiling": true,
"sample_triplets": [
"Gitea >> 類比於 >> WordPress (1)",
"Gitea >> 充當後端供稿給 >> Cloudflare Pages (1)",
"Quartz >> 目前負責轉譯給 >> Cloudflare Pages (1)",
"Cloudflare Artifacts >> 若提供 git 倉庫則可取代 >> Gitea (1)"
],
"sample_nodes": [
"Gitea — 可自架的 git 平台，編輯體驗近似 WordPress 後…",
"WordPress — 常見的內容管理後端，作為 Gitea 編輯體驗的類比對象。…",
"Cloudflare Pages — Cloudflare 的靜態站前端託管。…",
"Quartz — 目前把筆記轉成網站前端的工具。…"
]
}
]
},
{
"relPath": "system-dev/wiki/cards/notes/Prompt能力即拆解自己邏輯的能力.md",
"canonical": "Prompt能力即拆解自己邏輯的能力",
"entry": {
"page_name": "wikicard:Leo/notes/Prompt能力即拆解自己邏輯的能力",
"entry_type": "wiki_card",
"metadata.embed": true,
"content_hash": "63296a663227…",
"content_bytes": 2109,
"tags": [
"AI協作",
"工具教學",
"觀點主張"
]
},
"envelopeCount": 1,
"envelopes": [
{
"source.uri": "gitea:Leo/notes@system-dev/wiki/cards/notes/Prompt能力即拆解自己邏輯的能力.md",
"source.anchor": null,
"nodes": 5,
"triplets": 5,
"est_subrequests": 32,
"under_ceiling": true,
"sample_triplets": [
"Prompt 能力 >> 本質上等於 >> 邏輯拆解能力 (1)",
"邏輯拆解能力 >> 產出 >> pseudo code (1)",
"pseudo code >> 足以教會 >> AI (1)",
"Prompt能力即拆解自己邏輯的能力 >> 呼應 >> 程式化邏輯可圖解任何主題不限AI (1)"
],
"sample_nodes": [
"Prompt 能力 — 把腦中意圖轉成能指揮 AI 的指令的能力。…",
"邏輯拆解能力 — 把腦中隱性流程外顯成可陳述步驟的能力。…",
"pseudo code — 用類程式的步驟描述邏輯、尚未綁定特定語法的表達。…",
"AI — 需被人以指令／範例指揮才產出的生成模型。…"
]
}
]
},
{
"relPath": "system-dev/wiki/cards/notes/程式化邏輯可圖解任何主題不限AI.md",
"canonical": "程式化邏輯可圖解任何主題不限AI",
"entry": {
"page_name": "wikicard:Leo/notes/程式化邏輯可圖解任何主題不限AI",
"entry_type": "wiki_card",
"metadata.embed": true,
"content_hash": "a9dbf5fc0f9a…",
"content_bytes": 2577,
"tags": [
"工具教學",
"觀點主張",
"系統設計"
]
},
"envelopeCount": 1,
"envelopes": [
{
"source.uri": "gitea:Leo/notes@system-dev/wiki/cards/notes/程式化邏輯可圖解任何主題不限AI.md",
"source.anchor": null,
"nodes": 5,
"triplets": 5,
"est_subrequests": 32,
"under_ceiling": true,
"sample_triplets": [
"程式化邏輯 >> 可圖解 >> 亞洲金融風暴 (1)",
"流程圖解 >> 奠基於 >> 程式化邏輯 (1)",
"系統動力學 >> 類同於 >> 流程圖解 (1)",
"程式化邏輯可圖解任何主題不限AI >> 呼應 >> Prompt能力即拆解自己邏輯的能力 (1)"
],
"sample_nodes": [
"程式化邏輯 — 以程式的因果鏈結構來表述任一領域的邏輯。…",
"亞洲金融風暴 — 講者小 Lin 用長邏輯鏈敘述的金融事件案例。…",
"流程圖解 — 用 n8n 這類流程工具把邏輯視覺化講解的方法。…",
"系統動力學 — 以存量流量與回饋環圖解因果的建模工具。…"
]
}
]
}
],
"totals": {
"cards": 3,
"entries_to_upsert": 3,
"triplet_envelopes": 3,
"total_triplets": 15,
"total_nodes": 16,
"max_est_subrequests_single_call": 33,
"ceiling": 50,
"budget": 40,
"any_envelope_over_ceiling": 0
},
"self_test": {
"note": "合成 20 邊 / 22 節點 的超大卡",
"if_single_envelope_est_subrequests": 114,
"would_crash_single": true,
"segmented_into": 4,
"per_segment": [
{
"uri": "gitea:Leo/notes@system-dev/wiki/cards/notes/合成超大卡.md#seg01",
"anchor": "seg01",
"triplets": 6,
"nodes": 7,
"est_subrequests": 38,
"under_ceiling": true
},
{
"uri": "gitea:Leo/notes@system-dev/wiki/cards/notes/合成超大卡.md#seg02",
"anchor": "seg02",
"triplets": 6,
"nodes": 6,
"est_subrequests": 37,
"under_ceiling": true
},
{
"uri": "gitea:Leo/notes@system-dev/wiki/cards/notes/合成超大卡.md#seg03",
"anchor": "seg03",
"triplets": 6,
"nodes": 6,
"est_subrequests": 37,
"under_ceiling": true
},
{
"uri": "gitea:Leo/notes@system-dev/wiki/cards/notes/合成超大卡.md#seg04",
"anchor": "seg04",
"triplets": 3,
"nodes": 3,
"est_subrequests": 22,
"under_ceiling": true
}
],
"all_segments_under_ceiling": true
}
}
registry/examples/km-wiki-ingest/lib/card-to-envelope.mjs
+331
View File
@@ -0,0 +1,331 @@
// km-wiki-ingest — 機械式卡片→(entry + triplet envelope) 轉換核心（無 LLM、純函式）
// ---------------------------------------------------------------------------
// 取代舊 `kbdb-ingest-plugin/scripts/ingest-cli.mjs` 的 raw→Haiku 路：
// 舊路 = 讀裸筆記 → 呼叫 Haiku 萃 (s,p,o) → envelope（有 LLM、非決定性、耗 token）。
// 新路 = 讀「已精耕卡片」（`system-dev/wiki/cards/**/*.md`）→ 直接解析卡片內既有的
// `## 實體`（節點）、`## 關聯` 的 typed-edge（`A >> 關係 >> B`）與 `[[wikilink]]`
// → entry + triplet envelope。純機械、決定性、零 token。
//
// 這支＝通用 `code` 零件（Arcrun#10，sandbox inline JS）承載的解析邏輯本體。
// workflow.yaml 的 parse_card 節點把本檔的 planCard 邏輯內聯進 code 零件的 config
// （去 import/export、raw NUL 分隔符改 u0000 escape、改用 code 沙箱注入的 sha256）；
// 不再鑄 domain 零件 km_wiki_card_parse（Arcrun#10 裁定：一次性解析走通用逃生口）。
// 本檔續留作「該內聯 JS 的權威來源 + 可單元測試的參考實作」（純函式、stdin→stdout JSON、無 fs/網路）。
//
// 對齊契約：kbdb-ingest-plugin/contracts/ingest-candidate.json（envelope 形狀 / 禁止欄位）。
// 對齊頂層 SDD：卡片→entry（metadata.embed=true，走 base API）、wikilink→triplet（走 graph）。
//
// 鐵律：不碰儲存、不算向量、不建表。這支只「產出將寫入什麼」，實際 HTTP 由 workflow 打。
import { createHash } from 'node:crypto';
// --- CF subrequest 預算（防「Too many subrequests by single Worker invocation」，07_01 根因）---
//
// graph worker 處理一次 POST /triplets/ingest 時，對 base 的每次 fetch = 1 subrequest。
// 精確拆帳（讀 kbdb-graph-plugin/src/actions/triplet-ingest.ts + triplet-crud.ts + templates.ts）：
// ingestEnvelope = ensurePluginTemplates(3) + listRecordsByTemplate(1)
// + Σ triplet [ createTriplet → ensurePluginTemplates(3) + createRecord(1) = 4 ]
// + persistNodes [ ensurePluginTemplates(3) + Σ node createRecord(1) ]
// + Σ deprecated updateRecord(1)
// ⟹ subreq(envelope) = 7 + 4*N_triplets + M_nodes + D_deprecated
//
// 07_01 實測炸點：N=11, M=10, D=0 → 7+44+10 = 61 > 50（CF 免費/bundled 上限）→ 炸半殘。
//
// 對策 = 「一卡一 tick、每 envelope 壓在預算下、超大檔以 source_uri anchor 分段」。
export const SUBREQ_CEILING = 50; // CF 單次 Worker invocation subrequest 硬上限（bundled）
export const SUBREQ_BUDGET = 40; // 我們的目標上限（留 10 給 D_deprecated 等變動）
/** 精確估算「一個 envelope 打進 graph /triplets/ingest」會在 graph worker 內產生幾個 subrequest。 */
export function estimateEnvelopeSubrequests(nTriplets, mNodes, dDeprecated = 0) {
return 7 + 4 * nTriplets + mNodes + dDeprecated;
}
// --- sha256（content_hash 冪等鍵）---
export function sha256(text) {
return createHash('sha256').update(text).digest('hex');
}
// --- frontmatter 解析（極簡 YAML：只吃我們卡片用到的 tags / gloss / pipeline_candidate）---
function parseFrontmatter(md) {
const m = md.match(/^---\n([\s\S]*?)\n---\n?/);
if (!m) return { data: {}, body: md };
const body = md.slice(m[0].length);
const data = {};
for (const line of m[1].split('\n')) {
const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
if (!kv) continue;
const key = kv[1];
let val = kv[2].trim();
if (val.startsWith('[') && val.endsWith(']')) {
// inline list: [a, b, c]
data[key] = val.slice(1, -1).split(',').map((s) => s.trim()).filter(Boolean);
} else if (val === 'true' || val === 'false') {
data[key] = val === 'true';
} else {
data[key] = val;
}
}
return { data, body };
}
// --- 取某個 `## 標題` / `### 標題` 區塊的內文（到下一個同級或更高級標題為止）---
function sectionBody(md, heading) {
// heading 例：'## 實體'、'### 內文知識關係'
const level = heading.match(/^#+/)[0].length;
const lines = md.split('\n');
const out = [];
let inSec = false;
for (const line of lines) {
const h = line.match(/^(#+)\s+(.*)$/);
if (h) {
const thisLevel = h[1].length;
if (inSec) {
// 遇到同級或更高級標題 → 區塊結束
if (thisLevel <= level) break;
}
// 標題文字「開頭相符」即算命中（容忍標題後帶括號補述）
if (!inSec && thisLevel === level && line.replace(/^#+\s+/, '').startsWith(heading.replace(/^#+\s+/, ''))) {
inSec = true;
continue;
}
}
if (inSec) out.push(line);
}
return out.join('\n');
}
// --- 實體行解析：`- **正規名**（別名1／別名2）— 描述`（別名、描述皆選填）---
function parseEntities(md) {
const sec = sectionBody(md, '## 實體');
const entities = [];
for (const raw of sec.split('\n')) {
const line = raw.trim();
if (!line.startsWith('- ')) continue;
if (line.startsWith('- >') || line.startsWith('> ')) continue; // 跳過引言說明行
const m = line.match(/^- \*\*(.+?)\*\*(?:（(.+?)）)?\s*(?:[—–\-]\s*(.*))?$/);
if (!m) continue;
const name = m[1].trim();
if (!name) continue;
const aliases = m[2]
? m[2].split(/[／/、,]/).map((s) => s.trim()).filter((s) => s && s !== name)
: [];
const gloss = (m[3] || '').trim();
entities.push({ name, aliases, gloss });
}
return entities;
}
// --- typed-edge 行解析：`A >> 謂詞 >> B`（端點可為裸實體名或 [[wikilink]]）---
function parseTypedEdges(sectionText) {
const edges = [];
for (const raw of (sectionText || '').split('\n')) {
const line = raw.trim();
if (!line.startsWith('- ')) continue;
const body = line.slice(2).trim();
if (body.startsWith('（') || body.startsWith('(')) continue; // 「（暫無…）」占位行
const parts = body.split('>>');
if (parts.length !== 3) continue;
const subject = stripWikilink(parts[0].trim());
const predicate = parts[1].trim();
const object = stripWikilink(parts[2].trim());
if (!subject || !predicate || !object) continue;
edges.push({ subject, predicate, object });
}
return edges;
}
// [[notes/00-INDEX]] → notes/00-INDEX ；純字串則原樣回。
function stripWikilink(s) {
const m = s.match(/^\[\[(.+?)\]\]$/);
return m ? m[1].trim() : s;
}
// --- 抽所有 inline [[wikilink]]（含 header 的 ← [[notes/00-INDEX]] 與內文）---
function extractInlineWikilinks(md) {
const out = [];
const re = /\[\[(.+?)\]\]/g;
let m;
while ((m = re.exec(md)) !== null) out.push(m[1].trim());
return out;
}
// --- 卡片 canonical id：以檔名（去副檔名）為準，對齊 `## 卡片關係` 用的 [[基名]] 慣例 ---
export function cardCanonical(relPath) {
const base = relPath.split('/').pop().replace(/\.md$/, '');
return base;
}
/**
* 解析一張卡片 → { entry, nodes, triplets, meta }（尚未分段的原始產物）。
* relPath：卡片相對 repo 根路徑（如 system-dev/wiki/cards/notes/Xxx.md）。
* repo：如 'Leo/notes'。
*/
export function parseCard(md, relPath, repo = 'Leo/notes') {
const { data: fm } = parseFrontmatter(md);
const canonical = cardCanonical(relPath);
const titleMatch = md.match(/^#\s+(.+)$/m);
const title = titleMatch ? titleMatch[1].trim() : canonical;
// 1) 節點：## 實體 的正規名 + 別名 + gloss。
const entities = parseEntities(md);
// 2) 邊：內文知識關係（實體↔實體）+ 卡片關係（卡↔卡）+ inline wikilink（卡→卡 導覽/引用）。
const intraEdges = parseTypedEdges(sectionBody(md, '### 內文知識關係'))
.map((e) => ({ ...e, confidence: 1.0 }));
const cardEdges = parseTypedEdges(sectionBody(md, '### 卡片關係'))
.map((e) => ({ ...e, confidence: 1.0 }));
// inline wikilink（← [[notes/00-INDEX]] 等）→ 卡→卡「連結至」邊，去重、排除自環與已被 typed 邊覆蓋者。
const typedPairs = new Set(
[...cardEdges].map((e) => `${e.subject}${e.object}`),
);
const seenRef = new Set();
const refEdges = [];
for (const target of extractInlineWikilinks(md)) {
const t = stripWikilink(target);
if (t === canonical || t === title) continue; // 自環
if (typedPairs.has(`${canonical}${t}`)) continue; // 已有明確謂詞邊
const key = `${canonical}${t}`;
if (seenRef.has(key)) continue;
seenRef.add(key);
refEdges.push({ subject: canonical, predicate: '連結至', object: t, confidence: 0.5 });
}
const triplets = [...intraEdges, ...cardEdges, ...refEdges];
// 3) 節點清單：卡片本身（canonical，帶 frontmatter gloss）+ 內文實體。
// 卡對卡邊指到的「別張卡」不在此補 node —— 那張卡自己被 ingest 時會補自己的 node。
const nodes = [];
const seenNode = new Set();
const pushNode = (n) => {
const k = n.name.toLowerCase();
if (!n.name || seenNode.has(k)) return;
seenNode.add(k);
nodes.push(n);
};
pushNode({ name: canonical, gloss: fm.gloss || '', aliases: title && title !== canonical ? [title] : [] });
for (const e of entities) pushNode({ name: e.name, gloss: e.gloss, aliases: e.aliases });
return {
entry: {
// base POST /entries（或 kbdb_upsert_block）用。metadata.embed=true → 語意可搜。
page_name: `wikicard:${repo}/${canonical}`, // idempotency key（穩定）
entry_type: 'wiki_card',
content: md, // 卡片全文逐字（embed 對象）
tags: Array.isArray(fm.tags) ? fm.tags : [],
metadata: {
embed: true, // ★ base embed 模組讀此旗標
source: `gitea:${repo}@${relPath}`,
content_hash: sha256(md),
kind: 'wiki_card',
repo,
canonical,
pipeline_candidate: fm.pipeline_candidate === true,
},
},
nodes,
triplets,
meta: { canonical, title, relPath, repo, contentHash: sha256(md) },
};
}
/**
* 把一張卡片的 (nodes, triplets) 打包成「一個或多個」ingest envelope，
* 使每個 envelope 打進 graph 後的 subrequest 都 ≤ SUBREQ_BUDGET。
*
* 分段規則（對應頂層 SDD R4 / issue #8 第4點）：
* - 單 envelope 夠塞（7+4N+M ≤ budget）→ 不分段，uri = 基 uri（無 anchor）。
* - 需分段 → 每段 uri = `<基uri>#seg{NN}`、anchor = `seg{NN}`。
* 每段是「獨立 source_uri」→ 各自獨立冪等，繞開 graph 的 per-source content_hash 整包 skip
* （否則同 uri 第 2 段起會被 line 65 的 content_hash 命中而整包跳過）。
* - 節點只放進「第一個引用到它的段」，跨段不重送（避免 graph persistNodes 重建 entity record）。
*/
export function planEnvelopes(parsed, opts = {}) {
const budget = opts.budget ?? SUBREQ_BUDGET;
const repo = parsed.meta.repo;
const relPath = parsed.meta.relPath;
const baseUri = `gitea:${repo}@${relPath}`;
const contentHash = parsed.meta.contentHash;
const commit = opts.commit;
const extractor = {
model: opts.extractorModel ?? 'mechanical/km-wiki-card-parse@1',
tier: 'deep', // 人工精耕卡＝deep（決定性、非淺萃）
extracted_at: Math.floor(Date.now() / 1000),
};
const nodeByName = new Map(parsed.nodes.map((n) => [n.name, n]));
// 貪婪打包：逐條 triplet 累進，段成本 = 7 + 4*(段內邊數) + (段內首見節點數)。
const segments = [];
let cur = null;
const startSeg = () => {
cur = { triplets: [], nodeNames: new Set() };
segments.push(cur);
};
const segCost = (seg, extraEdges = 0, extraNodes = 0) =>
estimateEnvelopeSubrequests(seg.triplets.length + extraEdges, seg.nodeNames.size + extraNodes);
startSeg();
for (const t of parsed.triplets) {
// 這條邊會新引入哪些節點（subject/object 命中 nodeByName 且本段尚未收）
const cand = [t.subject, t.object].filter(
(nm) => nodeByName.has(nm) && !cur.nodeNames.has(nm) && !anySegHas(segments, cur, nm),
);
// 放得下？（含新增這條邊 + 新引入節點）
if (cur.triplets.length > 0 && segCost(cur, 1, cand.length) > budget) {
startSeg();
}
cur.triplets.push(t);
for (const nm of [t.subject, t.object]) {
if (nodeByName.has(nm) && !anySegHas(segments, null, nm)) cur.nodeNames.add(nm);
}
}
const multi = segments.length > 1;
const envelopes = segments.map((seg, i) => {
const anchor = multi ? `seg${String(i + 1).padStart(2, '0')}` : undefined;
const uri = multi ? `${baseUri}#${anchor}` : baseUri;
const nodes = [...seg.nodeNames].map((nm) => {
const n = nodeByName.get(nm);
const out = { name: n.name };
if (n.gloss) out.gloss = n.gloss;
if (n.aliases && n.aliases.length) out.aliases = n.aliases;
out.embed = true;
return out;
});
const source = { uri, content_hash: contentHash };
if (anchor) source.anchor = anchor;
if (commit) source.commit = commit;
return {
source,
extractor,
nodes,
triplets: seg.triplets.map((t) => ({
subject: t.subject,
predicate: t.predicate,
object: t.object,
confidence: t.confidence ?? 1.0,
})),
_estSubrequests: estimateEnvelopeSubrequests(seg.triplets.length, seg.nodeNames.size),
};
});
// triplets≥1 是契約硬性；無邊的卡不產 envelope（仍會建 entry）。
return envelopes.filter((e) => e.triplets.length >= 1);
}
function anySegHas(segments, exclude, name) {
for (const s of segments) {
if (s === exclude) continue;
if (s.nodeNames.has(name)) return true;
}
return false;
}
/** 一張卡片 → 完整 ingest 計畫（entry + envelopes）。planCard = parseCard + planEnvelopes。 */
export function planCard(md, relPath, repo = 'Leo/notes', opts = {}) {
const parsed = parseCard(md, relPath, repo);
const envelopes = planEnvelopes(parsed, opts);
return { entry: parsed.entry, envelopes, meta: parsed.meta, nodeCount: parsed.nodes.length, tripletCount: parsed.triplets.length };
}
registry/examples/km-wiki-ingest/lib/dry-run.mjs
+181
View File
@@ -0,0 +1,181 @@
#!/usr/bin/env node
// km-wiki-ingest 乾跑（dry-run）驗證器 — 不寫 live、不部署。
// -------------------------------------------------------------
// 註：解析在 live 由 workflow.yaml 的 parse_card = 通用 `code` 零件（sandbox inline JS）承載；
// 本驗證器直接 import card-to-envelope.mjs（＝該 code 節點內聯 JS 的權威來源）跑同一份邏輯，
// 故 dry-run 的 envelope 結果與 code 節點在 live 的輸出等價（Arcrun#10 已單測證明逐欄全等）。
// 對某 repo 的 system-dev/wiki/cards/**/*.md 跑機械解析 + envelope 打包，
// 輸出「將寫入什麼」：① entry 清單（page_name / entry_type / metadata.embed / content_hash）
// ② triplet envelope 清單（每段的 nodes / triplets / source.uri+anchor）
// ③ 每個 graph /triplets/ingest 呼叫的 subrequest 估算（證明壓在 CF 上限下）
// ④ 冪等鍵設計（entry=page_name+content_hash；triplet=source.uri+content_hash）。
//
// 用法：node dry-run.mjs --repo-path <clone路徑> [--repo Leo/notes] [--budget 40] [--json] [--full]
// --self-test 額外跑「合成超大卡」證明分段生效。
import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
import path from 'node:path';
import { execFileSync } from 'node:child_process';
import { planCard, estimateEnvelopeSubrequests, SUBREQ_CEILING, SUBREQ_BUDGET } from './card-to-envelope.mjs';
function parseArgs(argv) {
const out = { repo: 'Leo/notes', budget: SUBREQ_BUDGET };
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
if (a === '--repo-path') out.repoPath = argv[++i];
else if (a === '--repo') out.repo = argv[++i];
else if (a === '--budget') out.budget = Number(argv[++i]);
else if (a === '--json') out.json = true;
else if (a === '--full') out.full = true;
else if (a === '--self-test') out.selfTest = true;
}
return out;
}
function walkCards(dir) {
const out = [];
if (!existsSync(dir)) return out;
for (const e of readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, e.name);
if (e.isDirectory()) out.push(...walkCards(p));
else if (e.name.endsWith('.md') && e.name !== '.gitkeep' && !e.name.startsWith('00-INDEX')) out.push(p);
}
return out;
}
function gitCommit(repoPath) {
try {
return execFileSync('git', ['-C', repoPath, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
} catch { return undefined; }
}
const args = parseArgs(process.argv.slice(2));
if (!args.repoPath) {
console.error('用法: node dry-run.mjs --repo-path <clone路徑> [--repo Leo/notes] [--budget 40] [--json] [--full] [--self-test]');
process.exit(1);
}
const cardsRoot = path.join(args.repoPath, 'system-dev', 'wiki', 'cards');
const cardPaths = walkCards(cardsRoot);
const commit = gitCommit(args.repoPath);
const report = { repo: args.repo, commit, budget: args.budget, ceiling: SUBREQ_CEILING, cards: [], totals: {} };
let totEntries = 0, totEnvelopes = 0, totTriplets = 0, totNodes = 0, maxSub = 0, over = 0;
for (const p of cardPaths) {
const rel = path.relative(args.repoPath, p);
const md = readFileSync(p, 'utf8');
const plan = planCard(md, rel, args.repo, { budget: args.budget, commit });
totEntries++;
totEnvelopes += plan.envelopes.length;
const cardTriplets = plan.envelopes.reduce((s, e) => s + e.triplets.length, 0);
const cardNodes = plan.envelopes.reduce((s, e) => s + e.nodes.length, 0);
totTriplets += cardTriplets;
totNodes += cardNodes;
for (const e of plan.envelopes) {
maxSub = Math.max(maxSub, e._estSubrequests);
if (e._estSubrequests > SUBREQ_CEILING) over++;
}
report.cards.push({
relPath: rel,
canonical: plan.meta.canonical,
entry: {
page_name: plan.entry.page_name,
entry_type: plan.entry.entry_type,
'metadata.embed': plan.entry.metadata.embed,
content_hash: plan.entry.metadata.content_hash.slice(0, 12) + '…',
content_bytes: Buffer.byteLength(plan.entry.content, 'utf8'),
tags: plan.entry.tags,
},
envelopeCount: plan.envelopes.length,
envelopes: plan.envelopes.map((e) => ({
'source.uri': e.source.uri,
'source.anchor': e.source.anchor ?? null,
nodes: e.nodes.length,
triplets: e.triplets.length,
est_subrequests: e._estSubrequests,
under_ceiling: e._estSubrequests <= SUBREQ_CEILING,
sample_triplets: e.triplets.slice(0, args.full ? 999 : 4).map((t) => `${t.subject} >> ${t.predicate} >> ${t.object} (${t.confidence})`),
sample_nodes: e.nodes.slice(0, args.full ? 999 : 4).map((n) => `${n.name}${n.gloss ? ' — ' + n.gloss.slice(0, 30) + '…' : ''}`),
})),
});
}
report.totals = {
cards: totEntries,
entries_to_upsert: totEntries,
triplet_envelopes: totEnvelopes,
total_triplets: totTriplets,
total_nodes: totNodes,
max_est_subrequests_single_call: maxSub,
ceiling: SUBREQ_CEILING,
budget: args.budget,
any_envelope_over_ceiling: over,
};
// --- self-test：合成一張「超大卡」（20 邊 + 22 節點）證明單 envelope 會爆、分段後每段壓在預算下 ---
if (args.selfTest) {
const entities = [];
const edges = [];
for (let i = 0; i < 22; i++) entities.push(`- **實體${i}**（別名${i}）— 這是實體 ${i} 的一句描述。`);
for (let i = 0; i < 20; i++) edges.push(`- 實體${i} >> 關聯到 >> 實體${i + 1}`);
const bigCard = `---\ntags: [壓測]\ngloss: 合成超大卡，測分段。\n---\n# 合成超大卡\n\n← [[notes/00-INDEX]]\n\n## 實體\n${entities.join('\n')}\n\n## 關聯\n### 內文知識關係\n${edges.join('\n')}\n`;
const plan = planCard(bigCard, 'system-dev/wiki/cards/notes/合成超大卡.md', args.repo, { budget: args.budget });
const single = estimateEnvelopeSubrequests(plan.tripletCount, plan.nodeCount);
report.self_test = {
note: '合成 20 邊 / 22 節點 的超大卡',
if_single_envelope_est_subrequests: single,
would_crash_single: single > SUBREQ_CEILING,
segmented_into: plan.envelopes.length,
per_segment: plan.envelopes.map((e) => ({
uri: e.source.uri, anchor: e.source.anchor, triplets: e.triplets.length, nodes: e.nodes.length, est_subrequests: e._estSubrequests, under_ceiling: e._estSubrequests <= SUBREQ_CEILING,
})),
all_segments_under_ceiling: plan.envelopes.every((e) => e._estSubrequests <= SUBREQ_CEILING),
};
}
if (args.json) {
console.log(JSON.stringify(report, null, 2));
process.exit(0);
}
// --- 人類可讀輸出 ---
const L = (s = '') => console.log(s);
L(`\n================ km-wiki-ingest DRY-RUN（不寫 live）================`);
L(`repo=${report.repo} commit=${(commit || '(none)').slice(0, 12)} budget=${args.budget} CF_ceiling=${SUBREQ_CEILING}`);
L(`卡片來源根：${path.relative(args.repoPath, cardsRoot)} 找到 ${cardPaths.length} 張卡\n`);
for (const c of report.cards) {
L(`── 卡片：${c.relPath}`);
L(` ENTRY（base POST /entries 或 kbdb_upsert_block，冪等鍵 page_name）：`);
L(` page_name = ${c.entry.page_name}`);
L(` entry_type = ${c.entry.entry_type}`);
L(` metadata.embed= ${c.entry['metadata.embed']} content_hash=${c.entry.content_hash} bytes=${c.entry.content_bytes}`);
L(` tags = ${JSON.stringify(c.entry.tags)}`);
L(` TRIPLET ENVELOPE(s)（POST graph /triplets/ingest；分段數=${c.envelopeCount}）：`);
for (const e of c.envelopes) {
L(` • uri=${e['source.uri']}${e['source.anchor'] ? ' anchor=' + e['source.anchor'] : ''}`);
L(` nodes=${e.nodes} triplets=${e.triplets} est_subrequests=${e.est_subrequests} ≤ceiling? ${e.under_ceiling ? 'YES' : 'NO ⚠️'}`);
for (const t of e.sample_triplets) L(` - ${t}`);
if (e.sample_nodes.length) L(` nodes: ${e.sample_nodes.join(' | ')}`);
}
L('');
}
L(`================ 彙總 ================`);
for (const [k, v] of Object.entries(report.totals)) L(` ${k.padEnd(34)} = ${v}`);
L(` 冪等設計：`);
L(` entry → page_name（穩定鍵）+ metadata.content_hash（比對是否改動 → 未改 skip、改動 PATCH 重嵌）`);
L(` triplet → source.uri + source.content_hash（graph 現役 per-source 冪等；同 hash 整包 no-op）`);
L(` 分段 → 各段獨立 source.uri（#segNN）→ 各自獨立冪等，繞開 per-source content_hash 整包 skip`);
if (report.self_test) {
L(`\n================ SELF-TEST：超大檔分段 ================`);
const st = report.self_test;
L(` ${st.note}`);
L(` 若不分段（單 envelope）估算 subrequest = ${st.if_single_envelope_est_subrequests} → 會炸? ${st.would_crash_single ? 'YES（> ' + SUBREQ_CEILING + '）' : 'no'}`);
L(` 分段後段數 = ${st.segmented_into}，每段：`);
for (const s of st.per_segment) L(` - ${s.anchor}: triplets=${s.triplets} nodes=${s.nodes} est=${s.est_subrequests} ≤ceiling? ${s.under_ceiling ? 'YES' : 'NO ⚠️'}`);
L(` 全部段壓在上限下？ ${st.all_segments_under_ceiling ? 'YES ✅' : 'NO ⚠️'}`);
}
L('');
registry/examples/km-wiki-ingest/tags.json
+1
View File
@@ -0,0 +1 @@
["ingest", "kbdb", "wiki", "mechanical", "cron", "webhook", "graph", "triplet", "no-llm"]
registry/examples/km-wiki-ingest/workflow.yaml
+458
View File
@@ -0,0 +1,458 @@
name: km_wiki_ingest_drain
description: >
Phase 0 限速 drain：cron 每 tick 只處理「一張卡」→ 機械解析成 entry + triplet envelope
→ 冪等寫 KBDB（base entry / graph triplet）。反覆跑直到全庫 drain 完。
來源＝repo 的 system-dev/wiki/cards/**/*.md（人工精耕卡，非裸筆記，無 LLM）。
解析由通用 code 零件（sandbox inline JS）承載，不再鑄 domain 零件（Arcrun#10 裁定）。
穩態（Gitea push webhook 只處理 delta）見檔尾 §穩態變體。
# ── 為什麼「一 tick 一卡」＝根治 07_01 的 Too many subrequests ──
# graph worker 處理一次 POST /triplets/ingest 的 subrequest = 7 + 4*N_triplets + M_nodes + D_deprecated。
# 07_01 炸點：單一 envelope 吞整檔 N=11,M=10 → 61 > 50（CF bundled 上限）→ 半殘。
# 對策：① 一卡一 tick（天然小批，notes 卡 ~N4/M5 → est 28~33，穩壓 50 下）
# ② code 節點的內聯解析會自動把超大卡以 source_uri anchor 分段（每段獨立冪等）。
# ⟹ 任何單一 graph 呼叫都不會再破頂。
flow:
- "watch_cron >> ON_SUCCESS >> pick_next_card"
- "pick_next_card >> ON_SUCCESS >> fetch_card"
- "fetch_card >> ON_SUCCESS >> parse_card"
- "parse_card >> ON_SUCCESS >> upsert_entry" # 卡片 → base entry（embed=true），冪等
- "upsert_entry >> ON_SUCCESS >> post_envelopes" # wikilink/typed-edge → graph triplet
- "post_envelopes >> 對每個 envelope >> post_one_envelope" # 分段時多段，各段獨立冪等
config:
# 1) 排程 tick：慢推。每 2 分鐘一張卡＝限速（Phase 0 唯一需要 rate-limit 之處）。
watch_cron:
component: cron
cron_expr: "*/2 * * * *"
description: "每 2 分鐘 drain 一張卡（限速慢推，避免 CF 額度與 subrequest 壓力）"
# 2) 取下一張待處理卡（cursor drain）。用 Gitea contents API 列 cards 目錄 + 一個游標 block
# 記「處理到哪」。回傳單一 { rel_path, download_url, content_hash?(git blob sha) }。
# 註：list + cursor 的細節可用 http_request(Gitea API) + set/string_ops 組；此處給語意佔位。
pick_next_card:
component: http_request
method: GET
url: "https://git.uncle6.me/api/v1/repos/{{repo}}/contents/system-dev/wiki/cards?ref={{ref}}"
headers:
Authorization: "token {{gitea_token}}"
Accept: "application/json"
# 下游用 filter/set 取「游標之後第一張、且 .md、且非 00-INDEX」的一張。
# 3) 抓卡片全文（Gitea raw）。
fetch_card:
component: http_request
method: GET
url: "{{pick_next_card.next.download_url}}"
headers:
Authorization: "token {{gitea_token}}"
# 4) ★ 機械解析 —— 通用 code 零件（sandbox inline JS，無 LLM、無 fs/網路，stdin→stdout JSON）。
# Arcrun#10 裁定：一次性解析邏輯走通用逃生口，不再鑄 domain 零件 km_wiki_card_parse。
# 下面 code: 內聯的即 lib/card-to-envelope.mjs 的 planCard 邏輯（去 import/export、
# raw NUL 分隔符改 \u0000 escape、改用 code 沙箱注入的 curated builtin sha256；
# 已單測證明與原模組輸出逐欄全等）。
# input：卡片全文 md + 相對路徑 relPath + repo + opts.budget（subrequest 目標上限）。
# output：{ success:true, data:{ entry, envelopes[], meta, nodeCount, tripletCount } }
# —— envelope 已分段、已估 subrequest。故下游改引用 parse_card.data.*。
parse_card:
component: code
code: |
// km-wiki-ingest — 機械式卡片→(entry + triplet envelope) 轉換核心（無 LLM、純函式）
// ---------------------------------------------------------------------------
// 取代舊 `kbdb-ingest-plugin/scripts/ingest-cli.mjs` 的 raw→Haiku 路：
// 舊路 = 讀裸筆記 → 呼叫 Haiku 萃 (s,p,o) → envelope（有 LLM、非決定性、耗 token）。
// 新路 = 讀「已精耕卡片」（`system-dev/wiki/cards/**/*.md`）→ 直接解析卡片內既有的
// `## 實體`（節點）、`## 關聯` 的 typed-edge（`A >> 關係 >> B`）與 `[[wikilink]]`
// → entry + triplet envelope。純機械、決定性、零 token。
//
// 這支＝通用 `code` 零件（Arcrun#10，sandbox inline JS）承載的解析邏輯本體。
// workflow.yaml 的 parse_card 節點把本檔的 planCard 邏輯內聯進 code 零件的 config
// （去 import/export、raw NUL 分隔符改 u0000 escape、改用 code 沙箱注入的 sha256）；
// 不再鑄 domain 零件 km_wiki_card_parse（Arcrun#10 裁定：一次性解析走通用逃生口）。
// 本檔續留作「該內聯 JS 的權威來源 + 可單元測試的參考實作」（純函式、stdin→stdout JSON、無 fs/網路）。
//
// 對齊契約：kbdb-ingest-plugin/contracts/ingest-candidate.json（envelope 形狀 / 禁止欄位）。
// 對齊頂層 SDD：卡片→entry（metadata.embed=true，走 base API）、wikilink→triplet（走 graph）。
//
// 鐵律：不碰儲存、不算向量、不建表。這支只「產出將寫入什麼」，實際 HTTP 由 workflow 打。
// (import 移除：code 沙箱提供注入的 sha256 builtin)
// --- CF subrequest 預算（防「Too many subrequests by single Worker invocation」，07_01 根因）---
//
// graph worker 處理一次 POST /triplets/ingest 時，對 base 的每次 fetch = 1 subrequest。
// 精確拆帳（讀 kbdb-graph-plugin/src/actions/triplet-ingest.ts + triplet-crud.ts + templates.ts）：
// ingestEnvelope = ensurePluginTemplates(3) + listRecordsByTemplate(1)
// + Σ triplet [ createTriplet → ensurePluginTemplates(3) + createRecord(1) = 4 ]
// + persistNodes [ ensurePluginTemplates(3) + Σ node createRecord(1) ]
// + Σ deprecated updateRecord(1)
// ⟹ subreq(envelope) = 7 + 4*N_triplets + M_nodes + D_deprecated
//
// 07_01 實測炸點：N=11, M=10, D=0 → 7+44+10 = 61 > 50（CF 免費/bundled 上限）→ 炸半殘。
//
// 對策 = 「一卡一 tick、每 envelope 壓在預算下、超大檔以 source_uri anchor 分段」。
const SUBREQ_CEILING = 50; // CF 單次 Worker invocation subrequest 硬上限（bundled）
const SUBREQ_BUDGET = 40; // 我們的目標上限（留 10 給 D_deprecated 等變動）
/** 精確估算「一個 envelope 打進 graph /triplets/ingest」會在 graph worker 內產生幾個 subrequest。 */
function estimateEnvelopeSubrequests(nTriplets, mNodes, dDeprecated = 0) {
return 7 + 4 * nTriplets + mNodes + dDeprecated;
}
// --- sha256（content_hash 冪等鍵）---
// (sha256 移除：使用 code 沙箱注入的 curated builtin sha256)
// --- frontmatter 解析（極簡 YAML：只吃我們卡片用到的 tags / gloss / pipeline_candidate）---
function parseFrontmatter(md) {
const m = md.match(/^---\n([\s\S]*?)\n---\n?/);
if (!m) return { data: {}, body: md };
const body = md.slice(m[0].length);
const data = {};
for (const line of m[1].split('\n')) {
const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
if (!kv) continue;
const key = kv[1];
let val = kv[2].trim();
if (val.startsWith('[') && val.endsWith(']')) {
// inline list: [a, b, c]
data[key] = val.slice(1, -1).split(',').map((s) => s.trim()).filter(Boolean);
} else if (val === 'true' || val === 'false') {
data[key] = val === 'true';
} else {
data[key] = val;
}
}
return { data, body };
}
// --- 取某個 `## 標題` / `### 標題` 區塊的內文（到下一個同級或更高級標題為止）---
function sectionBody(md, heading) {
// heading 例：'## 實體'、'### 內文知識關係'
const level = heading.match(/^#+/)[0].length;
const lines = md.split('\n');
const out = [];
let inSec = false;
for (const line of lines) {
const h = line.match(/^(#+)\s+(.*)$/);
if (h) {
const thisLevel = h[1].length;
if (inSec) {
// 遇到同級或更高級標題 → 區塊結束
if (thisLevel <= level) break;
}
// 標題文字「開頭相符」即算命中（容忍標題後帶括號補述）
if (!inSec && thisLevel === level && line.replace(/^#+\s+/, '').startsWith(heading.replace(/^#+\s+/, ''))) {
inSec = true;
continue;
}
}
if (inSec) out.push(line);
}
return out.join('\n');
}
// --- 實體行解析：`- **正規名**（別名1／別名2）— 描述`（別名、描述皆選填）---
function parseEntities(md) {
const sec = sectionBody(md, '## 實體');
const entities = [];
for (const raw of sec.split('\n')) {
const line = raw.trim();
if (!line.startsWith('- ')) continue;
if (line.startsWith('- >') || line.startsWith('> ')) continue; // 跳過引言說明行
const m = line.match(/^- \*\*(.+?)\*\*(?:（(.+?)）)?\s*(?:[—–\-]\s*(.*))?$/);
if (!m) continue;
const name = m[1].trim();
if (!name) continue;
const aliases = m[2]
? m[2].split(/[／/、,]/).map((s) => s.trim()).filter((s) => s && s !== name)
: [];
const gloss = (m[3] || '').trim();
entities.push({ name, aliases, gloss });
}
return entities;
}
// --- typed-edge 行解析：`A >> 謂詞 >> B`（端點可為裸實體名或 [[wikilink]]）---
function parseTypedEdges(sectionText) {
const edges = [];
for (const raw of (sectionText || '').split('\n')) {
const line = raw.trim();
if (!line.startsWith('- ')) continue;
const body = line.slice(2).trim();
if (body.startsWith('（') || body.startsWith('(')) continue; // 「（暫無…）」占位行
const parts = body.split('>>');
if (parts.length !== 3) continue;
const subject = stripWikilink(parts[0].trim());
const predicate = parts[1].trim();
const object = stripWikilink(parts[2].trim());
if (!subject || !predicate || !object) continue;
edges.push({ subject, predicate, object });
}
return edges;
}
// [[notes/00-INDEX]] → notes/00-INDEX ；純字串則原樣回。
function stripWikilink(s) {
const m = s.match(/^\[\[(.+?)\]\]$/);
return m ? m[1].trim() : s;
}
// --- 抽所有 inline [[wikilink]]（含 header 的 ← [[notes/00-INDEX]] 與內文）---
function extractInlineWikilinks(md) {
const out = [];
const re = /\[\[(.+?)\]\]/g;
let m;
while ((m = re.exec(md)) !== null) out.push(m[1].trim());
return out;
}
// --- 卡片 canonical id：以檔名（去副檔名）為準，對齊 `## 卡片關係` 用的 [[基名]] 慣例 ---
function cardCanonical(relPath) {
const base = relPath.split('/').pop().replace(/\.md$/, '');
return base;
}
/**
* 解析一張卡片 → { entry, nodes, triplets, meta }（尚未分段的原始產物）。
* relPath：卡片相對 repo 根路徑（如 system-dev/wiki/cards/notes/Xxx.md）。
* repo：如 'Leo/notes'。
*/
function parseCard(md, relPath, repo = 'Leo/notes') {
const { data: fm } = parseFrontmatter(md);
const canonical = cardCanonical(relPath);
const titleMatch = md.match(/^#\s+(.+)$/m);
const title = titleMatch ? titleMatch[1].trim() : canonical;
// 1) 節點：## 實體 的正規名 + 別名 + gloss。
const entities = parseEntities(md);
// 2) 邊：內文知識關係（實體↔實體）+ 卡片關係（卡↔卡）+ inline wikilink（卡→卡 導覽/引用）。
const intraEdges = parseTypedEdges(sectionBody(md, '### 內文知識關係'))
.map((e) => ({ ...e, confidence: 1.0 }));
const cardEdges = parseTypedEdges(sectionBody(md, '### 卡片關係'))
.map((e) => ({ ...e, confidence: 1.0 }));
// inline wikilink（← [[notes/00-INDEX]] 等）→ 卡→卡「連結至」邊，去重、排除自環與已被 typed 邊覆蓋者。
const typedPairs = new Set(
[...cardEdges].map((e) => `${e.subject}\u0000${e.object}`),
);
const seenRef = new Set();
const refEdges = [];
for (const target of extractInlineWikilinks(md)) {
const t = stripWikilink(target);
if (t === canonical || t === title) continue; // 自環
if (typedPairs.has(`${canonical}\u0000${t}`)) continue; // 已有明確謂詞邊
const key = `${canonical}\u0000${t}`;
if (seenRef.has(key)) continue;
seenRef.add(key);
refEdges.push({ subject: canonical, predicate: '連結至', object: t, confidence: 0.5 });
}
const triplets = [...intraEdges, ...cardEdges, ...refEdges];
// 3) 節點清單：卡片本身（canonical，帶 frontmatter gloss）+ 內文實體。
// 卡對卡邊指到的「別張卡」不在此補 node —— 那張卡自己被 ingest 時會補自己的 node。
const nodes = [];
const seenNode = new Set();
const pushNode = (n) => {
const k = n.name.toLowerCase();
if (!n.name || seenNode.has(k)) return;
seenNode.add(k);
nodes.push(n);
};
pushNode({ name: canonical, gloss: fm.gloss || '', aliases: title && title !== canonical ? [title] : [] });
for (const e of entities) pushNode({ name: e.name, gloss: e.gloss, aliases: e.aliases });
return {
entry: {
// base POST /entries（或 kbdb_upsert_block）用。metadata.embed=true → 語意可搜。
page_name: `wikicard:${repo}/${canonical}`, // idempotency key（穩定）
entry_type: 'wiki_card',
content: md, // 卡片全文逐字（embed 對象）
tags: Array.isArray(fm.tags) ? fm.tags : [],
metadata: {
embed: true, // ★ base embed 模組讀此旗標
source: `gitea:${repo}@${relPath}`,
content_hash: sha256(md),
kind: 'wiki_card',
repo,
canonical,
pipeline_candidate: fm.pipeline_candidate === true,
},
},
nodes,
triplets,
meta: { canonical, title, relPath, repo, contentHash: sha256(md) },
};
}
/**
* 把一張卡片的 (nodes, triplets) 打包成「一個或多個」ingest envelope，
* 使每個 envelope 打進 graph 後的 subrequest 都 ≤ SUBREQ_BUDGET。
*
* 分段規則（對應頂層 SDD R4 / issue #8 第4點）：
* - 單 envelope 夠塞（7+4N+M ≤ budget）→ 不分段，uri = 基 uri（無 anchor）。
* - 需分段 → 每段 uri = `<基uri>#seg{NN}`、anchor = `seg{NN}`。
* 每段是「獨立 source_uri」→ 各自獨立冪等，繞開 graph 的 per-source content_hash 整包 skip
* （否則同 uri 第 2 段起會被 line 65 的 content_hash 命中而整包跳過）。
* - 節點只放進「第一個引用到它的段」，跨段不重送（避免 graph persistNodes 重建 entity record）。
*/
function planEnvelopes(parsed, opts = {}) {
const budget = opts.budget ?? SUBREQ_BUDGET;
const repo = parsed.meta.repo;
const relPath = parsed.meta.relPath;
const baseUri = `gitea:${repo}@${relPath}`;
const contentHash = parsed.meta.contentHash;
const commit = opts.commit;
const extractor = {
model: opts.extractorModel ?? 'mechanical/km-wiki-card-parse@1',
tier: 'deep', // 人工精耕卡＝deep（決定性、非淺萃）
extracted_at: Math.floor(Date.now() / 1000),
};
const nodeByName = new Map(parsed.nodes.map((n) => [n.name, n]));
// 貪婪打包：逐條 triplet 累進，段成本 = 7 + 4*(段內邊數) + (段內首見節點數)。
const segments = [];
let cur = null;
const startSeg = () => {
cur = { triplets: [], nodeNames: new Set() };
segments.push(cur);
};
const segCost = (seg, extraEdges = 0, extraNodes = 0) =>
estimateEnvelopeSubrequests(seg.triplets.length + extraEdges, seg.nodeNames.size + extraNodes);
startSeg();
for (const t of parsed.triplets) {
// 這條邊會新引入哪些節點（subject/object 命中 nodeByName 且本段尚未收）
const cand = [t.subject, t.object].filter(
(nm) => nodeByName.has(nm) && !cur.nodeNames.has(nm) && !anySegHas(segments, cur, nm),
);
// 放得下？（含新增這條邊 + 新引入節點）
if (cur.triplets.length > 0 && segCost(cur, 1, cand.length) > budget) {
startSeg();
}
cur.triplets.push(t);
for (const nm of [t.subject, t.object]) {
if (nodeByName.has(nm) && !anySegHas(segments, null, nm)) cur.nodeNames.add(nm);
}
}
const multi = segments.length > 1;
const envelopes = segments.map((seg, i) => {
const anchor = multi ? `seg${String(i + 1).padStart(2, '0')}` : undefined;
const uri = multi ? `${baseUri}#${anchor}` : baseUri;
const nodes = [...seg.nodeNames].map((nm) => {
const n = nodeByName.get(nm);
const out = { name: n.name };
if (n.gloss) out.gloss = n.gloss;
if (n.aliases && n.aliases.length) out.aliases = n.aliases;
out.embed = true;
return out;
});
const source = { uri, content_hash: contentHash };
if (anchor) source.anchor = anchor;
if (commit) source.commit = commit;
return {
source,
extractor,
nodes,
triplets: seg.triplets.map((t) => ({
subject: t.subject,
predicate: t.predicate,
object: t.object,
confidence: t.confidence ?? 1.0,
})),
_estSubrequests: estimateEnvelopeSubrequests(seg.triplets.length, seg.nodeNames.size),
};
});
// triplets≥1 是契約硬性；無邊的卡不產 envelope（仍會建 entry）。
return envelopes.filter((e) => e.triplets.length >= 1);
}
function anySegHas(segments, exclude, name) {
for (const s of segments) {
if (s === exclude) continue;
if (s.nodeNames.has(name)) return true;
}
return false;
}
/** 一張卡片 → 完整 ingest 計畫（entry + envelopes）。planCard = parseCard + planEnvelopes。 */
function planCard(md, relPath, repo = 'Leo/notes', opts = {}) {
const parsed = parseCard(md, relPath, repo);
const envelopes = planEnvelopes(parsed, opts);
return { entry: parsed.entry, envelopes, meta: parsed.meta, nodeCount: parsed.nodes.length, tripletCount: parsed.triplets.length };
}
// graph /triplets/ingest 是 strict schema，拒絕未知鍵。planEnvelopes 於 envelope 上掛的
// 診斷鍵 _estSubrequests 不在 ingest-candidate 契約內 → post 前剝除所有 _-前綴鍵，
// 讓 post_one_envelope 的 body_json={{envelope}} 為契約乾淨 payload。
// （leo21c 實測：不剝除會回 422 unrecognized_keys "_estSubrequests"。）
const __plan = planCard(input.md, input.relPath, input.repo, input.opts || {});
__plan.envelopes = __plan.envelopes.map(function (e) {
const clean = {};
for (const k in e) { if (k.charAt(0) !== '_') clean[k] = e[k]; }
return clean;
});
return __plan;
input:
md: "{{fetch_card.data.body}}"
relPath: "{{pick_next_card.next.rel_path}}"
repo: "{{repo}}"
opts:
budget: 40 # subrequest 目標上限（留 10 給 D_deprecated），超過自動 anchor 分段
limits:
timeout_ms: 3000 # 純 CPU 解析；大卡也充裕
max_output_bytes: 4194304 # envelope 陣列可能較大（4 MiB）
# 5) 卡片 → base entry，冪等 upsert（page_name 當鍵；找到 PATCH、沒有 POST）。
# metadata.embed=true → base embed 模組會補嵌 → 語意可搜。
upsert_entry:
component: kbdb_upsert_block
api_key: "{{kbdb_api_key}}"
kbdb_url: "{{kbdb_url}}"
page_name: "{{parse_card.data.entry.page_name}}"
type: "{{parse_card.data.entry.entry_type}}"
content: "{{parse_card.data.entry.content}}"
source: "{{parse_card.data.entry.metadata.source}}"
tags_json: "{{parse_card.data.entry.tags_json}}"
# ⚠️ metadata.embed=true / content_hash 需經 base /entries 帶 metadata_json 落地；
# 若 kbdb_upsert_block 尚未透傳 metadata_json，改用 http_request 直打 base POST/PATCH /entries
# 帶 body_json.metadata_json（見 description.md §entry 冪等）。
# 6) triplet envelope（可能多段）→ 逐段 POST graph /triplets/ingest。
# graph 端 per-source(uri+content_hash) 冪等：同 hash 整包 no-op；分段各段 uri 不同 → 各自獨立冪等。
post_envelopes:
component: foreach_control
items: "{{parse_card.data.envelopes}}"
item_key: envelope
post_one_envelope:
component: http_request
method: POST
url: "{{graph_url}}/triplets/ingest"
headers:
Content-Type: "application/json"
X-Arcrun-API-Key: "{{graph_api_key}}"
body_json: "{{envelope}}" # envelope 已符合 ingest-candidate.json 契約（禁止欄位已排除）
# ── 執行環境變數（部署時注入；此檔不放密鑰）──
# repo=Leo/notes ref=main gitea_token=<GITEA_TOKEN>
# kbdb_url=https://arcrun-kbdb.leo21c.workers.dev kbdb_api_key=<partner key>
# graph_url=<graph plugin base url on leo21c> graph_api_key=leo
#
# ═══════════════════════════════════════════════════════════════════════════
# §穩態變體（km_wiki_ingest_delta）：Gitea push webhook → 只處理 delta 檔
# ═══════════════════════════════════════════════════════════════════════════
# 觸發 = Gitea repo Settings → Webhooks → 指向 arcrun(cypher-executor) 的 workflow webhook URL。
# ⚠️ 這是 Gitea → Cloudflare(arcrun)，非 GitHub Actions → 不觸 GitHub flag 紅線（D4/D20）。
# 只把上面 flow 的 watch_cron/pick_next_card 換成：
# input（webhook payload）>> ON_SUCCESS >> collect_changed
# collect_changed = 從 payload.commits[].{added,modified} 濾出 system-dev/wiki/cards/**/*.md
# >> foreach 檔 >> fetch_card >> parse_card >> upsert_entry >> post_envelopes（同上）
# 量小、天生不撞頂、不需限速；靠 graph/entry 冪等自動 skip 未變檔。