← Archive
lm-004708 · 2026-10

PSMR Adapter SDK Specification v0.1

en · md Raw source ↗ Metadata ↗
下載 MD 檔 ⬇

PSMR Adapter SDK Specification v0.1

版本： v0.1
作者： Neo.K
機構： EveMissLab
日期： 2026-09-15

公司： 一言諾科技有限公司

0. 文件目的

PSMR 必須能接受不同來源。

但核心 Runtime 不應內建所有解析器。

因此定義 Adapter SDK。

Adapter 的責任是：

Ak:Xk→EkA_k : X_k \rightarrow E_k

即將外部來源轉成 Evidence Artifact 與 Semantic Objects。

一、Adapter 類型

第一版定義：

source
git
runtime
schema
documentation
intent
artifact_observation
external_analyzer

二、Adapter Manifest

每個 Adapter 必須提供：

{
  "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

discover
probe
ingest
normalize
emit
close

四、Probe

Probe 不應直接完整解析。

它只回答：

can_handle
confidence
detected_type
estimated_cost
required_capabilities

五、Ingest Request

{
  "adapter_id": "source.python",
  "source": {
    "kind": "path",
    "value": "src/"
  },
  "policy": {},
  "capability_refs": []
}

六、Ingest Result

{
  "artifacts": [],
  "semantic_objects": [],
  "unknowns": [],
  "conflicts": [],
  "warnings": [],
  "metrics": {}
}

七、Evidence Requirement

Adapter 不能只輸出結論。

至少應保留：

origin
locator
version
observation method
content identity
authority
uncertainty

八、Source Adapter

Source Adapter 可以輸出：

source artifact
syntax structure
symbol index
import facts
source spans

但高階 CISG 可交給 PBSOI Operator Stack。

Adapter 與 Analyzer 應分工：

Adapter observes≠Operator reasons\boxed{ \text{Adapter observes} \neq \text{Operator reasons} }

九、Git Adapter

輸出：

repository identity
revision identity
parent relation
changed files
commit metadata

Git Adapter 不應自行產生 Semantic Diff。

Semantic Diff 是 Operator。

十、Runtime Adapter

接受：

trace
log
profile
runtime event stream

並產生 observed runtime evidence。

必須保留：

timestamp
process/thread identity
event source
sampling method
loss/truncation information

十一、Schema Adapter

接受：

OpenAPI
JSON Schema
GraphQL
protobuf
database schema
package manifest

輸出：

type objects
contract objects
boundary objects
compatibility facts

十二、Documentation Adapter

文件內容預設：

authority = claimed

不得標記成 implementation observed。

十三、Intent Adapter

自然語言 Intent 可產生：

goal
constraint
non-goal
acceptance criterion
open question

但預設：

status = claimed
authority = intent

十四、Artifact Observation Adapter

此 Adapter 是「無 source」工作流的通用接口。

PSMR 核心不定義具體觀測方法。

只定義：

外部合法、授權工具可以輸入結構化 evidence。

Manifest 可聲明：

input_kind = compiled_artifact
observation_method = external

十五、External Analyzer Adapter

若外部工具已輸出：

call graph
dependency graph
security findings
type data

PSMR 可透過 Adapter 引入。

但必須保留：

tool identity
tool version
tool confidence
original finding identity

十六、Authority Mapping

Adapter 必須映射 authority。

例如：

source parser -> implementation observed
runtime trace -> runtime observed
README -> author claimed
LLM extractor -> inferred
external analyzer -> external tool claim

十七、Uncertainty

Adapter 應明確輸出：

complete
partial
sampled
truncated
ambiguous
unsupported

十八、Bounded Analysis

Adapter 必須支援 budget。

例如：

{
  "max_files": 3000,
  "max_bytes_per_file": 400000,
  "max_events": 1000000
}

超出時：

truncated = true

並產生 Unknown / Warning。

十九、Capability

Adapter 所需 capability 必須最小化。

例如 Source Adapter 通常只需要：

filesystem-read

不能因為「方便」就要求：

filesystem-write
process-execute
network

二十、Sandbox

第三方 Adapter 預設應執行於受限 sandbox。

可限制：

filesystem scope
network
process
memory
time
output size

二十一、Deterministic Adapter

若 Adapter 標記 deterministic：

A(X,P)=EA(X,P) = E

在相同：

input bytes
adapter version
policy

下 canonical result 必須一致。

二十二、Adapter Cache

Key：

KA=H(adapter version,input identity,policy)K_A = H( \text{adapter version}, \text{input identity}, \text{policy} )

二十三、Incremental Adapter

Adapter 可聲明：

supports_incremental = true

並接受：

previous_result
changed_regions

二十四、Streaming Adapter

Runtime Trace 可使用 streaming：

on_event
on_batch
checkpoint
finalize

二十五、Adapter Validation Suite

每個 Adapter 最低測試：

manifest validation
probe determinism
identity stability
authority correctness
unknown preservation
budget enforcement
capability enforcement
canonical output
malformed input
partial input

二十六、SDK Interface

概念介面：

class PSMRAdapter:
    def manifest(self): ...
    def probe(self, source, context): ...
    def ingest(self, source, context): ...
    def close(self): ...

Incremental：

class IncrementalPSMRAdapter(PSMRAdapter):
    def update(self, previous, changes, context): ...

二十七、Normalized Output

Adapter 不應直接寫 Workspace database。

應輸出：

AdapterResult

由 Runtime commit 到 Workspace。

如此可以：

validate
reject
merge
deduplicate

二十八、Adapter Result

{
  "schema": "psmr-adapter-result-0.1",
  "adapter_id": "...",
  "adapter_version": "...",
  "artifacts": [],
  "objects": [],
  "evidence": [],
  "unknowns": [],
  "conflicts": [],
  "warnings": []
}

二十九、Merge Into Workspace

Runtime 執行：

W′=Merge⁡(W,Ek)W' = \operatorname{Merge}(W,E_k)

Merge 必須檢查：

identity collision
authority conflict
schema compatibility
duplicate evidence

三十、Adapter 不負責跨來源真相融合

例如：

source says A
runtime says B

Adapter 不應自行決定誰對。

它只輸出證據。

Conflict Resolution 是 Workspace / Operator 層責任。

三十一、第一批 Adapter

PSMR 第一版建議只做：

PBSOI Source/Repository Adapter
Git Revision Adapter
PSMR Workspace Import Adapter

第二批：

Runtime Trace Adapter
OpenAPI / JSON Schema Adapter
Documentation / Intent Adapter

三十二、與 PBSOI v1.0 的關係

PBSOI v1.0 現在同時包含部分：

source ingestion
graph construction
analysis

PSMR 化後可逐步拆成：

Source Adapter+PBSOI Operator Stack\boxed{ \text{Source Adapter} + \text{PBSOI Operator Stack} }

不需要一次重寫。

三十三、結論

Adapter SDK 的真正目的不是：

支援更多檔案。

而是：

把外部世界轉成可被 PSMR 運算的 evidence\boxed{ \text{把外部世界轉成可被 PSMR 運算的 evidence} }

因此：

Input Generality=Adapter Contract\text{Input Generality} = \text{Adapter Contract}

而不是：

One Giant Parser\text{One Giant Parser}

這讓 PSMR 可以長期接入新的程式語言、Runtime、Schema、文件與合法 Artifact Observation，而不必破壞核心 Semantic Workspace。