# PSMR Adapter SDK Specification v0.1 **版本：** v0.1 **作者：** Neo.K **機構：** EveMissLab **日期：** 2026-09-15 **公司：** 一言諾科技有限公司 --- ## 0. 文件目的 PSMR 必須能接受不同來源。 但核心 Runtime 不應內建所有解析器。 因此定義 Adapter SDK。 Adapter 的責任是： $$ A_k : X_k \rightarrow E_k $$ 即將外部來源轉成 Evidence Artifact 與 Semantic Objects。 --- # 一、Adapter 類型 第一版定義： ```text source git runtime schema documentation intent artifact_observation external_analyzer ``` --- # 二、Adapter Manifest 每個 Adapter 必須提供： ```json { "adapter_id": "source.python", "version": "0.1.0", "adapter_type": "source", "input_kinds": ["file", "directory"], "output_artifact_types": ["source_file"], "required_capabilities": ["filesystem-read"], "side_effects": [], "determinism": "deterministic" } ``` --- # 三、Adapter Lifecycle ```text discover probe ingest normalize emit close ``` --- # 四、Probe Probe 不應直接完整解析。 它只回答： ```text can_handle confidence detected_type estimated_cost required_capabilities ``` --- # 五、Ingest Request ```json { "adapter_id": "source.python", "source": { "kind": "path", "value": "src/" }, "policy": {}, "capability_refs": [] } ``` --- # 六、Ingest Result ```json { "artifacts": [], "semantic_objects": [], "unknowns": [], "conflicts": [], "warnings": [], "metrics": {} } ``` --- # 七、Evidence Requirement Adapter 不能只輸出結論。 至少應保留： ```text origin locator version observation method content identity authority uncertainty ``` --- # 八、Source Adapter Source Adapter 可以輸出： ```text source artifact syntax structure symbol index import facts source spans ``` 但高階 CISG 可交給 PBSOI Operator Stack。 Adapter 與 Analyzer 應分工： $$ \boxed{ \text{Adapter observes} \neq \text{Operator reasons} } $$ --- # 九、Git Adapter 輸出： ```text repository identity revision identity parent relation changed files commit metadata ``` Git Adapter 不應自行產生 Semantic Diff。 Semantic Diff 是 Operator。 --- # 十、Runtime Adapter 接受： ```text trace log profile runtime event stream ``` 並產生 observed runtime evidence。 必須保留： ```text timestamp process/thread identity event source sampling method loss/truncation information ``` --- # 十一、Schema Adapter 接受： ```text OpenAPI JSON Schema GraphQL protobuf database schema package manifest ``` 輸出： ```text type objects contract objects boundary objects compatibility facts ``` --- # 十二、Documentation Adapter 文件內容預設： ```text authority = claimed ``` 不得標記成 implementation observed。 --- # 十三、Intent Adapter 自然語言 Intent 可產生： ```text goal constraint non-goal acceptance criterion open question ``` 但預設： ```text status = claimed authority = intent ``` --- # 十四、Artifact Observation Adapter 此 Adapter 是「無 source」工作流的通用接口。 PSMR 核心不定義具體觀測方法。 只定義： > 外部合法、授權工具可以輸入結構化 evidence。 Manifest 可聲明： ```text input_kind = compiled_artifact observation_method = external ``` --- # 十五、External Analyzer Adapter 若外部工具已輸出： ```text call graph dependency graph security findings type data ``` PSMR 可透過 Adapter 引入。 但必須保留： ```text tool identity tool version tool confidence original finding identity ``` --- # 十六、Authority Mapping Adapter 必須映射 authority。 例如： ```text source parser -> implementation observed runtime trace -> runtime observed README -> author claimed LLM extractor -> inferred external analyzer -> external tool claim ``` --- # 十七、Uncertainty Adapter 應明確輸出： ```text complete partial sampled truncated ambiguous unsupported ``` --- # 十八、Bounded Analysis Adapter 必須支援 budget。 例如： ```json { "max_files": 3000, "max_bytes_per_file": 400000, "max_events": 1000000 } ``` 超出時： ```text truncated = true ``` 並產生 Unknown / Warning。 --- # 十九、Capability Adapter 所需 capability 必須最小化。 例如 Source Adapter 通常只需要： ```text filesystem-read ``` 不能因為「方便」就要求： ```text filesystem-write process-execute network ``` --- # 二十、Sandbox 第三方 Adapter 預設應執行於受限 sandbox。 可限制： ```text filesystem scope network process memory time output size ``` --- # 二十一、Deterministic Adapter 若 Adapter 標記 deterministic： $$ A(X,P) = E $$ 在相同： ```text input bytes adapter version policy ``` 下 canonical result 必須一致。 --- # 二十二、Adapter Cache Key： $$ K_A = H( \text{adapter version}, \text{input identity}, \text{policy} ) $$ --- # 二十三、Incremental Adapter Adapter 可聲明： ```text supports_incremental = true ``` 並接受： ```text previous_result changed_regions ``` --- # 二十四、Streaming Adapter Runtime Trace 可使用 streaming： ```text on_event on_batch checkpoint finalize ``` --- # 二十五、Adapter Validation Suite 每個 Adapter 最低測試： ```text manifest validation probe determinism identity stability authority correctness unknown preservation budget enforcement capability enforcement canonical output malformed input partial input ``` --- # 二十六、SDK Interface 概念介面： ```python class PSMRAdapter: def manifest(self): ... def probe(self, source, context): ... def ingest(self, source, context): ... def close(self): ... ``` Incremental： ```python class IncrementalPSMRAdapter(PSMRAdapter): def update(self, previous, changes, context): ... ``` --- # 二十七、Normalized Output Adapter 不應直接寫 Workspace database。 應輸出： ```text AdapterResult ``` 由 Runtime commit 到 Workspace。 如此可以： ```text validate reject merge deduplicate ``` --- # 二十八、Adapter Result ```json { "schema": "psmr-adapter-result-0.1", "adapter_id": "...", "adapter_version": "...", "artifacts": [], "objects": [], "evidence": [], "unknowns": [], "conflicts": [], "warnings": [] } ``` --- # 二十九、Merge Into Workspace Runtime 執行： $$ W' = \operatorname{Merge}(W,E_k) $$ Merge 必須檢查： ```text identity collision authority conflict schema compatibility duplicate evidence ``` --- # 三十、Adapter 不負責跨來源真相融合 例如： ```text source says A runtime says B ``` Adapter 不應自行決定誰對。 它只輸出證據。 Conflict Resolution 是 Workspace / Operator 層責任。 --- # 三十一、第一批 Adapter PSMR 第一版建議只做： ```text PBSOI Source/Repository Adapter Git Revision Adapter PSMR Workspace Import Adapter ``` 第二批： ```text Runtime Trace Adapter OpenAPI / JSON Schema Adapter Documentation / Intent Adapter ``` --- # 三十二、與 PBSOI v1.0 的關係 PBSOI v1.0 現在同時包含部分： ```text source ingestion graph construction analysis ``` PSMR 化後可逐步拆成： $$ \boxed{ \text{Source Adapter} + \text{PBSOI Operator Stack} } $$ 不需要一次重寫。 --- # 三十三、結論 Adapter SDK 的真正目的不是： > 支援更多檔案。 而是： $$ \boxed{ \text{把外部世界轉成可被 PSMR 運算的 evidence} } $$ 因此： $$ \text{Input Generality} = \text{Adapter Contract} $$ 而不是： $$ \text{One Giant Parser} $$ 這讓 PSMR 可以長期接入新的程式語言、Runtime、Schema、文件與合法 Artifact Observation，而不必破壞核心 Semantic Workspace。