Metadata-Version: 2.5
Name: ex-minimal-adapter-py
Version: 0.0.1a1
Summary: promptex 第三方平台適配擴展範例（alpha）：把同一份源碼投影成另一套平台原生產物
Project-URL: Homepage, https://github.com/promptex-ai/ex-minimal-project-py
Project-URL: Repository, https://github.com/promptex-ai/ex-minimal-project-py
Project-URL: Issues, https://github.com/promptex-ai/ex-minimal-project-py/issues
Author: promptex-ai
License: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,codegen,llm,prompt,promptex,promptex-adapter
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Requires-Dist: promptex-py~=0.0.0
Description-Content-Type: text/markdown

# ex-minimal-adapter-py

[ex-minimal-project-py](../../) 的 adapter 擴展。由專案以路徑來源（`[tool.uv.sources]` 的 editable path）掛上：Python 的 import 走發布名對應的 import 套件名，帶連字號的目錄無法直接 import；同時保持可發布形態——中繼欄位、參數宣告與授權都隨套件出貨，版號比照 promptex 的 alpha 原型套件。

適配以 SDK 層實作，只用 `AdapterContext` 的公開介面。`emit` 的責任鏈固定四步：

1. 算落點表——渲染要靠它解析引用，因此必須在渲染之前完成。
2. 回報不支援的 kind——逐一列進報告，不靜默丟棄。
3. 渲染並產出節點——平台缺某機制時記 degrade 降級。
4. 產出被引用的資源。

本適配示範的平台只有提示詞單檔與參考資料：支援 skill、rule、instruction，不支援 agent、hook、mcp、permission。適配綁語言——同一個平台要服務另兩個生態的專案時，各自以該語言的 SDK 實作一份。

## 在本專案的接法

`promptex.config.py` 的目標清單寫成 `targets=[claude(), ex_minimal_adapter()]`，claude 是內建適配、本擴展是第三方適配，同一份源碼因此投影出兩套平台原生產物。跑 `uv run promptex install .` 後產物落在 `.ex-minimal-adapter-py/prompts/`，安裝報告會列出一項降級：範例規則宣告了適用範圍，而本平台無範圍載入機制，改為常駐並在內文標註適用範圍。

## 參數宣告

參數宣告（標準 JSON Schema）住import 套件目錄裡的 `promptex.config.schema.json`，由 `__init__.py` 自己讀進來，隨中介表示交給讀取端；`promptex config declare ex-minimal-adapter-py` 讀的是同一份檔案。

## 發布

```bash
uv build
uvx twine check dist/*
uvx twine upload dist/*
```

版號寫 PEP 440 的 `0.0.1a1`，與另兩個生態的 `0.0.1-alpha.1` 指同一個版本——三生態版號無法逐字相同，這是預發布版號的既有限制。安裝端要 `pip install --pre ex-minimal-plugin-py`：預發布版號不會被 pip 預設選中。

SDK 依賴不必換：`dependencies` 的 `promptex-py~=0.0.0` 在 registry 上對到的是 promptex-prototype 發的 `0.0.0` **介面樁**——型別與簽名逐字複製正式版、方法本體一律拋錯。發布驗證（尤其 `cargo publish` 的建置）拿它編得過；裝到消費端也裝得起來，但實際執行要靠工作區覆寫指向本地的正式版 SDK，否則第一個碰到樁的呼叫就會以「promptex 介面樁」開頭的錯誤中止。

名稱刻意不帶 `promptex-adapter-` 前綴——那是給要被消費端搜尋到的套件用的；本擴展的定位是示範，改以 keywords 的 `promptex-adapter` 承載可搜尋性。
