From 30c9312c57581a8647b8c7822e3c1836b1e9b7c2 Mon Sep 17 00:00:00 2001 From: uncle6me-web Date: Sat, 15 Aug 2026 13:47:27 +0800 Subject: [PATCH] =?UTF-8?q?wiki:=20=E6=8B=BF=E7=9C=9F=E5=AF=A6=E7=9A=84=20?= =?UTF-8?q?docs/=20=E5=A5=97=E6=96=B0=E8=A6=8F=E7=AF=84=E8=B7=91=E4=B8=80?= =?UTF-8?q?=E6=AC=A1=EF=BC=8827=20=E5=BC=B5=E5=8D=A1=EF=BC=8C=E5=85=A9?= =?UTF-8?q?=E5=80=8B=E7=AF=80=E9=BB=9E=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit leo 2026-08-15：「我是說不是要用真實的資料夾套新規範做一次？」 對 matrix/arcrun/docs 的兩個節點做了真的萃取（不是模擬）： · docs/ 5 篇原稿 → 5 文件卡 ＋ 9 概念卡 ＋ 1 主題（結構性閘） · user_requirements/ 4 篇 → 2 文件卡 ＋ 7 概念卡 ＋ 1 主題（讓生態自己長） 踩到並如實處理的四個邊緣案例： ① arcrun-landing-page/ 只有 .jsx/.html/.css ⇒ 依規範不是節點，不建 .wiki（index 說明有寫） ② credential_parts.md 29KB、12 個 H2，超過 20KB 分段門檻 ⇒ 只萃 §0–§2，其餘八段在文件卡上如實標明未做——一張卡蓋不住 29KB ③ wishlist.md 是「空」的第三種：指針檔（不是沒東西、不是紀錄） ⇒ 標 no_concept 不產卡。我第一版給它產了卡，wiki-lint 當場報孤島卡抓到 ④ 三個子節點未萃，在 index 標「未萃」——標出來使用者才分得出「沒東西」和「還沒做」 並依 leo 的判準拿掉 type 欄位： 「在這個類似 Logseq 的結構裡根本不分，你要想的是在寫函式時是否不同」 逐一檢查 place_card／patch_card／promote_hub／split_hub／渲染／三個信號／lint ——沒有任何函式需要類型欄位，需要的全是結構屬性（有無父／有無子／有無判斷）， 而那三個都是現算的。⇒ type: hub 與 hub_kind 拿掉，wiki-lint 改成用算的。 promote_hub 因此不是改型別，是在有子的卡上補一段判斷，型別自己就變了。 實測：docs 樹 節點 2｜卡片 27｜卡外邊 62，十五項全 0，退出碼 0 Co-Authored-By: Claude Opus 5 --- docs/.wiki/00-INDEX.md | 58 +++++++++++++++++++ docs/.wiki/AI 讀不到的隱形分層.md | 42 ++++++++++++++ .../HANDOFF-config-scope-and-vectorize.md | 34 +++++++++++ docs/.wiki/HANDOFF-matrix-rearrange.md | 32 ++++++++++ docs/.wiki/HANDOFF-mira-repair.md | 34 +++++++++++ docs/.wiki/HANDOFF-self-host-harness.md | 34 +++++++++++ docs/.wiki/Mira workflow 斷鏈.md | 40 +++++++++++++ docs/.wiki/component-pr-review-standard.md | 34 +++++++++++ docs/.wiki/cypher 雙份分岔.md | 37 ++++++++++++ docs/.wiki/manifest.json | 57 ++++++++++++++++++ docs/.wiki/scope 誤部風險.md | 41 +++++++++++++ docs/.wiki/self-hosted 戰法轉向.md | 39 +++++++++++++ docs/.wiki/假零件降級.md | 41 +++++++++++++ docs/.wiki/成功的定義.md | 40 +++++++++++++ docs/.wiki/結構性閘.md | 37 ++++++++++++ docs/.wiki/規則記不住.md | 40 +++++++++++++ docs/.wiki/零件 PR 審核閘.md | 46 +++++++++++++++ docs/user_requirements/.wiki/00-INDEX.md | 55 ++++++++++++++++++ .../.wiki/AI 的 marketplace.md | 42 ++++++++++++++ .../.wiki/credential_parts.md | 34 +++++++++++ .../.wiki/n8n 的每服務一零件.md | 37 ++++++++++++ docs/user_requirements/.wiki/u6u_design.md | 37 ++++++++++++ .../四個 primitive 不是每服務一個零件.md | 44 ++++++++++++++ .../.wiki/自動審核取代人工.md | 41 +++++++++++++ docs/user_requirements/.wiki/視覺優先開發.md | 41 +++++++++++++ .../.wiki/解釋 webhook 的困難.md | 37 ++++++++++++ docs/user_requirements/.wiki/讓生態自己長.md | 36 ++++++++++++ .../user_requirements/.wiki/零件長尾誰來補.md | 41 +++++++++++++ 28 files changed, 1131 insertions(+) create mode 100644 docs/.wiki/00-INDEX.md create mode 100644 docs/.wiki/AI 讀不到的隱形分層.md create mode 100644 docs/.wiki/HANDOFF-config-scope-and-vectorize.md create mode 100644 docs/.wiki/HANDOFF-matrix-rearrange.md create mode 100644 docs/.wiki/HANDOFF-mira-repair.md create mode 100644 docs/.wiki/HANDOFF-self-host-harness.md create mode 100644 docs/.wiki/Mira workflow 斷鏈.md create mode 100644 docs/.wiki/component-pr-review-standard.md create mode 100644 docs/.wiki/cypher 雙份分岔.md create mode 100644 docs/.wiki/manifest.json create mode 100644 docs/.wiki/scope 誤部風險.md create mode 100644 docs/.wiki/self-hosted 戰法轉向.md create mode 100644 docs/.wiki/假零件降級.md create mode 100644 docs/.wiki/成功的定義.md create mode 100644 docs/.wiki/結構性閘.md create mode 100644 docs/.wiki/規則記不住.md create mode 100644 docs/.wiki/零件 PR 審核閘.md create mode 100644 docs/user_requirements/.wiki/00-INDEX.md create mode 100644 docs/user_requirements/.wiki/AI 的 marketplace.md create mode 100644 docs/user_requirements/.wiki/credential_parts.md create mode 100644 docs/user_requirements/.wiki/n8n 的每服務一零件.md create mode 100644 docs/user_requirements/.wiki/u6u_design.md create mode 100644 docs/user_requirements/.wiki/四個 primitive 不是每服務一個零件.md create mode 100644 docs/user_requirements/.wiki/自動審核取代人工.md create mode 100644 docs/user_requirements/.wiki/視覺優先開發.md create mode 100644 docs/user_requirements/.wiki/解釋 webhook 的困難.md create mode 100644 docs/user_requirements/.wiki/讓生態自己長.md create mode 100644 docs/user_requirements/.wiki/零件長尾誰來補.md diff --git a/docs/.wiki/00-INDEX.md b/docs/.wiki/00-INDEX.md new file mode 100644 index 0000000..52a5674 --- /dev/null +++ b/docs/.wiki/00-INDEX.md @@ -0,0 +1,58 @@ +# 00-INDEX（arcrun/docs） + +> 機器整理的 wiki。**原稿在上一層**，這裡不放原文。有爭議時以原稿為準。 + +## 子節點 + +- **user_requirements** → `../user_requirements/.wiki/00-INDEX.md` + 主題：u6u 四層架構、credential 三層模型｜概念：Polaris 意圖層、零件宇宙、AuthBroker… + `#規格 #架構 #credential`　4 篇（含 1 篇指針）　更 2026-08-15 + +## 文件（本層每一篇一張） + +- [[HANDOFF-config-scope-and-vectorize]] — 一份交辦文件，指出 arcrun 設定分層的兩條缺口，萃出兩個概念。 + `#文件 #設定`　建 2026-06-15　更 2026-08-15 +- [[HANDOFF-matrix-rearrange]] — Matrix 重整交給 arcrun 的待辦清單，用指針式考古不複製素材。 + `#文件 #遷移`　建 2026-06-13　更 2026-08-15 +- [[HANDOFF-mira-repair]] — 一份修復交辦，把調查做完了：哪些不用改、哪些要改、哪些要降級。 + `#文件 #事故`　建 2026-06-03　更 2026-08-15 +- [[HANDOFF-self-host-harness]] — 一份把「今天要做的三件事」連同已查證實況整理好的交辦，核心是戰法轉向。 + `#文件 #策略`　建 2026-06-01　更 2026-08-15 +- [[component-pr-review-standard]] — 零件與 binding 的 PR 審核規範，五段 checklist，任一否就打回。 + `#文件 #流程`　建 2026-06-03　更 2026-08-15 + +## 主題（跨文件聚類產生） + +- [[結構性閘]] — 把錯誤路徑做成「根本碰不到」，而不是叮嚀人不要走。 + `#方法論 #流程 #架構`　建 2026-06-03　更 2026-08-15 + +## 本層概念（9） + +- [[AI 讀不到的隱形分層]] — arcrun 是給 AI 操作的工具，而 harness 說明 41 行對 scope 零字提及。 + `#設定 #AI 協作`　建 2026-06-15　更 2026-08-15 +- [[Mira workflow 斷鏈]] — Mira 六個 workflow 全斷，但真因不是 arcrun 壞了，是 Mira 當初把東西錯做成假零件。 + `#事故 #零件`　建 2026-06-03　更 2026-08-15 +- [[cypher 雙份分岔]] — matrix 與 arcrun 各有一份 cypher-executor 且已分岔——整合後只留 arcrun 一份。 + `#架構 #遷移`　建 2026-06-13　更 2026-08-15 +- [[scope 誤部風險]] — 部署到哪個 CF 帳號，取決於你當下站在哪個資料夾——而這件事沒有任何地方寫著。 + `#設定 #風險`　建 2026-06-15　更 2026-08-15 +- [[self-hosted 戰法轉向]] — 2026-06-01 從 SaaS 改成 self-hosted 開源——它改的不只是商業模式，是「成功」的定義。 + `#策略 #部署`　建 2026-06-01　更 2026-08-15 +- [[假零件降級]] — 打固定 endpoint 的東西不是零件是 recipe——33 顆降到 22 顆，代價是所有引用它的人斷鏈。 + `#零件 #架構`　建 2026-06-03　更 2026-08-15 +- [[成功的定義]] — 舊：在我的帳號上能跑。新：任何人在自己的帳號上跑得通，而且寫錯會被擋住。 + `#策略 #驗收`　建 2026-06-01　更 2026-08-15 +- [[規則記不住]] — 規定說幾次都沒用——這不是紀律問題，是機制缺席。 + `#流程 #AI 協作`　建 2026-06-03　更 2026-08-15 +- [[零件 PR 審核閘]] — 靠「AI 記住規則」防架構錯誤不 scale，所以把錯誤擋在 PR 這道結構性閘上。 + `#流程 #架構 #審核`　建 2026-06-03　更 2026-08-15 + +## 說明 + +> 上面四節是**機器讀的**，只准放連結／路徑；說明寫在這一節，**不要用連結語法**。 +> 每一行的摘要／標籤／日期都是從卡的 frontmatter 複製過來的 ⇒ index 可機械產生。 +> +> 🔴 **`user_requirements/arcrun-landing-page/` 不在任何清單上，這是對的**—— +> 它只有 `.jsx`／`.html`／`.css`，**沒有可掃文件 ⇒ 依規範它不是節點**，不建 `.wiki`。 +> +> 本層只長出一個主題（結構性閘），因為另外幾張卡各自獨立、還湊不出第二個主題。 diff --git a/docs/.wiki/AI 讀不到的隱形分層.md b/docs/.wiki/AI 讀不到的隱形分層.md new file mode 100644 index 0000000..3ad7a93 --- /dev/null +++ b/docs/.wiki/AI 讀不到的隱形分層.md @@ -0,0 +1,42 @@ +--- +tags: [設定, AI 協作] +gloss: arcrun 是給 AI 操作的工具，而 harness 說明 41 行對 scope 零字提及。 +created: 2026-06-15 +updated: 2026-08-15 +--- +# AI 讀不到的隱形分層 + +← [[HANDOFF-config-scope-and-vectorize]] + +## 摘要 + +真實事故：mira 被交代遷移時沒看懂 scope 存在，差點誤部官方帳號。病根不在它笨，在它讀的東西裡沒有這一層。 + +## 重點 + +- **arcrun 的操作者是 AI 不是人**（mindset §2），所以「AI 讀得到什麼」就是「系統有什麼」 +- 而 harness block 全文 41 行，**對 scope／帳號歸屬／誤部風險 0 字** +- ⇒ mira 把「搬資料」跟「用哪個帳號」混為一談——**那是兩件獨立的事** +- 這是 [[結構性閘]] 的另一面：規則沒被寫在會被讀到的地方，等於不存在 + +## 實體 + +- **harness block**（介面）— AI 讀 arcrun 時看到的說明，`cli/harness/CLAUDE.block.md`。 +- **遷移 ≠ scope**（判準）— 搬資料與用哪個帳號是兩件獨立的事。 + +## 關聯 + +### 內文知識關係 + +- harness block >> 沒有提及 >> scope +- AI >> 只知道 >> harness block 寫的東西 + +### 卡片關係 + +- AI 讀不到的隱形分層 >> 屬於 >> [[HANDOFF-config-scope-and-vectorize]] +- AI 讀不到的隱形分層 >> 屬於 >> [[結構性閘]] +- AI 讀不到的隱形分層 >> 被誤部風險放大 >> [[scope 誤部風險]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../HANDOFF-config-scope-and-vectorize.md` >> 提及 >> AI 讀不到的隱形分層 diff --git a/docs/.wiki/HANDOFF-config-scope-and-vectorize.md b/docs/.wiki/HANDOFF-config-scope-and-vectorize.md new file mode 100644 index 0000000..d7e0304 --- /dev/null +++ b/docs/.wiki/HANDOFF-config-scope-and-vectorize.md @@ -0,0 +1,34 @@ +--- +tags: [文件, 設定] +gloss: 一份交辦文件，指出 arcrun 設定分層的兩條缺口，萃出兩個概念。 +created: 2026-06-15 +updated: 2026-08-15 +--- +# HANDOFF-config-scope-and-vectorize + +← [[00-INDEX]] + +## 摘要 + +2026-06-15 頂層總管交辦。由 mira self-hosted dogfood 踩出來的兩條框架缺口，兩條都走 SDD 協議。 + +## 重點 + +- **缺口 1** 是功能面：讀分層完整但只能寫全域 ⇒ [[scope 誤部風險]] +- **缺口 2 被作者標為最重要**：AI 讀的說明裡完全沒有這一層 ⇒ [[AI 讀不到的隱形分層]] +- 文件還帶了第三塊（KBDB Vectorize 開關），但那部分在本次萃取中沒有獨立成概念 + +## 實體 + +- **HANDOFF-config-scope-and-vectorize**（原稿）— 本卡對應的那一份交辦文件。 + +## 關聯 + +### 卡片關係 + +- HANDOFF-config-scope-and-vectorize >> 涵蓋 >> [[AI 讀不到的隱形分層]] +- HANDOFF-config-scope-and-vectorize >> 涵蓋 >> [[scope 誤部風險]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../HANDOFF-config-scope-and-vectorize.md` >> 提及 >> HANDOFF-config-scope-and-vectorize diff --git a/docs/.wiki/HANDOFF-matrix-rearrange.md b/docs/.wiki/HANDOFF-matrix-rearrange.md new file mode 100644 index 0000000..a40a280 --- /dev/null +++ b/docs/.wiki/HANDOFF-matrix-rearrange.md @@ -0,0 +1,32 @@ +--- +tags: [文件, 遷移] +gloss: Matrix 重整交給 arcrun 的待辦清單，用指針式考古不複製素材。 +created: 2026-06-13 +updated: 2026-08-15 +--- +# HANDOFF-matrix-rearrange + +← [[00-INDEX]] + +## 摘要 + +頂層重整的產物。第一條就是關掉 matrix 版 cypher-executor。 + +## 重點 + +- **主要問題**：[[cypher 雙份分岔]]，含逐檔的勘查結果 +- **指針式考古**：素材真身留在 `_archive/`，這份只給路徑——**不複製進來，避免第二份真相** + +## 實體 + +- **HANDOFF-matrix-rearrange**（原稿）— 本卡對應的那一份交辦文件。 + +## 關聯 + +### 卡片關係 + +- HANDOFF-matrix-rearrange >> 涵蓋 >> [[cypher 雙份分岔]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../HANDOFF-matrix-rearrange.md` >> 提及 >> HANDOFF-matrix-rearrange diff --git a/docs/.wiki/HANDOFF-mira-repair.md b/docs/.wiki/HANDOFF-mira-repair.md new file mode 100644 index 0000000..210c624 --- /dev/null +++ b/docs/.wiki/HANDOFF-mira-repair.md @@ -0,0 +1,34 @@ +--- +tags: [文件, 事故] +gloss: 一份修復交辦，把調查做完了：哪些不用改、哪些要改、哪些要降級。 +created: 2026-06-03 +updated: 2026-08-15 +--- +# HANDOFF-mira-repair + +← [[00-INDEX]] + +## 摘要 + +arcrun 端的 CC 寫給 mira 端的 CC。特色是「調查已做完，照著改即可，不必重跑」。 + +## 重點 + +- **事故**：[[Mira workflow 斷鏈]]——六個 workflow 全掃過 +- **真因**：[[假零件降級]]，而 mira 當初錯做了假零件 +- **這份文件本身示範了一件事**：交辦時把調查結果一起交出去，接手的人才不會重跑一遍 + +## 實體 + +- **HANDOFF-mira-repair**（原稿）— 本卡對應的那一份交辦文件。 + +## 關聯 + +### 卡片關係 + +- HANDOFF-mira-repair >> 涵蓋 >> [[Mira workflow 斷鏈]] +- HANDOFF-mira-repair >> 涵蓋 >> [[假零件降級]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../HANDOFF-mira-repair.md` >> 提及 >> HANDOFF-mira-repair diff --git a/docs/.wiki/HANDOFF-self-host-harness.md b/docs/.wiki/HANDOFF-self-host-harness.md new file mode 100644 index 0000000..cf7cd8c --- /dev/null +++ b/docs/.wiki/HANDOFF-self-host-harness.md @@ -0,0 +1,34 @@ +--- +tags: [文件, 策略] +gloss: 一份把「今天要做的三件事」連同已查證實況整理好的交辦，核心是戰法轉向。 +created: 2026-06-01 +updated: 2026-08-15 +--- +# HANDOFF-self-host-harness + +← [[00-INDEX]] + +## 摘要 + +2026-06-01 撰寫。它最重要的一段不是任務，是背景：戰法已經變了。 + +## 重點 + +- **背景**：[[self-hosted 戰法轉向]] +- **後果**：[[成功的定義]] 被整個改寫 +- **它的體例值得學**：先講「戰法已轉變（最重要的背景）」，再講今天做什麼 + +## 實體 + +- **HANDOFF-self-host-harness**（原稿）— 本卡對應的那一份交辦文件。 + +## 關聯 + +### 卡片關係 + +- HANDOFF-self-host-harness >> 涵蓋 >> [[self-hosted 戰法轉向]] +- HANDOFF-self-host-harness >> 涵蓋 >> [[成功的定義]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../HANDOFF-self-host-harness.md` >> 提及 >> HANDOFF-self-host-harness diff --git a/docs/.wiki/Mira workflow 斷鏈.md b/docs/.wiki/Mira workflow 斷鏈.md new file mode 100644 index 0000000..4c78106 --- /dev/null +++ b/docs/.wiki/Mira workflow 斷鏈.md @@ -0,0 +1,40 @@ +--- +tags: [事故, 零件] +gloss: Mira 六個 workflow 全斷，但真因不是 arcrun 壞了，是 Mira 當初把東西錯做成假零件。 +created: 2026-06-03 +updated: 2026-08-15 +--- +# Mira workflow 斷鏈 + +← [[HANDOFF-mira-repair]] + +## 摘要 + +整修後 mira 的 workflow 斷了。調查結論：prod 活著、降級的 recipe 都在 KV，大部分只需小改不必重寫。 + +## 重點 + +- **不是 arcrun 壞了**——`cypher.arcrun.dev` 活著，降級後的 recipe 都在 prod KV（已驗） +- **是 Mira 當初自己把一堆東西錯做成假零件** ⇒ [[假零件降級]] 一動它就斷 +- **教訓**：引用「不該存在的東西」的人，會在那個東西被修正時付出代價 + +## 實體 + +- **六個 workflow**（受害範圍）— mira 全部的 workflow 都掃過了。 +- **降級後的 recipe**（現況）— kbdb_get／telegram_send／gmail_send 等都在 prod KV。 + +## 關聯 + +### 內文知識關係 + +- Mira >> 錯做成 >> 假零件 +- 假零件降級 >> 導致 >> Mira workflow 斷鏈 + +### 卡片關係 + +- Mira workflow 斷鏈 >> 屬於 >> [[HANDOFF-mira-repair]] +- Mira workflow 斷鏈 >> 肇因於 >> [[假零件降級]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../HANDOFF-mira-repair.md` >> 提及 >> Mira workflow 斷鏈 diff --git a/docs/.wiki/component-pr-review-standard.md b/docs/.wiki/component-pr-review-standard.md new file mode 100644 index 0000000..0f0e0ce --- /dev/null +++ b/docs/.wiki/component-pr-review-standard.md @@ -0,0 +1,34 @@ +--- +tags: [文件, 流程] +gloss: 零件與 binding 的 PR 審核規範，五段 checklist，任一否就打回。 +created: 2026-06-03 +updated: 2026-08-15 +--- +# component-pr-review-standard + +← [[00-INDEX]] + +## 摘要 + +它的開場白就是整份文件的論點：靠 AI 記住規則不 scale，所以把錯誤擋在結構上。 + +## 重點 + +- **論點**：[[規則記不住]] +- **手法**：[[零件 PR 審核閘]]，五段 A–E 逐條過 +- 每一段都附了**真實反例**（`km_wiki_card_parse` 被否、drainer 本地綠但撞 1042）——**反例比規則本身有用** + +## 實體 + +- **component-pr-review-standard**（原稿）— 本卡對應的那一份交辦文件。 + +## 關聯 + +### 卡片關係 + +- component-pr-review-standard >> 涵蓋 >> [[規則記不住]] +- component-pr-review-standard >> 涵蓋 >> [[零件 PR 審核閘]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../component-pr-review-standard.md` >> 提及 >> component-pr-review-standard diff --git a/docs/.wiki/cypher 雙份分岔.md b/docs/.wiki/cypher 雙份分岔.md new file mode 100644 index 0000000..0a2797f --- /dev/null +++ b/docs/.wiki/cypher 雙份分岔.md @@ -0,0 +1,37 @@ +--- +tags: [架構, 遷移] +gloss: matrix 與 arcrun 各有一份 cypher-executor 且已分岔——整合後只留 arcrun 一份。 +created: 2026-06-13 +updated: 2026-08-15 +--- +# cypher 雙份分岔 + +← [[HANDOFF-matrix-rearrange]] + +## 摘要 + +勘查結果：matrix 版獨有 5 檔（皆非 SaaS 遺留，是 self-hosted 核心）、兩邊都有但內容不同 10 檔要逐檔比對。 + +## 重點 + +- **matrix 獨有的 5 檔是要保留的**：版本選擇策略、缺件自動生成、雙模式路由、WASM 執行、proxy +- **10 檔內容分岔**要逐檔比對合併，取較完整的一邊但保留 arcrun 較新的 auth 演進 +- **同一個東西有兩份且都在演化 ⇒ 必然分岔**，這是要儘早合併的理由 + +## 實體 + +- **diverged 副本**（狀態）— 同源但各自演化後內容不同的兩份。 + +## 關聯 + +### 內文知識關係 + +- 兩份副本 >> 各自演化 >> 內容分岔 + +### 卡片關係 + +- cypher 雙份分岔 >> 屬於 >> [[HANDOFF-matrix-rearrange]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../HANDOFF-matrix-rearrange.md` >> 提及 >> cypher 雙份分岔 diff --git a/docs/.wiki/manifest.json b/docs/.wiki/manifest.json new file mode 100644 index 0000000..d776fad --- /dev/null +++ b/docs/.wiki/manifest.json @@ -0,0 +1,57 @@ +{ + "schema": 3, + "note": "卡→原文寫在卡的『### 出處』；原文→卡寫在這裡。多對多。", + "docs": [ + { + "doc_id": "d_000", + "node": "(根)", + "path": "HANDOFF-config-scope-and-vectorize.md", + "提及": [ + "HANDOFF-config-scope-and-vectorize", + "AI 讀不到的隱形分層", + "結構性閘", + "scope 誤部風險" + ] + }, + { + "doc_id": "d_001", + "node": "(根)", + "path": "HANDOFF-matrix-rearrange.md", + "提及": [ + "HANDOFF-matrix-rearrange", + "cypher 雙份分岔" + ] + }, + { + "doc_id": "d_002", + "node": "(根)", + "path": "HANDOFF-mira-repair.md", + "提及": [ + "假零件降級", + "Mira workflow 斷鏈", + "HANDOFF-mira-repair" + ] + }, + { + "doc_id": "d_003", + "node": "(根)", + "path": "HANDOFF-self-host-harness.md", + "提及": [ + "成功的定義", + "self-hosted 戰法轉向", + "HANDOFF-self-host-harness" + ] + }, + { + "doc_id": "d_004", + "node": "(根)", + "path": "component-pr-review-standard.md", + "提及": [ + "零件 PR 審核閘", + "規則記不住", + "結構性閘", + "component-pr-review-standard" + ] + } + ] +} diff --git a/docs/.wiki/scope 誤部風險.md b/docs/.wiki/scope 誤部風險.md new file mode 100644 index 0000000..acffa52 --- /dev/null +++ b/docs/.wiki/scope 誤部風險.md @@ -0,0 +1,41 @@ +--- +tags: [設定, 風險] +gloss: 部署到哪個 CF 帳號，取決於你當下站在哪個資料夾——而這件事沒有任何地方寫著。 +created: 2026-06-15 +updated: 2026-08-15 +--- +# scope 誤部風險 + +← [[HANDOFF-config-scope-and-vectorize]] + +## 摘要 + +arcrun 的設定讀取分三層（env > 專案 > 全域），但寫入只能寫全域，而「我現在會部到哪」沒有任何提示。 + +## 重點 + +- **讀分層完整、寫只能全域**：`saveConfig()` 寫死 `~/.arcrun/config.yaml`，`acr init` 四處呼叫全寫全域 +- ⇒ 想用專案層的人被迫污染全域，**怕誤打官方帳號** +- **最陰險的是 fallback**：任一層都沒 `mode` 就靜默當 `local`，不報錯——你會看到「成功」但雲端沒有 trace +- 真正的病灶不是缺功能，是 [[AI 讀不到的隱形分層]] + +## 實體 + +- **scope 分層**（機制）— env > 專案 `.arcrun.yaml` > 全域 `~/.arcrun/config.yaml`。 +- **靜默 fallback**（陷阱）— 沒設 mode 就當 local，不報錯。 + +## 關聯 + +### 內文知識關係 + +- scope 分層 >> 決定 >> 部署到哪個帳號 +- 靜默 fallback >> 造成 >> 看到成功但沒有雲端 trace + +### 卡片關係 + +- scope 誤部風險 >> 屬於 >> [[HANDOFF-config-scope-and-vectorize]] +- scope 誤部風險 >> 根因是 >> [[AI 讀不到的隱形分層]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../HANDOFF-config-scope-and-vectorize.md` >> 提及 >> scope 誤部風險 diff --git a/docs/.wiki/self-hosted 戰法轉向.md b/docs/.wiki/self-hosted 戰法轉向.md new file mode 100644 index 0000000..fbccd4f --- /dev/null +++ b/docs/.wiki/self-hosted 戰法轉向.md @@ -0,0 +1,39 @@ +--- +tags: [策略, 部署] +gloss: 2026-06-01 從 SaaS 改成 self-hosted 開源——它改的不只是商業模式，是「成功」的定義。 +created: 2026-06-01 +updated: 2026-08-15 +--- +# self-hosted 戰法轉向 + +← [[HANDOFF-self-host-harness]] + +## 摘要 + +richblack 的決定。連帶把 self-hosted 一鍵起得來從「重要但非阻擋項」升為第一優先。 + +## 重點 + +- **改的是驗收標準**，見 [[成功的定義]] +- ⇒ 優先序跟著翻轉：self-host 起得來變成當日第一優先 +- **戰法一變，原本排在後面的東西可能立刻變成阻擋項**——這是排序時要先問「戰法變了嗎」的理由 + +## 實體 + +- **self-hosted 開源策略**（戰法）— 使用者在自己的 CF 帳號上跑，而非平台託管。 + +## 關聯 + +### 內文知識關係 + +- 戰法轉向 >> 改變 >> 優先序 +- self-hosted >> 取代 >> SaaS + +### 卡片關係 + +- self-hosted 戰法轉向 >> 屬於 >> [[HANDOFF-self-host-harness]] +- self-hosted 戰法轉向 >> 改寫了 >> [[成功的定義]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../HANDOFF-self-host-harness.md` >> 提及 >> self-hosted 戰法轉向 diff --git a/docs/.wiki/假零件降級.md b/docs/.wiki/假零件降級.md new file mode 100644 index 0000000..5e2af01 --- /dev/null +++ b/docs/.wiki/假零件降級.md @@ -0,0 +1,41 @@ +--- +tags: [零件, 架構] +gloss: 打固定 endpoint 的東西不是零件是 recipe——33 顆降到 22 顆，代價是所有引用它的人斷鏈。 +created: 2026-06-03 +updated: 2026-08-15 +--- +# 假零件降級 + +← [[HANDOFF-mira-repair]] + +## 摘要 + +arcrun 大整修：把「打固定 API 卻被做成零件」的假零件降級成 recipe 並刪掉零件目錄。判準是 DECISIONS §1：零件＝endpoint 薄殼。 + +## 重點 + +- **判準**：零件是可複用的原語；**打固定 API 的是 recipe** +- **33 → 22 顆**，被降級的解析方式變了 ⇒ 造成 [[Mira workflow 斷鏈]] +- 這正是 [[零件 PR 審核閘]] 要在源頭擋掉的東西——**降級是補救，審核才是預防** + +## 實體 + +- **假零件**（反模式）— 打固定 API 卻被做成零件的東西。 +- **recipe**（正解）— 具名封裝的單一 API 呼叫。 + +## 關聯 + +### 內文知識關係 + +- 假零件 >> 應降級為 >> recipe +- 降級 >> 改變了 >> 零件名的解析方式 + +### 卡片關係 + +- 假零件降級 >> 屬於 >> [[HANDOFF-mira-repair]] +- 假零件降級 >> 被擋於 >> [[零件 PR 審核閘]] +- 假零件降級 >> 觸發了 >> [[Mira workflow 斷鏈]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../HANDOFF-mira-repair.md` >> 提及 >> 假零件降級 diff --git a/docs/.wiki/成功的定義.md b/docs/.wiki/成功的定義.md new file mode 100644 index 0000000..530e92e --- /dev/null +++ b/docs/.wiki/成功的定義.md @@ -0,0 +1,40 @@ +--- +tags: [策略, 驗收] +gloss: 舊：在我的帳號上能跑。新：任何人在自己的帳號上跑得通，而且寫錯會被擋住。 +created: 2026-06-01 +updated: 2026-08-15 +--- +# 成功的定義 + +← [[HANDOFF-self-host-harness]] + +## 摘要 + +戰法轉向後，harness 的成功定義被整個改寫。新定義多了一個常被忽略的下半句。 + +## 重點 + +- **舊**：在 richblack 的 prod 帳號（`cypher.arcrun.dev`）上能跑 +- **新**：任何 CC 在自己的 CF 帳號 `acr init --self-hosted` 後跑通一個含 recipe 的 workflow +- 🔴 **而且「寫錯時會被程式擋住」是定義的一部分**——不是加分項 +- ⇒ 這句話直接推導出 [[零件 PR 審核閘]] 這類 [[結構性閘]] 的必要性 + +## 實體 + +- **新成功定義**（驗收）— 任何人在自己帳號跑通，且寫錯會被擋。 + +## 關聯 + +### 內文知識關係 + +- 新定義 >> 包含 >> 寫錯會被擋住 +- 舊定義 >> 只涵蓋 >> 作者自己的帳號 + +### 卡片關係 + +- 成功的定義 >> 屬於 >> [[HANDOFF-self-host-harness]] +- 成功的定義 >> 被改寫於 >> [[self-hosted 戰法轉向]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../HANDOFF-self-host-harness.md` >> 提及 >> 成功的定義 diff --git a/docs/.wiki/結構性閘.md b/docs/.wiki/結構性閘.md new file mode 100644 index 0000000..fdb38ea --- /dev/null +++ b/docs/.wiki/結構性閘.md @@ -0,0 +1,37 @@ +--- +tags: [方法論, 流程, 架構] +gloss: 把錯誤路徑做成「根本碰不到」，而不是叮嚀人不要走。 +created: 2026-06-03 +updated: 2026-08-15 +--- +# 結構性閘 + +← [[00-INDEX]] + +## 摘要 + +這個主題把三張卡收在一起，因為它們是同一個手法的三個場合：不靠自覺，靠結構。 + +## 重點 + +- 把 [[零件 PR 審核閘]] 收進來，是因為它明講了理由——**零件本來就要走 PR，所以把檢查放在那裡，錯誤路徑就碰不到** +- 而 [[規則記不住]] 是這個手法的前提：**規定說幾次都沒用，這不是紀律問題是機制缺席** +- [[AI 讀不到的隱形分層]] 則是同一件事的反面——**規則沒被放在會被讀到的地方，等於不存在** +- ⇒ 三張卡合起來給出一條可複用的判準：**看到「說過很多次還是會犯」，就去找那個缺席的閘** + +## 實體 + +- **結構性閘**（手法）— 讓錯誤路徑在結構上碰不到，而非靠遵守。 + +## 關聯 + +### 卡片關係 + +- 結構性閘 >> 收攏 >> [[AI 讀不到的隱形分層]] +- 結構性閘 >> 收攏 >> [[規則記不住]] +- 結構性閘 >> 收攏 >> [[零件 PR 審核閘]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../component-pr-review-standard.md` >> 提及 >> 結構性閘 +- `../HANDOFF-config-scope-and-vectorize.md` >> 提及 >> 結構性閘 diff --git a/docs/.wiki/規則記不住.md b/docs/.wiki/規則記不住.md new file mode 100644 index 0000000..294b79c --- /dev/null +++ b/docs/.wiki/規則記不住.md @@ -0,0 +1,40 @@ +--- +tags: [流程, AI 協作] +gloss: 規定說幾次都沒用——這不是紀律問題，是機制缺席。 +created: 2026-06-03 +updated: 2026-08-15 +--- +# 規則記不住 + +← [[component-pr-review-standard]] + +## 摘要 + +審核規範開宗明義的一句：「靠 AI 記住規則防架構錯誤不 scale」。它是整份文件存在的理由。 + +## 重點 + +- **規定寫得再清楚，沒有機制驗證就等於沒有** +- ⇒ 對策不是寫更多規定，是**把錯誤路徑做成碰不到** +- 這條可以推廣到任何「說過很多次還是會犯」的問題——**去找那個缺席的閘** + +## 實體 + +- **不 scale**（性質）— 規則數量增加時，靠記憶遵守的成功率下降。 + +## 關聯 + +### 內文知識關係 + +- 靠記憶遵守規則 >> 不 scale +- 缺席的機制 >> 才是 >> 真正的病灶 + +### 卡片關係 + +- 規則記不住 >> 屬於 >> [[component-pr-review-standard]] +- 規則記不住 >> 屬於 >> [[結構性閘]] +- 規則記不住 >> 治的是 >> [[零件 PR 審核閘]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../component-pr-review-standard.md` >> 提及 >> 規則記不住 diff --git a/docs/.wiki/零件 PR 審核閘.md b/docs/.wiki/零件 PR 審核閘.md new file mode 100644 index 0000000..d4fab8f --- /dev/null +++ b/docs/.wiki/零件 PR 審核閘.md @@ -0,0 +1,46 @@ +--- +tags: [流程, 架構, 審核] +gloss: 靠「AI 記住規則」防架構錯誤不 scale，所以把錯誤擋在 PR 這道結構性閘上。 +created: 2026-06-03 +updated: 2026-08-15 +--- +# 零件 PR 審核閘 + +← [[component-pr-review-standard]] + +## 摘要 + +零件與 service binding 本來就要走 PR，所以把檢查放在那裡，讓錯誤路徑「根本碰不到」。五段 checklist，任一否就打回。 + +## 重點 + +- **A 反過度工程**：判準是「三個月後會有第二個 workflow 用它嗎」，不會就不是零件 +- **B binding 層級**（最常踩）：跨-worker 編排一律走 cypher binding，service binding 只准組 wasm +- **D 驗證誠實**：要打**部署後的真端點**，本地 miniflare 會假綠——實例是 drainer 本地綠、production 撞 1042 +- **E 部署鐵律**：wrangler 直推，不用 `acr update`（會假綠蓋掉改動） +- 它治的是 [[規則記不住]]，手法屬於 [[結構性閘]] + +## 實體 + +- **PR 審核閘**（機制）— 零件與 binding 變更的強制檢查點。 +- **假綠**（反模式）— 本地測試通過但生產環境會失敗。 +- **三個月判準**（判準）— 未來三個月會不會有第二個使用者。 + +## 關聯 + +### 內文知識關係 + +- PR 審核 >> 擋下 >> 架構錯誤 +- 本地 miniflare >> 產生 >> 假綠 +- 三個月判準 >> 決定 >> 是不是零件 + +### 卡片關係 + +- 零件 PR 審核閘 >> 實作 >> 結構性閘 >> [[規則記不住]] +- 零件 PR 審核閘 >> 屬於 >> [[component-pr-review-standard]] +- 零件 PR 審核閘 >> 屬於 >> [[結構性閘]] +- 零件 PR 審核閘 >> 擋的正是 >> [[假零件降級]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../component-pr-review-standard.md` >> 提及 >> 零件 PR 審核閘 diff --git a/docs/user_requirements/.wiki/00-INDEX.md b/docs/user_requirements/.wiki/00-INDEX.md new file mode 100644 index 0000000..adb1306 --- /dev/null +++ b/docs/user_requirements/.wiki/00-INDEX.md @@ -0,0 +1,55 @@ +# 00-INDEX（user_requirements） + +← `../../.wiki/00-INDEX.md` + +## 子節點 + +- **ADR-lib-and-landingPage** → `../ADR-lib-and-landingPage/.wiki/00-INDEX.md` — 3 篇（未萃） +- **simplify_mvp** → `../simplify_mvp/.wiki/00-INDEX.md` — 1 篇（未萃） +- **u6u-long-term** → `../u6u-long-term/.wiki/00-INDEX.md` — 1 篇＋子節點 SourceDocs 3 篇（未萃） + +## 文件（本層每一篇一張） + +- [[credential_parts]] — 29KB 的 credential 規格，本次只萃了 §0–§2，其餘尚未分段。 + `#文件 #credential`　建 2026-05-25　更 2026-08-15 +- [[u6u_design]] — 一份兩千字的設計筆記，密度很高，萃出五個概念。 + `#文件 #設計`　建 2026-05-20　更 2026-08-15 +- `../wishlist.md` — **空**：指針檔，全文都在說「已移至頂層」。真身在 `InkStoneCo/docs/1-vision/product-wishlist.md` + +## 主題（跨文件聚類產生） + +- [[讓生態自己長]] — u6u 對「零件從哪來、誰把關、爛的怎麼淘汰」的整套答案：三件事互相咬合。 + `#生態 #零件 #方法論`　建 2026-05-20　更 2026-08-15 + +## 本層概念（7） + +- [[AI 的 marketplace]] — marketplace 給 AI 不給人：強制用完回評價，被評差的零件其他 AI 自動避開。 + `#生態 #零件`　建 2026-05-20　更 2026-08-15 +- [[n8n 的每服務一零件]] — n8n 為每個服務寫一個 credential 零件——這份文件開宗明義說那是錯的。 + `#credential #反模式`　建 2026-05-25　更 2026-08-15 +- [[四個 primitive 不是每服務一個零件]] — 做四個 TinyGo/WASM primitive，每個服務只要一份 YAML recipe ＋ 用戶自己的 secret。 + `#credential #架構`　建 2026-05-25　更 2026-08-15 +- [[自動審核取代人工]] — call API 的只要 call 通就過，功能性的只要通過它自己設的 Gherkin 就過。 + `#流程 #零件`　建 2026-05-20　更 2026-08-15 +- [[視覺優先開發]] — 用戶拉一個按鈕，後面自然綁上 webhook——不用解釋 webhook 是什麼。 + `#產品 #介面`　建 2026-05-20　更 2026-08-15 +- [[解釋 webhook 的困難]] — 要跟一般用戶解釋什麼是 webhook 很難——這是低門檻產品真正的門檻。 + `#產品 #介面`　建 2026-05-20　更 2026-08-15 +- [[零件長尾誰來補]] — 沒有人會為了 delete table 去寫完整的 Google Sheets 零件——但缺的那個端點會被下一個需要的人補上。 + `#生態 #零件`　建 2026-05-20　更 2026-08-15 + +## 說明 + +> 上面四節是機器讀的；說明寫這裡，不要用連結語法。 +> +> 🔴 **`arcrun-landing-page/` 沒有出現在子節點清單裡，這是對的**—— +> 它只有 `.jsx`／`.html`／`.css`，**沒有可掃文件 ⇒ 依規範不是節點**。 +> +> 🔴 **三個子節點標「未萃」是誠實的殘缺**：本次真實測試只做了 `docs/` 與本層兩個節點。 +> 標出來，使用者才分得出「沒東西」和「還沒做」。 +> +> 🔴 **`wishlist.md` 是「空」的第三種**：不是沒東西（待辦）、不是紀錄（報價單），是**指針**。 +> 依規範標 `no_concept` **不產卡**——我第一版給它產了卡，`wiki-lint` 當場報孤島卡抓到。 +> +> 🔴 **`credential_parts.md` 是 29KB、12 個 H2**，超過 20KB 分段門檻。 +> 本次只萃了 §0–§2，其餘八段**如實標明未做**——一張卡蓋不住 29KB。 diff --git a/docs/user_requirements/.wiki/AI 的 marketplace.md b/docs/user_requirements/.wiki/AI 的 marketplace.md new file mode 100644 index 0000000..d61eabb --- /dev/null +++ b/docs/user_requirements/.wiki/AI 的 marketplace.md @@ -0,0 +1,42 @@ +--- +tags: [生態, 零件] +gloss: marketplace 給 AI 不給人：強制用完回評價，被評差的零件其他 AI 自動避開。 +created: 2026-05-20 +updated: 2026-08-15 +--- +# AI 的 marketplace + +← [[u6u_design]] + +## 摘要 + +u6u 的零件市集設計。它跟一般 marketplace 的差別在使用者是 AI，所以回饋可以被強制。 + +## 重點 + +- **強制回評價**——AI 不像人會忘記或懶得評 +- **被評差幾次的零件，其他 AI 自動避開** ⇒ 淘汰不需要人介入 +- 它配的是 [[自動審核取代人工]]，兩者合起來讓 [[零件長尾誰來補]] 有解 + +## 實體 + +- **AI marketplace**（機制）— 使用者是 AI 的零件市集，回饋可強制。 +- **自然淘汰**（效果）— 差評零件被自動避開。 + +## 關聯 + +### 內文知識關係 + +- AI >> 被強制 >> 回覆評價 +- 低評零件 >> 被 >> 其他 AI 避開 + +### 卡片關係 + +- AI 的 marketplace >> 屬於 >> [[u6u_design]] +- AI 的 marketplace >> 屬於 >> [[讓生態自己長]] +- AI 的 marketplace >> 機制是 >> [[自動審核取代人工]] +- AI 的 marketplace >> 解的是 >> [[零件長尾誰來補]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../u6u_design.md` >> 提及 >> AI 的 marketplace diff --git a/docs/user_requirements/.wiki/credential_parts.md b/docs/user_requirements/.wiki/credential_parts.md new file mode 100644 index 0000000..fd92837 --- /dev/null +++ b/docs/user_requirements/.wiki/credential_parts.md @@ -0,0 +1,34 @@ +--- +tags: [文件, credential] +gloss: 29KB 的 credential 規格，本次只萃了 §0–§2，其餘尚未分段。 +created: 2026-05-25 +updated: 2026-08-15 +--- +# credential_parts + +← [[00-INDEX]] + +## 摘要 + +這份文件超過本規範的 20KB 分段門檻，共 12 個 H2 段落。本次示範「只萃前段、其餘誠實標明未做」。 + +## 重點 + +- 已萃：[[四個 primitive 不是每服務一個零件]]、[[n8n 的每服務一零件]]（來自 §0 TL;DR 與 §1–2） +- 🔴 **未萃**：§3 四個 primitive 詳細規格／§4 Recipe Schema／§5 繼承／§6 WASM 介面／§7 AuthBroker API／§8 Storage／§9 授權 UI／§10 TODO／§11 風險 +- **這正是「大檔要按 H2 分段」那個洞的實例**——一張卡蓋不住 29KB + +## 實體 + +- **credential_parts**（原稿）— 本卡對應的那一份文件。 + +## 關聯 + +### 卡片關係 + +- credential_parts >> 涵蓋 >> [[n8n 的每服務一零件]] +- credential_parts >> 涵蓋 >> [[四個 primitive 不是每服務一個零件]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../credential_parts.md` >> 提及 >> credential_parts diff --git a/docs/user_requirements/.wiki/n8n 的每服務一零件.md b/docs/user_requirements/.wiki/n8n 的每服務一零件.md new file mode 100644 index 0000000..6add092 --- /dev/null +++ b/docs/user_requirements/.wiki/n8n 的每服務一零件.md @@ -0,0 +1,37 @@ +--- +tags: [credential, 反模式] +gloss: n8n 為每個服務寫一個 credential 零件——這份文件開宗明義說那是錯的。 +created: 2026-05-25 +updated: 2026-08-15 +--- +# n8n 的每服務一零件 + +← [[credential_parts]] + +## 摘要 + +被點名的反模式。它的問題是零件數量隨服務數量線性成長，而認證方式其實只有幾種。 + +## 重點 + +- **零件數 ∝ 服務數**，但認證方式其實只有四種 +- ⇒ 正解是 [[四個 primitive 不是每服務一個零件]] + +## 實體 + +- **每服務一零件**（反模式）— n8n 的 credential 做法。 + +## 關聯 + +### 內文知識關係 + +- 零件數 >> 隨服務數 >> 線性成長 + +### 卡片關係 + +- n8n 的每服務一零件 >> 否定 >> [[四個 primitive 不是每服務一個零件]] +- n8n 的每服務一零件 >> 屬於 >> [[credential_parts]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../credential_parts.md` >> 提及 >> n8n 的每服務一零件 diff --git a/docs/user_requirements/.wiki/u6u_design.md b/docs/user_requirements/.wiki/u6u_design.md new file mode 100644 index 0000000..a105c6d --- /dev/null +++ b/docs/user_requirements/.wiki/u6u_design.md @@ -0,0 +1,37 @@ +--- +tags: [文件, 設計] +gloss: 一份兩千字的設計筆記，密度很高，萃出五個概念。 +created: 2026-05-20 +updated: 2026-08-15 +--- +# u6u_design + +← [[00-INDEX]] + +## 摘要 + +開場一句「u6u 是一個 AI Friendly 的 n8n」，後面是條列的設計主張，最後一段是觀念想法。 + +## 重點 + +- **生態那三條**被收成 [[讓生態自己長]] +- **介面策略**是 [[視覺優先開發]]，它迴避 [[解釋 webhook 的困難]] +- ⚠️ 文件最後一句「考慮讓他自己 OWN，企業版資料獨立」**沒有展開，本次未萃成卡** + +## 實體 + +- **u6u_design**（原稿）— 本卡對應的那一份文件。 + +## 關聯 + +### 卡片關係 + +- u6u_design >> 涵蓋 >> [[AI 的 marketplace]] +- u6u_design >> 涵蓋 >> [[自動審核取代人工]] +- u6u_design >> 涵蓋 >> [[視覺優先開發]] +- u6u_design >> 涵蓋 >> [[解釋 webhook 的困難]] +- u6u_design >> 涵蓋 >> [[零件長尾誰來補]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../u6u_design.md` >> 提及 >> u6u_design diff --git a/docs/user_requirements/.wiki/四個 primitive 不是每服務一個零件.md b/docs/user_requirements/.wiki/四個 primitive 不是每服務一個零件.md new file mode 100644 index 0000000..d57523d --- /dev/null +++ b/docs/user_requirements/.wiki/四個 primitive 不是每服務一個零件.md @@ -0,0 +1,44 @@ +--- +tags: [credential, 架構] +gloss: 做四個 TinyGo/WASM primitive，每個服務只要一份 YAML recipe ＋ 用戶自己的 secret。 +created: 2026-05-25 +updated: 2026-08-15 +--- +# 四個 primitive 不是每服務一個零件 + +← [[credential_parts]] + +## 摘要 + +credential 設計的核心主張。它是三層模型：primitive（程式）／recipe（公共設定）／secret（私有）。 + +## 重點 + +- **四個 primitive** 涵蓋所有認證方式，不隨服務數量成長 +- **recipe 存平台 KV（公共）、secret 存 tenant KV（私有）**，runtime 由 AuthBroker 組裝 +- 它明確反對 [[n8n 的每服務一零件]] +- ⚠️ 本卡只涵蓋這份 29KB 文件的 §0–§2；`§3 四個 primitive 詳細規格`、`§4 Recipe Schema` 等**尚未分段萃取** + +## 實體 + +- **primitive**（零件）— TinyGo/WASM 寫的認證原語，共四個。 +- **recipe**（設定）— 每服務一份 YAML，存公共 KV。 +- **AuthBroker**（組裝者）— runtime 把 recipe 與 secret 組成可用的 HTTP client。 + +## 關聯 + +### 內文知識關係 + +- primitive >> 加上 >> recipe 與 secret +- AuthBroker >> 組裝 >> 可用的 HTTP client +- recipe >> 存於 >> 公共 KV +- secret >> 存於 >> tenant KV + +### 卡片關係 + +- 四個 primitive 不是每服務一個零件 >> 反的是 >> [[n8n 的每服務一零件]] +- 四個 primitive 不是每服務一個零件 >> 屬於 >> [[credential_parts]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../credential_parts.md` >> 提及 >> 四個 primitive 不是每服務一個零件 diff --git a/docs/user_requirements/.wiki/自動審核取代人工.md b/docs/user_requirements/.wiki/自動審核取代人工.md new file mode 100644 index 0000000..d571347 --- /dev/null +++ b/docs/user_requirements/.wiki/自動審核取代人工.md @@ -0,0 +1,41 @@ +--- +tags: [流程, 零件] +gloss: call API 的只要 call 通就過，功能性的只要通過它自己設的 Gherkin 就過。 +created: 2026-05-20 +updated: 2026-08-15 +--- +# 自動審核取代人工 + +← [[u6u_design]] + +## 摘要 + +把「零件能不能上架」的判斷交給可執行的檢查，省掉人工審核。 + +## 重點 + +- **打 API 的**：成功 call 通就算過 +- **功能性的**：通過投稿者自己寫的 Gherkin 就算過 +- ⚠️ 這條跟後來的 `component-pr-review-standard` 有張力——那份明講 **Gherkin 全綠 ≠ 零件安全**（投稿者可寫避重就輕的 Gherkin） +- ⇒ **兩份文件寫於不同時期，後者修正了前者**。真正框死破壞力的是純 WASI 沙箱，不是 Gherkin + +## 實體 + +- **Gherkin 自審**（機制）— 投稿者自寫驗收條件，通過即上架。 + +## 關聯 + +### 內文知識關係 + +- call API 成功 >> 即通過 >> 審核 +- Gherkin 全綠 >> 不等於 >> 零件安全 + +### 卡片關係 + +- 自動審核取代人工 >> 屬於 >> [[u6u_design]] +- 自動審核取代人工 >> 屬於 >> [[讓生態自己長]] +- 自動審核取代人工 >> 支撐 >> [[AI 的 marketplace]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../u6u_design.md` >> 提及 >> 自動審核取代人工 diff --git a/docs/user_requirements/.wiki/視覺優先開發.md b/docs/user_requirements/.wiki/視覺優先開發.md new file mode 100644 index 0000000..7b4ca42 --- /dev/null +++ b/docs/user_requirements/.wiki/視覺優先開發.md @@ -0,0 +1,41 @@ +--- +tags: [產品, 介面] +gloss: 用戶拉一個按鈕，後面自然綁上 webhook——不用解釋 webhook 是什麼。 +created: 2026-05-20 +updated: 2026-08-15 +--- +# 視覺優先開發 + +← [[u6u_design]] + +## 摘要 + +u6u 的低門檻策略：讓抽象概念從具體操作裡浮現，而不是先教會使用者術語。 + +## 重點 + +- **先做前端按鈕、輸入框，後端邏輯跟著綁上去** +- **點下去就看到工作流** ⇒ 概念從操作裡長出來 +- 它迴避的是 [[解釋 webhook 的困難]] +- 延伸：cypher 放大就是 graph，**每個功能可以摺疊成一點，也可以 zoom in 展開調整** ⇒ 同一個碎型結構 + +## 實體 + +- **視覺優先**（策略）— 先給看得見的操作，再讓概念浮現。 +- **摺疊與展開**（互動）— 功能可收成一點也可展開調整。 + +## 關聯 + +### 內文知識關係 + +- 前端按鈕 >> 綁定 >> webhook +- cypher 放大 >> 就是 >> graph + +### 卡片關係 + +- 視覺優先開發 >> 屬於 >> [[u6u_design]] +- 視覺優先開發 >> 迴避了 >> [[解釋 webhook 的困難]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../u6u_design.md` >> 提及 >> 視覺優先開發 diff --git a/docs/user_requirements/.wiki/解釋 webhook 的困難.md b/docs/user_requirements/.wiki/解釋 webhook 的困難.md new file mode 100644 index 0000000..e8ad2ec --- /dev/null +++ b/docs/user_requirements/.wiki/解釋 webhook 的困難.md @@ -0,0 +1,37 @@ +--- +tags: [產品, 介面] +gloss: 要跟一般用戶解釋什麼是 webhook 很難——這是低門檻產品真正的門檻。 +created: 2026-05-20 +updated: 2026-08-15 +--- +# 解釋 webhook 的困難 + +← [[u6u_design]] + +## 摘要 + +一句被順帶寫下、但其實是整個介面策略起點的觀察。 + +## 重點 + +- **門檻不在功能，在術語** +- ⇒ 對策不是寫更好的說明文件，是 [[視覺優先開發]]——讓他不必知道那個詞 + +## 實體 + +- **術語門檻**（障礙）— 使用者卡在概念名稱而非功能本身。 + +## 關聯 + +### 內文知識關係 + +- 術語 >> 構成 >> 使用門檻 + +### 卡片關係 + +- 解釋 webhook 的困難 >> 屬於 >> [[u6u_design]] +- 解釋 webhook 的困難 >> 被迴避於 >> [[視覺優先開發]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../u6u_design.md` >> 提及 >> 解釋 webhook 的困難 diff --git a/docs/user_requirements/.wiki/讓生態自己長.md b/docs/user_requirements/.wiki/讓生態自己長.md new file mode 100644 index 0000000..f78a4b6 --- /dev/null +++ b/docs/user_requirements/.wiki/讓生態自己長.md @@ -0,0 +1,36 @@ +--- +tags: [生態, 零件, 方法論] +gloss: u6u 對「零件從哪來、誰把關、爛的怎麼淘汰」的整套答案：三件事互相咬合。 +created: 2026-05-20 +updated: 2026-08-15 +--- +# 讓生態自己長 + +← [[00-INDEX]] + +## 摘要 + +這個主題把三張卡收在一起，因為它們是同一個迴圈的三段：怎麼補、怎麼把關、怎麼淘汰。 + +## 重點 + +- 起點是 [[零件長尾誰來補]]——**不預先做完整，缺的時候由需要的人補** +- 把關交給 [[自動審核取代人工]]，因為人工審核會變成瓶頸 +- 淘汰交給 [[AI 的 marketplace]]，**而它能成立的唯一原因是使用者是 AI**（回饋可以被強制） +- ⇒ **三段缺一段這個迴圈就停**：沒人補、沒人審、或爛的不會消失，生態都長不起來 + +## 實體 + +- **生態迴圈**（結構）— 補件、把關、淘汰三段互相咬合。 + +## 關聯 + +### 卡片關係 + +- 讓生態自己長 >> 收攏 >> [[AI 的 marketplace]] +- 讓生態自己長 >> 收攏 >> [[自動審核取代人工]] +- 讓生態自己長 >> 收攏 >> [[零件長尾誰來補]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../u6u_design.md` >> 提及 >> 讓生態自己長 diff --git a/docs/user_requirements/.wiki/零件長尾誰來補.md b/docs/user_requirements/.wiki/零件長尾誰來補.md new file mode 100644 index 0000000..eca45bb --- /dev/null +++ b/docs/user_requirements/.wiki/零件長尾誰來補.md @@ -0,0 +1,41 @@ +--- +tags: [生態, 零件] +gloss: 沒有人會為了 delete table 去寫完整的 Google Sheets 零件——但缺的那個端點會被下一個需要的人補上。 +created: 2026-05-20 +updated: 2026-08-15 +--- +# 零件長尾誰來補 + +← [[u6u_design]] + +## 摘要 + +u6u 對「零件覆蓋率」的答案：不追求完整，追求需要時補得上，而搜尋會把碎片整合起來。 + +## 重點 + +- **每個 API call 獨立，但搜尋會整合**——有人做了 create table，下一個人要 delete 時發現沒有就直接做一個 +- **下次搜 google sheets 就同時看到兩個端點** ⇒ 覆蓋率由需求長出來，不由規劃決定 +- 這正是 [[AI 的 marketplace]] 要服務的形狀 + +## 實體 + +- **長尾覆蓋**（問題）— 沒人會預先寫完整的 API 包裝。 +- **搜尋整合**（機制）— 碎片端點在搜尋時被聚合成一組。 + +## 關聯 + +### 內文知識關係 + +- 需求 >> 決定 >> 覆蓋率 +- 搜尋 >> 整合 >> 獨立的端點 + +### 卡片關係 + +- 零件長尾誰來補 >> 對策是 >> [[AI 的 marketplace]] +- 零件長尾誰來補 >> 屬於 >> [[u6u_design]] +- 零件長尾誰來補 >> 屬於 >> [[讓生態自己長]] + +### 出處（原文 >> 提及 >> 本卡，可多筆） + +- `../u6u_design.md` >> 提及 >> 零件長尾誰來補