pi-knowledge 0.15.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +59 -22
  3. package/dist/index.d.ts +10 -4
  4. package/dist/index.js +145 -166
  5. package/dist/src/coverage-snapshot.d.ts +23 -0
  6. package/dist/src/coverage-snapshot.js +53 -0
  7. package/dist/src/daemon/client.d.ts +60 -0
  8. package/dist/src/daemon/client.js +360 -0
  9. package/dist/src/daemon/main.d.ts +2 -0
  10. package/dist/src/daemon/main.js +109 -0
  11. package/dist/src/daemon/protocol.d.ts +71 -0
  12. package/dist/src/daemon/protocol.js +170 -0
  13. package/dist/src/daemon/runtime.d.ts +26 -0
  14. package/dist/src/daemon/runtime.js +192 -0
  15. package/dist/src/daemon/server.d.ts +46 -0
  16. package/dist/src/daemon/server.js +500 -0
  17. package/dist/src/daemon/service.d.ts +49 -0
  18. package/dist/src/daemon/service.js +527 -0
  19. package/dist/src/diagnostics/health.d.ts +6 -0
  20. package/dist/src/diagnostics/health.js +135 -2
  21. package/dist/src/engine.d.ts +13 -8
  22. package/dist/src/engine.js +569 -100
  23. package/dist/src/filesystem-access.d.ts +9 -0
  24. package/dist/src/filesystem-access.js +100 -0
  25. package/dist/src/indexer/chunker.d.ts +10 -0
  26. package/dist/src/indexer/chunker.js +284 -9
  27. package/dist/src/mcp/http.d.ts +47 -0
  28. package/dist/src/mcp/http.js +564 -0
  29. package/dist/src/mcp/main.d.ts +2 -0
  30. package/dist/src/mcp/main.js +97 -0
  31. package/dist/src/mcp/protocol.d.ts +81 -0
  32. package/dist/src/mcp/protocol.js +444 -0
  33. package/dist/src/mcp/server.d.ts +42 -0
  34. package/dist/src/mcp/server.js +378 -0
  35. package/dist/src/model-worker-client.js +9 -0
  36. package/dist/src/model-worker-contract.d.ts +3 -0
  37. package/dist/src/model-worker-contract.js +8 -0
  38. package/dist/src/model-worker.js +76 -4
  39. package/dist/src/network/safe-fetch.d.ts +7 -0
  40. package/dist/src/network/safe-fetch.js +199 -0
  41. package/dist/src/node-runtime.d.ts +3 -0
  42. package/dist/src/node-runtime.js +78 -0
  43. package/dist/src/profiles.d.ts +15 -0
  44. package/dist/src/profiles.js +160 -0
  45. package/dist/src/runtime-config.js +5 -6
  46. package/dist/src/secure-files.d.ts +17 -0
  47. package/dist/src/secure-files.js +184 -0
  48. package/dist/src/status.js +12 -7
  49. package/dist/src/storage/sqlite.d.ts +4 -1
  50. package/dist/src/storage/sqlite.js +46 -3
  51. package/dist/src/type-guards.d.ts +1 -0
  52. package/dist/src/type-guards.js +3 -0
  53. package/dist/src/watcher/file-watcher.d.ts +3 -1
  54. package/dist/src/watcher/file-watcher.js +166 -32
  55. package/dist/src/windows-security.d.ts +4 -0
  56. package/dist/src/windows-security.js +47 -0
  57. package/docs/configuration.md +39 -9
  58. package/docs/daemon-profiles.md +302 -0
  59. package/docs/mcp-clients.md +266 -0
  60. package/docs/offline-mode.md +6 -6
  61. package/package.json +28 -2
@@ -0,0 +1,47 @@
1
+ import { execFileSync } from "node:child_process";
2
+ import { isAbsolute, join } from "node:path";
3
+ import { isObjectRecord } from "./type-guards.js";
4
+ function powershellPath() {
5
+ const systemRoot = process.env.SystemRoot?.trim() || process.env.WINDIR?.trim() || "C:\\Windows";
6
+ if (!isAbsolute(systemRoot))
7
+ throw new Error("Windows system root must be an absolute path");
8
+ return join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
9
+ }
10
+ function runPowerShell(script, path) {
11
+ return execFileSync(powershellPath(), ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script, path], {
12
+ encoding: "utf8",
13
+ stdio: ["ignore", "pipe", "ignore"],
14
+ timeout: 10_000,
15
+ windowsHide: true,
16
+ }).trim();
17
+ }
18
+ export function hardenWindowsPath(path, directory) {
19
+ if (process.platform !== "win32")
20
+ return;
21
+ const inheritance = directory ? "ContainerInherit, ObjectInherit" : "None";
22
+ runPowerShell(`$ErrorActionPreference='Stop'; $p=$args[0]; $me=[Security.Principal.WindowsIdentity]::GetCurrent(); $acl=Get-Acl -LiteralPath $p; $acl.SetAccessRuleProtection($true,$false); foreach($rule in @($acl.Access)){[void]$acl.RemoveAccessRuleSpecific($rule)}; $acl.SetOwner($me.User); $inherit=[Security.AccessControl.InheritanceFlags]'${inheritance}'; $prop=[Security.AccessControl.PropagationFlags]::None; $allow=[Security.AccessControl.AccessControlType]::Allow; foreach($sid in @($me.User,(New-Object Security.Principal.SecurityIdentifier('S-1-5-18')),(New-Object Security.Principal.SecurityIdentifier('S-1-5-32-544')))){ $rule=New-Object Security.AccessControl.FileSystemAccessRule($sid,[Security.AccessControl.FileSystemRights]::FullControl,$inherit,$prop,$allow); $acl.AddAccessRule($rule) }; Set-Acl -LiteralPath $p -AclObject $acl`, path);
23
+ }
24
+ export function assertWindowsPathPrivate(path) {
25
+ if (process.platform !== "win32")
26
+ return;
27
+ const output = runPowerShell(`$ErrorActionPreference='Stop'; $p=$args[0]; $me=[Security.Principal.WindowsIdentity]::GetCurrent().User.Value; $trusted=@($me,'S-1-5-18','S-1-5-32-544'); $acl=Get-Acl -LiteralPath $p; $owner=(New-Object Security.Principal.NTAccount($acl.Owner)).Translate([Security.Principal.SecurityIdentifier]).Value; $unsafe=0; foreach($rule in @($acl.Access)){ if($rule.AccessControlType -eq [Security.AccessControl.AccessControlType]::Allow){ $sid=$rule.IdentityReference.Translate([Security.Principal.SecurityIdentifier]).Value; if($trusted -notcontains $sid){$unsafe++} } }; [pscustomobject]@{owner=$owner;current=$me;unsafe=$unsafe}|ConvertTo-Json -Compress`, path);
28
+ const parsed = JSON.parse(output);
29
+ if (!isObjectRecord(parsed) ||
30
+ parsed.owner !== parsed.current ||
31
+ typeof parsed.unsafe !== "number" ||
32
+ parsed.unsafe !== 0) {
33
+ throw new Error(`Windows path is not private to the current user: ${path}`);
34
+ }
35
+ }
36
+ export function assertWindowsPathAncestorsTrusted(path) {
37
+ if (process.platform !== "win32")
38
+ return;
39
+ const output = runPowerShell(`$ErrorActionPreference='Stop'; $p=$args[0]; $me=[Security.Principal.WindowsIdentity]::GetCurrent().User.Value; $trusted=@($me,'S-1-5-18','S-1-5-32-544','S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464'); $danger=[Security.AccessControl.FileSystemRights]::Write -bor [Security.AccessControl.FileSystemRights]::Modify -bor [Security.AccessControl.FileSystemRights]::FullControl -bor [Security.AccessControl.FileSystemRights]::ChangePermissions -bor [Security.AccessControl.FileSystemRights]::TakeOwnership -bor [Security.AccessControl.FileSystemRights]::Delete -bor [Security.AccessControl.FileSystemRights]::DeleteSubdirectoriesAndFiles -bor [Security.AccessControl.FileSystemRights]::CreateFiles -bor [Security.AccessControl.FileSystemRights]::CreateDirectories; $unsafe=0; $item=Get-Item -LiteralPath $p -Force; while($null -ne $item){ $acl=Get-Acl -LiteralPath $item.FullName; $owner=(New-Object Security.Principal.NTAccount($acl.Owner)).Translate([Security.Principal.SecurityIdentifier]).Value; if($trusted -notcontains $owner){$unsafe++}; foreach($rule in @($acl.Access)){ if($rule.AccessControlType -eq [Security.AccessControl.AccessControlType]::Allow -and (($rule.FileSystemRights -band $danger) -ne 0)){ $sid=$rule.IdentityReference.Translate([Security.Principal.SecurityIdentifier]).Value; if($trusted -notcontains $sid){$unsafe++} } }; if($item.PSIsContainer){$item=$item.Parent}else{$item=$item.Directory} }; [pscustomobject]@{unsafe=$unsafe}|ConvertTo-Json -Compress`, path);
40
+ const parsed = JSON.parse(output);
41
+ if (!isObjectRecord(parsed) || typeof parsed.unsafe !== "number" || parsed.unsafe !== 0) {
42
+ throw new Error(`Windows path or ancestor is controlled by an untrusted principal: ${path}`);
43
+ }
44
+ }
45
+ export function assertWindowsExecutableTrusted(path) {
46
+ assertWindowsPathAncestorsTrusted(path);
47
+ }
@@ -6,15 +6,20 @@
6
6
 
7
7
  | Variable | Default | Purpose |
8
8
  |----------|---------|---------|
9
- | `PI_KNOWLEDGE_DIR` | host-derived knowledge dir | Override the directory that stores `knowledge.db`, vectors, and model cache parent data for Pi and OMP. Takes precedence over `OMP_KNOWLEDGE_DIR`. |
10
- | `OMP_KNOWLEDGE_DIR` | host-derived knowledge dir | Override the knowledge directory when running under OMP. Used when `PI_KNOWLEDGE_DIR` is not set. |
11
- | `PI_CODING_AGENT_DIR` | unset | Derive the Pi host root from a configured agent directory. Useful for isolated installs and validation. |
12
- | `OMP_CODING_AGENT_DIR` | unset | Derive the OMP host root from a configured agent directory. Used when `PI_CODING_AGENT_DIR` is not set. |
13
- | `OMP_PROFILE` | unset | Treat the current process as OMP-hosted for default path selection. |
14
- | `PI_KNOWLEDGE_MODEL_CACHE_DIR` | `<knowledge-dir>/models` | Override the local Transformers.js model cache directory. |
15
- | `PI_KNOWLEDGE_NODE_PATH` | current Node when possible, then `NODE`, then `node` on `PATH` | Override the Node 22+ executable used by the isolated runtime worker for local models and PDF/DOCX extraction. Useful for Windows OMP packaged runtimes where the host process is not Node. |
9
+ | `PI_KNOWLEDGE_PROFILE` | `default` | Select the process-wide knowledge profile. Profile names are lowercase ASCII keys; named profiles are an advanced isolation feature. |
10
+ | `PI_KNOWLEDGE_PROFILE_ROOT` | `~/.pi-knowledge/profiles` | Override the root used for named profiles. It does not move or merge an existing default profile. |
11
+ | `PI_KNOWLEDGE_DIR` | persisted default mapping or legacy directory | Override storage for the `default` profile only. The directory contains `knowledge.db`, vectors, model/runtime config, and `coverage.json`. Takes precedence over `OMP_KNOWLEDGE_DIR`. |
12
+ | `OMP_KNOWLEDGE_DIR` | unset | Override default-profile storage when `PI_KNOWLEDGE_DIR` is not set. Named profiles reject both storage overrides. |
13
+ | `PI_CODING_AGENT_DIR` | unset | Candidate used only when first claiming the default profile from an existing host-derived knowledge directory. |
14
+ | `OMP_CODING_AGENT_DIR` | unset | OMP candidate used only when first claiming the default profile. |
15
+ | `OMP_PROFILE` | unset | Retained for host compatibility; profile selection uses `PI_KNOWLEDGE_PROFILE`. |
16
+ | `PI_KNOWLEDGE_RUNTIME_DIR` | per-user private runtime directory | Advanced override for Unix daemon socket placement. The directory must be owner-only. |
17
+ | `PI_KNOWLEDGE_MODEL_CACHE_DIR` | `<profile-storage>/models` | Override the local Transformers.js model cache directory. |
18
+ | `PI_KNOWLEDGE_NODE_PATH` | persisted profile runtime, then worker discovery | Override the Node 22+ executable used by the isolated model/document worker. Daemon startup itself accepts only the current trusted Node runtime or an explicit path persisted by `knowledge_configure`. |
16
19
 
17
- Default data storage is `~/.pi/knowledge` under Pi and `~/.omp/knowledge` under OMP. For the default home OMP root, `pi-knowledge` preserves an existing legacy `~/.pi/knowledge` directory when `~/.omp/knowledge` does not exist, so existing Pi knowledge bases remain visible during migration.
20
+ The zero-configuration path is the `default` profile. On first use, `~/.pi-knowledge/profiles.json` atomically records one canonical default storage directory. A single existing Pi/OMP legacy database is adopted in place; multiple distinct legacy databases fail closed until `PI_KNOWLEDGE_DIR` selects one. Named profiles use `~/.pi-knowledge/profiles/<name>` and never fall back to default.
21
+
22
+ Each profile has one long-lived daemon that owns its SQLite handle, vectors, model worker, mutations, watchers, and `coverage.json`. Pi/OMP sessions connect to that daemon and do not stop it on session shutdown. Use `pi-knowledge-daemon start|status|stop [--profile <name>]` for explicit lifecycle control.
18
23
 
19
24
  ## Embeddings
20
25
 
@@ -86,7 +91,7 @@ API embedding failures intentionally surface by default. Silent fallback can hid
86
91
  | `PI_KNOWLEDGE_DEEP_RERANK_CANDIDATES` | profile default | Override how many filtered candidates `deep` mode sends to the reranker. Clamped to 5-100. |
87
92
  | `PI_KNOWLEDGE_DEEP_RERANK_TOPK_MULTIPLIER` | profile default | Override deep rerank top-k multiplier relative to the effective result limit. Clamped to 1-10. |
88
93
 
89
- Search diagnostics include result provenance and applied search tuning in both text output and structured `details`: selected profile, effective limit, snippet length, hybrid threshold, global candidate limit, per-KB retrieval limit, retrieved/threshold-passed/eligibility-passed/metadata-passed/diversity candidate counts, global-pool truncation, chunk id, chunk hash, match reason, indexed timestamp, stale flag, and source mtime when the original source file is available. This provenance is stored in SQLite and derived from indexed source metadata; it does not create or modify files in the indexed project.
94
+ Search diagnostics include result provenance and applied search tuning in both text output and structured `details`: selected profile, effective limit, snippet length, hybrid threshold, global candidate limit, per-KB retrieval limit, retrieved/threshold-passed/eligibility-passed/metadata-passed/diversity candidate counts, global-pool truncation, chunk id, chunk hash, match reason, persisted indexed timestamp, and stale flag derived from persisted KB status. Query-time search reads indexed data only and does not stat retained source paths.
90
95
 
91
96
  `knowledge_search` supports `file_type`, substring `path_pattern`, `profile`, integer `limit` from 1 to 50, and non-negative integer `offset`. `offset + limit` cannot exceed the 800-candidate global search window. Each KB retrieves up to the profile-derived candidate limit, then merged results are ranked, filtered, and globally capped before deep reranking, adaptive expansion, or diversity. Search profiles tune result count, snippets, hybrid strictness, candidate breadth, adaptive context, and deep rerank breadth at runtime. `auto` chooses from query shape, mode, and KB source type; explicit tool parameters win over env overrides, env overrides win over profile defaults, and profile defaults win over built-in compatibility values. `hybrid` mode remains lexical-anchored to prevent low-evidence semantic false positives; use `semantic` for pure vector search, or `semantic_hybrid` when weak lexical overlap should not block vector-backed weighted fusion. `adaptive` uses bounded same-file context expansion; when AST metadata is present it can prefer same-parent/sibling chunks without claiming caller/callee graph semantics.
92
97
 
@@ -98,6 +103,31 @@ Empty `knowledge_search` responses always include structured `details.miss` with
98
103
 
99
104
  `knowledge_symbol_search` uses a lightweight symbol index stored in `knowledge.db`. It is rebuilt during `knowledge_add`, `knowledge_update`, and `knowledge_import`, and can find AST-backed methods/functions/classes/interfaces/types/variables for supported code files, route-like handlers, Markdown headings, config keys, and environment variables. It is not a full LSP or code graph; it does not answer caller/callee or rename-safety questions. Empty lookups distinguish missing KBs, unavailable KBs, empty symbol metadata, exact-name misses, metadata filters, pagination, and ordinary no-match results. If the symbol index itself is empty, use `knowledge_update` for source-backed KBs; imported portable KBs and inline text KBs do not retain an active source path and must be re-imported or re-added from the original content.
100
105
 
106
+ ### Standalone MCP server
107
+
108
+ `pi-knowledge-mcp [--profile <name>]` connects to the selected daemon. It uses stdio by default; `--transport http` starts an authenticated Streamable HTTP endpoint for multiple local clients. Both transports are read-only by default and list only indexed search, symbol search, and show. These paths do not rescan retained source directories.
109
+
110
+ | Option or variable | Default | Purpose |
111
+ |--------------------|---------|---------|
112
+ | `--transport stdio\|http` | `stdio` | Select a per-client stdio adapter or a shared local HTTP process. |
113
+ | `PI_KNOWLEDGE_MCP_HTTP_TOKEN` | unset | Required only for HTTP. Must contain 32–512 visible ASCII characters and is accepted as a bearer token. Keep it out of arguments, source control, logs, and shared config. |
114
+ | `--host` | `127.0.0.1` | HTTP bind host. Only `127.0.0.1`, `::1`, and `localhost` are accepted. |
115
+ | `--port` | `3210` | HTTP TCP port; `0` requests an ephemeral port. |
116
+ | `--endpoint` | `/mcp` | One absolute HTTP endpoint path without query or fragment. |
117
+ | `--allow-origin <origin>` | none | Repeatable exact HTTP(S) supplied origin. Requests without `Origin` are allowed; an unlisted supplied origin is rejected. This validation does not enable browser CORS/preflight. |
118
+
119
+ HTTP mode does not provide TLS, OAuth, or remote binding. It is a same-machine transport; use stdio when one client owns the adapter. For several local clients, start one persistent HTTP adapter and give each client the same loopback URL and token. Separate endpoints are required when clients need different capability sets.
120
+
121
+ - `--allow-root <canonical-dir>` may be repeated; it enables `knowledge_plan` and authorizes local source/import/export paths inside those roots. Roots must be current-user-owned and not group/world-writable on Unix, or private by Windows ACL. The adapter canonicalizes arguments for early rejection; the daemon independently rebinds the root inode and revalidates containment at operation time.
122
+ - `--allow-network` authorizes public URL sources; the normal private-network and redirect policy still applies.
123
+ - `--allow-write` exposes add/update/import/export, subject to the root/network capabilities above.
124
+ - `--allow-admin` exposes live status/doctor diagnostics plus configure/remove/clear. Status and doctor can rescan every retained source, so they are not exposed to the capability-free MCP surface. Tool confirmation remains required for destructive calls, but confirmation is not authorization.
125
+
126
+ The server supports legacy `initialize` protocols `2025-11-25`, `2025-06-18`, and `2025-03-26`, plus modern `2026-07-28` `server/discover`, tool progress, and cancellation. Stdio uses newline-delimited JSON-RPC. HTTP uses POST with JSON or request-scoped SSE, mandatory modern mirrored headers, negotiated legacy session IDs, and DELETE session termination; GET intentionally returns `405`. Valid tool execution/cancellation failures use an MCP tool result with `isError: true`; malformed JSON-RPC requests remain protocol errors.
127
+
128
+ Client shutdown cancels adapter requests without stopping the profile daemon. HTTP shutdown stops admission, aborts active session work, drains bounded operations, and is idempotent. See [MCP Client Setup](mcp-clients.md) for npm installation, Claude Code, Codex, Cursor, VS Code Copilot, capability, profile, upgrade, and token examples.
129
+
130
+
101
131
  ## Test and Release Fixtures
102
132
 
103
133
  | Variable | Default | Purpose |
@@ -0,0 +1,302 @@
1
+ # Profile-scoped Daemon Architecture
2
+
3
+ ## 狀態
4
+
5
+ 實作規格。此文件定義 pi-knowledge 從 extension 內嵌 `KnowledgeEngine` 遷移到 profile-scoped singleton daemon 的完整切換契約。
6
+
7
+ ## 目標
8
+
9
+ - 一般使用者零設定使用 `default` profile;工具參數不暴露 profile 複雜度。
10
+ - 一個 profile 可包含多個 knowledge bases,但只擁有一個 storage domain 與一個常駐 daemon。
11
+ - Pi、OMP、CLI、MCP 與其他 agent 都連到同一個 profile daemon;client 不直接開啟 `knowledge.db` 或 vector files。
12
+ - 進階使用者可明確選擇 named profile,取得完全隔離的 DB、vectors、config、watchers、daemon 與 coverage snapshot。
13
+ - daemon 可由使用者獨立啟動,也可由 extension/MCP client 以 `ensure` 語意自動啟動;啟動它的 client 離開不會停止 daemon。
14
+ - issue #25 的 `coverage.json` 由 profile daemon 在 mutation 完成點唯一產生。
15
+
16
+ ## 核心模型
17
+
18
+ ### Profile
19
+
20
+ Profile 是 storage/runtime domain,不是單一 KB。每個 profile 包含:
21
+
22
+ - canonical storage directory
23
+ - `knowledge.db`
24
+ - `vectors/` 與 model/runtime config
25
+ - watcher state
26
+ - daemon runtime manifest、endpoint 與 singleton ownership
27
+ - `coverage.json`
28
+
29
+ Profile 名稱只供選擇與顯示;singleton identity 由 canonical storage directory 的 SHA-256 digest 決定。名稱必須是已 canonicalize 的 ASCII lowercase key,符合 `[a-z0-9][a-z0-9_-]{0,62}`;拒絕 trailing dot/space、Windows reserved device basename、case-fold collision 與不能 round-trip 的名稱。工具中的既有 search tuning `profile` 不改名;knowledge profile 在程序層以 `PI_KNOWLEDGE_PROFILE` 或 CLI `--profile` 選擇,避免同名參數衝突。Named profile directory 建立時不得跟隨 symlink,建立後必須 realpath 並驗證仍位於 owner-verified profile root 內。
30
+
31
+ ### Default-first 行為
32
+
33
+ - 未指定 profile 時永遠選擇 `default`。
34
+ - extension 與 MCP tool schema 不新增必填 profile 欄位。
35
+ - named profile 只由進階使用者透過程序設定選擇;找不到 named profile 時建立其隔離 storage directory,不 fallback 到 default。
36
+ - 一個 daemon process 只管理一個 profile;不同 profile 可同時執行。
37
+
38
+ ### Default storage migration
39
+
40
+ Default 必須跨 Pi、OMP 與 MCP 穩定解析到同一 storage directory,同時保留現有資料:
41
+
42
+ 1. `PI_KNOWLEDGE_DIR`、其次 `OMP_KNOWLEDGE_DIR` 明確覆蓋 default storage;explicit override 可位於 profile root 外,但仍須 canonicalize 與驗證 owner。
43
+ 2. 沒有覆蓋時,讀取 `~/.pi-knowledge/profiles.json` 的 persisted default mapping。
44
+ 3. 首次建立 mapping 時,先依現行 precedence 解析 `PI_CODING_AGENT_DIR`、`OMP_CODING_AGENT_DIR` 所代表的 host-derived knowledge directory,再連同 legacy `~/.pi/knowledge`、`~/.omp/knowledge` 一起 canonicalize、去重並檢查:
45
+ - 只有一個 candidate 含 `knowledge.db`:採用該目錄,不搬移資料。
46
+ - 多個 candidate 解析為同一 canonical path:採用該目錄。
47
+ - 多個不同 candidate 各有 `knowledge.db`:拒絕猜測,回報需用 `PI_KNOWLEDGE_DIR` 明確選擇。
48
+ - 都沒有 DB:新 default 使用 `~/.pi-knowledge/profiles/default`。
49
+ 4. Named profiles 使用 `~/.pi-knowledge/profiles/<canonical-name>`,可由 `PI_KNOWLEDGE_PROFILE_ROOT` 覆蓋 profile root。
50
+ 5. Registry 以 owner-only tmp + rename 原子寫入;不得匯出、移動或合併現有 KB。新 profile directory mode 為 `0700`;重用 legacy directory 前驗證 owner,對 group/other writable 目錄拒絕啟動並提供明確修復訊息。
51
+
52
+ ## Daemon ownership
53
+
54
+ Profile daemon 是以下資源的唯一 runtime owner:
55
+
56
+ - `KnowledgeEngine`
57
+ - SQLite connection
58
+ - vector mutation
59
+ - model worker lifecycle
60
+ - file watchers 與 polling fallback
61
+ - mutation queue/guards
62
+ - profile coverage snapshot
63
+
64
+ Client 不得在 daemon 無法連線時 fallback 建立本地 `KnowledgeEngine`。失敗必須回報 actionable error,否則會重新引入第二個 writer。
65
+
66
+ Direct `KnowledgeEngine` construction 保留給 unit/e2e/bench 與內部 daemon service,不是 extension/MCP production path。
67
+
68
+ ## Singleton 與 runtime discovery
69
+
70
+ 每個 profile storage directory 下建立 owner-verified、不可跟隨 symlink 的 `.runtime/`(mode `0700`):
71
+
72
+ - `daemon.json`: runtime manifest,以 exclusive `0600` temp file + fsync + rename 發布
73
+ - `daemon.lock`: 完整 daemon owner JSON,以 exclusive `0600` temp file + fsync + hard-link no-replace claim 發布
74
+
75
+ Unix endpoint 放在 owner-verified、mode `0700` 的 per-user runtime directory,名稱包含 profile id 與每次啟動的 256-bit random component,避免 socket path 長度與 predictable-name race;Windows named pipe 同樣使用 random component、token authentication與僅本機模式。Endpoint 只能從受保護 manifest 發現。Manifest 至少包含:
76
+
77
+ - protocol version
78
+ - profile name/id
79
+ - canonical storage directory
80
+ - daemon instance id、PID、started timestamp
81
+ - random endpoint
82
+ - package/build identity
83
+ - 256-bit auth token
84
+ - watcher enabled state
85
+
86
+ Daemon startup:
87
+
88
+ 1. 先產生 instance id/random endpoint與完整 owner JSON(PID、instance id、endpoint、started timestamp),再以 `0600` exclusive temp file寫入並 fsync,最後用 hard link把完整檔案 no-replace claim為 `daemon.lock`。Target 已存在時 claim必須失敗,不得覆蓋。
89
+ 2. 取得完整 lock後立即建立/bind random endpoint;完成 bind後才初始化 engine。Application handshake尚未 ready時,raw socket listener仍代表 owner存活,其他 launcher必須等待或回報 busy。
90
+ 3. lock已存在時,即使 manifest尚未發布,也能直接從完整 `daemon.lock`讀取 instance/PID/endpoint;先嘗試 authenticated handshake或 raw connect。
91
+ 4. heartbeat只供診斷,永遠不能授權 takeover。Owner PID仍存在、PID identity無法可靠確認、raw endpoint可連線或 lock identity在檢查期間改變時,一律拒絕接管並回報 busy/unresponsive。
92
+ 5. 只有 endpoint明確沒有 listener、owner PID已不存在、`daemon.lock`/manifest(若存在)的 instance id在二次讀取後仍完全一致,才能 atomic rename舊 lock後清理該 instance記錄。Crash發生在 manifest發布前仍可由 owner record安全恢復;stale random socket保守保留,避免 unlink/bind race移除外來 live endpoint。
93
+ 6. `EADDRINUSE`或未通過認證的 foreign endpoint一律 fail closed;daemon不得因 handshake失敗就 unlink不屬於自己的 socket。
94
+ 7. graceful shutdown關閉 admission、watchers與 server,取消並等待 bounded in-flight work。只有 coordinator確認所有使用 DB/vector handles的 operation已 settle,才能 dispose engine並移除 instance-matched artifacts。
95
+
96
+ PID、heartbeat 或檔案存在本身都不構成 liveness 證明。Client 只有在完成 authenticated protocol handshake 後才把 daemon 視為 ready。
97
+
98
+ ## Local RPC contract
99
+
100
+ - JSON Lines request/response protocol over local socket/pipe。
101
+ - protocol version 從 1 開始;client/server protocol 或 package/build identity 不相容時直接拒絕。
102
+ - 每個 client request 使用唯一 id;連線以受保護 manifest 中的 token 認證,token 不進 argv/log/error。
103
+ - server 可傳送零到多個 bounded progress frames,最後恰好一個 result 或 error frame。
104
+ - client `AbortSignal` 觸發 cancel frame;server 的 `AbortController` 傳入所有長操作,取消必須繼續傳到 model worker。
105
+ - 連線中止也必須取消該 subscriber;coalesced update 由 daemon mutation coordinator 管理 subscriber/progress,只有沒有 subscriber或 daemon shutdown 時才取消底層 operation。
106
+ - model worker protocol 必須支援 cancel frame與 request registry;長迴圈在批次間檢查。無法中斷的單次 native/model call 可延遲到該 call 返回,但不得繼續後續 batch,且語意必須明確。
107
+ - request/frame、connection、in-flight request、queued mutation、progress bytes與 outbound buffer 都設定硬上限;超載直接拒絕,不建立無界 queue。
108
+ - daemon shutdown 在任何 `await` 前停止 admission並 abort controllers,重複 shutdown 共用同一 promise。Grace deadline 到期後先 terminate model worker,使 pending model promises reject,再給 coordinator一個短的 settle deadline;若仍有 operation存活,daemon採 fail-stop:不 close DB、不 dispose live resources、不移除 lock/manifest/socket,直接以非零狀態結束整個 process,讓 OS 回收 handles,下次啟動只在確認舊 PID dead後做 instance-checked recovery。
109
+ - server error 只回傳安全的 message/code,不回傳 stack 或 token。
110
+
111
+ 第一版 RPC operations:
112
+
113
+ - `ping`, `shutdown`, `enable_watchers`
114
+ - `plan`, `configure`
115
+ - `add`, `update`, `remove`, `clear`, `import`, `export`
116
+ - `search`, `symbol_search`, `list`, `status`, `doctor`
117
+
118
+ `configure` 正常由 daemon 執行;但 launcher另提供 startup-light bootstrap config path,不開 DB/engine、不需要 daemon。當 ensure 回報「沒有可信 Node runtime」時,`knowledge_configure` 可用使用者明確提供的 absolute `node_path` 在 client process驗證 Node 22+、owner與路徑,原子寫入該 profile runtime config,再重試 ensure。Bootstrap 禁止 PATH/NODE auto-discovery;未提供明確 path 時回傳 actionable error。其他 tools 不得繞過 daemon。
119
+
120
+ 所有 engine 呼叫都由 daemon service 執行。Watcher callback 也回到同一個 mutation coordinator/service update path,確保 subscriber cancellation、progress、coverage snapshot 與 mutation guard 一致。
121
+
122
+ ## Daemon lifecycle
123
+
124
+ - `ensure`: 先 connect;不可達時使用目前 package `import.meta.url` 解析出的絕對 daemon entry,透過共用、profile-aware Node 22+ resolver 以 argument array、`shell:false`、detached stdio啟動,再等待 authenticated readiness。
125
+ - Source checkout 的 `.ts` entry 使用 `--experimental-strip-types`;published `.js` 不使用。不得從 cwd、shell或 PATH 搜尋 `pi-knowledge-daemon`。
126
+ - Daemon runtime只接受兩類 Node executable:已驗證確為 Node 22+ 的 `process.execPath`,或由 admin 明確設定/profile config持久化的 absolute、owner-verified Node path。Daemon launcher不得採信 `NODE`、`PATH`或自動 discovery candidate;非 Node Pi/OMP host沒有可信 persisted runtime時 fail closed並要求先明確 configure。Model worker可維持既有 discovery,但不能決定 daemon executable。
127
+ - Spawn environment 採 allowlist:profile/storage/runtime/provider必要設定與 credentials;拒絕繼承 `NODE_OPTIONS`、`NODE_PATH` 等 loader injection。Token 不放 argv/environment。
128
+ - `start`: ensure 的 CLI 顯式形式,已啟動時成功回報既有 instance。
129
+ - `run`: foreground daemon,供 service manager 與診斷使用。
130
+ - `status`: 只做 handshake,不啟動 daemon。
131
+ - `stop`: authenticated admin shutdown,等待 server 確認;不得以 PID 猜測直接 kill 正常 daemon。
132
+ - extension session shutdown 只釋放 client state,不停止 daemon。
133
+ - daemon shutdown guard 必須在任何 `await` 前設定,重複 shutdown必須 idempotent。Service先 bounded drain;deadline後 terminate model worker並短暫等待 coordinator。若仍未 settle,整個 daemon fail-stop且不執行競態 cleanup;只有全數 settle才呼叫 `KnowledgeEngine.dispose()`。Engine dispose不得重新無界等待已由 service管理的 operation。
134
+
135
+ ## Watcher contract
136
+
137
+ Watcher 從 extension 移入 daemon:
138
+
139
+ - daemon 啟動時依 profile runtime 設定啟用。
140
+ - client 帶 `PI_KNOWLEDGE_WATCH=true` 連入既有 daemon 時,可呼叫 `enable_watchers`;這是 monotonic enable,不因另一個 client 離開而關閉。
141
+ - add directory KB 後由 daemon 自動建立 watcher。
142
+ - remove/clear 後 daemon 停止對應 watcher。
143
+ - watcher update 使用 service mutation coordinator,不直接呼叫第二個 engine。
144
+ - watcher polling 改為 async、bounded batch、不可重入;不得以同步全目錄 scan 長時間阻塞 daemon endpoint。
145
+ - shutdown 先停止 watcher/timer與新 admission,再 abort/drain requests,最後 engine dispose。
146
+
147
+ ## Extension cutover
148
+
149
+ Root `index.ts` 保持 startup-light:
150
+
151
+ - 不再 runtime import `engine.ts`、SQLite 或 watcher。
152
+ - lazy import daemon client/profile resolver。
153
+ - session start 執行 `ensure`;所有 engine-backed tool、auto-inject、before-agent-start 透過 daemon client。唯一例外是上述 `knowledge_configure` no-runtime bootstrap,它只驗證/持久化明確 Node path並立即重試 ensure,不開 DB或 engine。
154
+ - session shutdown 等待 in-flight ensure 完成後清理 client reference,但不停止 daemon。
155
+ - 不提供 local engine fallback。
156
+
157
+ Public tool descriptions、approval、confirmation、search miss formatting與結構化 `details` 必須保持相容。
158
+
159
+ ## MCP adapter
160
+
161
+ MCP 是 daemon 的 adapter,不是第二個 engine owner:
162
+
163
+ - `pi-knowledge-mcp [--profile <name>]` 預設提供 stdio JSON-RPC;`--transport http` 提供多個本機 agent 可共用的 Streamable HTTP endpoint。
164
+ - adapter 啟動時 ensure profile daemon。MCP process 不開 DB、不啟動 watcher、不載入模型;stdio/HTTP 都轉送到同一 profile daemon。
165
+ - transport-independent protocol core 實作 legacy `2025-11-25`/`2025-06-18`/`2025-03-26` 的 `initialize` 與 modern `2026-07-28` 的 `server/discover`、required per-request `_meta`、typed result,以及 cacheable complete result 必備的 private `ttlMs`/`cacheScope`;兩者都支援 `ping`、`tools/list`、`tools/call`、progress 與 cancellation。
166
+ - tool metadata/schema 與 Pi/OMP extension 共用同一份定義,輸出順序 deterministic。MCP 是新增的外部 client surface,不取代或改變 Pi/OMP hooks。
167
+ - stdio 使用 bounded JSONL;stdin EOF 取消 adapter in-flight requests 並退出,但不停止 profile daemon。
168
+ - HTTP 只允許 `127.0.0.1`、`::1` 或 `localhost`,且強制從 `PI_KNOWLEDGE_MCP_HTTP_TOKEN` 取得 32–512 visible ASCII bearer token。 supplied `Origin` 必須等於 endpoint own origin 或 explicit `--allow-origin`;token 不進 argv/log。
169
+ - HTTP modern request 驗證 required metadata 與 `MCP-Protocol-Version`、`Mcp-Method`、tool call `Mcp-Name` mirrored headers;tool call 使用 request-scoped SSE 回報 progress/result,client disconnect 取消 modern work。
170
+ - HTTP 保留 negotiated legacy session ID、idle/session bounds、DELETE session termination;GET 回 `405`,不建立 server-initiated event stream。Request/body/output queue/concurrency 全部 bounded。
171
+ - HTTP shutdown 先停止 admission,再 abort sessions/requests、bounded drain/close connections;重複或 concurrent close 必須 idempotent,且不停止 profile daemon。
172
+ - MCP adapter預設只暴露不讀取 retained source的已索引 `search`、`symbol_search`、`show`;`knowledge_plan`不屬於預設 read-only,因為它會掃描任意來源。Search provenance只使用已索引時間與持久化 KB status,不在 query path讀取 source mtime。
173
+ - `--allow-root <canonical-dir>`(可重複)提供 owner-verified local source/import/export scope並開啟 `plan`;所有 local path在每次操作時 realpath並驗證仍位於 allowed root。`--allow-network`另行開啟 URL source/update,套用 private-network policy。`--allow-write`開啟 mutation,但 local/network mutation仍必須同時具備對應 root/network capability。`--allow-admin`另行開啟會掃描 retained source的 status/doctor,以及 configure/remove/clear。
174
+ - Pi/OMP host 的 approval metadata不能被視為 MCP authorization;`confirm` 也只防誤操作。
175
+
176
+ 不新增 production dependency;stdio 與 HTTP 使用 Node runtime primitives。遠端 bind、TLS、OAuth、MCP resources/prompts 不在本階段範圍,不能把 loopback HTTP 文件化成跨機器服務。
177
+
178
+ ## Coverage snapshot(issue #25)
179
+
180
+ Daemon 在 startup reconcile,以及 add/update/remove/clear/import 成功後,原子重寫 `<profile-storage>/coverage.json`:
181
+
182
+ ```json
183
+ {
184
+ "schema_version": 1,
185
+ "generated_at": 1763050000000,
186
+ "profile": "default",
187
+ "kbs": [
188
+ {
189
+ "name": "repo",
190
+ "source_type": "directory",
191
+ "source_path": "/work/repo",
192
+ "exclude_paths": ["dist"],
193
+ "file_count": 42,
194
+ "chunk_count": 812,
195
+ "updated_at": 1763049871000,
196
+ "status": "ready"
197
+ }
198
+ ]
199
+ }
200
+ ```
201
+
202
+ - `kbs` 以 `name`、再以內部 KB ID 的 Unicode code-unit順序排序;順序不受 OS locale影響。`name` 在同一 profile內唯一,也是 `knowledge_update`等工具可使用的 selector。
203
+ - `source_type` 的封閉集合為 `directory | file | url | text`。`source_path` 對 directory/file 是建立或更新時解析的本機絕對路徑,對 URL 是 URL;inline text/import 為 `null`。Consumer 必須把 `null` 視為 scope-agnostic(永遠涵蓋),不能解讀為不涵蓋任何 path。
204
+ - `exclude_paths` 只對 directory source有意義;值使用 `/`、移除前後 `/`,並相對於 source root。值 `archive` 只匹配 `archive` 本身與其子樹,不匹配 `archived_reports`;空值不輸出。
205
+ - `file_count`、`chunk_count`是最近一次成功持久化的 KB計數。`updated_at`是最近一次完整成功 add/update/import 的 Unix epoch毫秒;indexing、error、cancel或其他 row bookkeeping 不得推進此時間。它仍不是 per-file freshness watermark。
206
+ - 既有 v5 database 升級時,daemon 依序以最近保留的成功 indexing job、現存 chunk 的最晚 `indexed_at`、最後 `0` 做保守回填;不得用會被 status bookkeeping 推進的舊 row `updated_at`。`0` 表示沒有可證明的成功時間,consumer 應保持 silent/fail-open。
207
+ - `status` 的封閉集合為 `ready | indexing | error | stale`。`generated_at`是 daemon產生本次 point-in-time snapshot的 Unix epoch毫秒。
208
+ - clear 保留檔案並寫入空 `kbs`。
209
+ - snapshot 與 temp file 都使用 `0600`;tmp + fsync + rename,consumer 永遠只看到完整舊版或完整新版。
210
+ - snapshot error 不回滾也不改變已成功的 mutation;daemon 保存最近 snapshot error供 status/manifest診斷並寫不含敏感 path的 stderr。Watcher背景更新也必須同步更新或清除 manifest診斷。
211
+ - snapshot可能包含本機絕對 path或 URL,屬敏感的 advisory point-in-time scope/status;它不是 per-file coverage/freshness authority。
212
+ - consumer必須處理 absent/stale/version mismatch,且不得修改此檔控制 daemon。
213
+
214
+ ## Runtime configuration ownership
215
+
216
+ Daemon process 以 profile storage directory 設定自己的 `PI_KNOWLEDGE_DIR`,讓既有 model cache、runtime config 與 worker discovery 都落在正確 profile。
217
+
218
+ Engine-affecting環境設定由啟動中的 daemon 擁有。Handshake 回報 runtime configuration signature;client 與現有 daemon 設定不一致時不得假裝新設定已套用,應回報需要 restart/reconfigure。`PI_KNOWLEDGE_WATCH=true` 例外,可透過 monotonic enable 即時開啟。
219
+
220
+ ## 安全邊界
221
+
222
+ - endpoint 僅限本機;Unix runtime parent/profile runtime mode `0700`,socket、manifest、token與 coverage 使用 user-only 權限;所有 runtime artifact 在使用/刪除前做 `lstat`、owner、symlink 與 instance-id 驗證。
223
+ - auth token 每次 daemon instance 以 crypto 產生至少 256 bits,輪替後舊 token 失效,不寫 log、argv、錯誤或 coverage snapshot。同 UID process 視為本機 trust boundary,但 MCP adapter仍以 read/write/admin launch capability限制 agent surface。
224
+ - RPC 不接受任意方法名稱映射或動態 import;方法 allowlist與輸入 schema在 daemon boundary 再驗證。
225
+ - destructive tool confirmation 只防誤操作,不代表授權;MCP mutation/admin 必須另由 launch capability開啟。
226
+ - direct file、URL、import、inline text與 export path 都有 byte/count/time/redirect bounds。URL 一律拒絕 loopback/private/link-local與 redirect 逃逸;`--allow-network` 只授權 public URL operation,不會放寬此限制。Export 預設拒絕 symlink escape與非預期覆寫。
227
+
228
+ ## Clean cutover
229
+
230
+ - production extension 一次切換到 daemon client;不保留 local-engine compatibility mode。
231
+ - 舊 storage 透過 default registry 指向原目錄,不複製資料。
232
+ - watcher ownership 一次移入 daemon;extension 移除 watcher lifecycle。
233
+ - package 提供 `pi-knowledge-daemon` 與 `pi-knowledge-mcp` bin entry。
234
+ - `knowledge_status` 顯示 active profile、daemon instance/protocol、storage path、watcher count與 snapshot warning。
235
+
236
+ ## 實作階段與 gates
237
+
238
+ ### Phase A:Profile 與 daemon core
239
+
240
+ 交付:profile resolver/registry、manifest、singleton、RPC framing、daemon service/client/CLI。
241
+
242
+ Gate:
243
+
244
+ - default legacy/host-derived resolution、named isolation、invalid/ambiguous/case-fold/reserved profile 測試。
245
+ - concurrent ensure 只產生一個 daemon。
246
+ - live-but-unresponsive owner不接管;pre-manifest crash可由完整 atomic owner record恢復;dead owner stale lock/socket做 instance-checked recovery。
247
+ - auth、protocol/build mismatch、foreign endpoint、oversized frame、overload與disconnect cancellation。
248
+ - model-worker cancellation與 coalesced update 多 subscriber progress/cancel。
249
+ - trusted/persisted Node、非 Node host fail-closed、Windows 空白 path、spawn failure與 readiness timeout。
250
+ - fresh non-Node host無 persisted config時,client-side explicit configure-node → ensure成功,且 bootstrap全程不開 DB/engine。
251
+ - repeated/concurrent shutdown idempotence、cooperative bounded drain,以及永不回應 native call觸發不清理 live resources的 fail-stop gate。
252
+ - 獨立 reviewer 完成 correctness/security/lifecycle review,blocking finding 歸零。
253
+
254
+ ### Phase B:Extension 與 MCP cutover
255
+
256
+ 交付:shared tool definitions、extension daemon client、watcher daemon ownership、MCP shared protocol core、stdio 與 loopback Streamable HTTP。
257
+
258
+ Gate:
259
+
260
+ - 所有 public tools contract 保持。
261
+ - startup/shutdown race、agent-start、auto-inject、progress/cancellation。
262
+ - MCP modern discover/meta/result 與三個 legacy initialize 版本;stdio list/call/progress/cancel;HTTP bearer/origin/mirrored headers、JSON/SSE、legacy session/DELETE、disconnect cancellation。
263
+ - read/write/admin capability filtering 在兩個 transports 一致。
264
+ - HTTP non-loopback/weak token fail closed;request/body/session/concurrency/output bounded;repeated/concurrent shutdown idempotent。
265
+ - extension 不再 import/construct production `KnowledgeEngine`,Pi/OMP hooks 行為不因 MCP transport 改變。
266
+ - 獨立 reviewer 完成 compatibility/security/lifecycle review,blocking finding 歸零。
267
+
268
+ ### Phase C:Coverage snapshot
269
+
270
+ 交付:versioned atomic snapshot、mutation/startup hooks、status warning、文件。
271
+
272
+ Gate:
273
+
274
+ - shape、exclude paths、source type、clear empty list。
275
+ - write/rename failure不影響 mutation。
276
+ - startup reconcile。
277
+ - 只有 daemon service production path 寫入。
278
+ - 獨立 reviewer 完成 data contract/failure semantics review,blocking finding 歸零。
279
+
280
+ ### Final gate
281
+
282
+ - `npm run check`
283
+ - `npm run typecheck`
284
+ - `npm test`
285
+ - `npm run test:e2e`,明列未設定 PDF/DOCX fixture時的 skipped coverage
286
+ - 設定 `PI_KNOWLEDGE_E2E_PDF` 與 `PI_KNOWLEDGE_E2E_DOCX` 的 release-grade e2e(fixture 可用時)
287
+ - actual detached daemon CLI smoke with concurrent clients
288
+ - actual packed MCP stdio 與 authenticated loopback HTTP smoke;兩者都實際 list/call 並 clean shutdown
289
+ - `node --experimental-strip-types -e "import('./index.ts')"`
290
+ - `npm run build`
291
+ - `npm pack --dry-run`
292
+ - 將 packed tarball 安裝到 temp project,實際啟動兩個 bin並驗證 native dependency resolution
293
+ - Pi/OMP dogfood when runtimes are available
294
+ - independent final quality/security/async-lifecycle review
295
+
296
+ ## 非目標
297
+
298
+ - 跨機器 daemon、遠端 network listener或多使用者服務。
299
+ - default 跨 profile 搜尋。
300
+ - 自動合併兩個 legacy DB。
301
+ - sidecar 作為 mutation input或 per-file manifest。
302
+ - MCP resources/prompts、遠端 HTTP bind、TLS termination、OAuth或多使用者服務。