promptex-py 0.0.1a1__tar.gz

promptex_py-0.0.1a1/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.egg-info/
+tmp/

promptex_py-0.0.1a1/LICENSE-APACHE

@@ -0,0 +1,204 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the
+      purposes of this License, Derivative Works shall not include works
+      that remain separable from, or merely link (or bind by name) to the
+      interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright
+      owner or by an individual or Legal Entity authorized to submit on
+      behalf of the copyright owner. For the purposes of this definition,
+      "submitted" means any form of electronic, verbal, or written
+      communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing
+      lists, source code control systems, and issue tracking systems that
+      are managed by, or on behalf of, the Licensor for the purpose of
+      discussing and improving the Work, but excluding communication that
+      is conspicuously marked or otherwise designated in writing by the
+      copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing
+      the origin of the Work and reproducing the content of the NOTICE
+      file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this
+      License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 promptex-ai
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

promptex_py-0.0.1a1/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 promptex-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

promptex_py-0.0.1a1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: promptex-py
+Version: 0.0.1a1
+Summary: promptex 的 Python SDK 最小原型（alpha）：宣告 skill 並投影成 SKILL.md
+Project-URL: Homepage, https://github.com/promptex-ai/promptex
+Project-URL: Repository, https://github.com/promptex-ai/promptex
+Project-URL: Issues, https://github.com/promptex-ai/promptex/issues
+Author: promptex-ai
+License: MIT OR Apache-2.0
+License-File: LICENSE-APACHE
+License-File: LICENSE-MIT
+Keywords: agent,ai,claude,codegen,llm,prompt,prompt-engineering,skills
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT 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
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# promptex-py（alpha 原型）
+
+promptex 的 Python SDK **最小原型**。目前的能力只有一項：宣告 skill，建置成
+Claude Code 的 `SKILL.md` 產物。
+
+## 這不是什麼
+
+本套件是早期 alpha，**不是**完整的 promptex。正式版的單一套件內含 SDK、核心的
+預編譯二進位綁定與完整命令列工具三者；本原型只有 SDK 的最窄一條路徑，命令列
+工具只有 `build` 一個動詞，沒有原生綁定、沒有多平台投影、沒有引用與關係圖、
+沒有安裝與所有權登記。
+
+介面與產物格式在正式版之前都會變，不保證任何相容性。正式版發布時本原型會被
+整份取代。
+
+## 安裝
+
+```bash
+pip install --pre promptex-py
+```
+
+需要 Python 3.10 以上。`--pre` 是必要的：預發布版號不會被 pip 預設選中。
+
+## 用法
+
+把宣告寫在 `prompts/` 下：
+
+```python
+# prompts/skill.py
+from promptex import config, define_skill
+
+commit_helper = define_skill(
+    "commit-helper",
+    "Commit 訊息協助",
+    config=config(when_to_use="當使用者要求撰寫 commit 訊息時使用"),
+    content=[
+        "依 Conventional Commits 撰寫：type(scope): subject。",
+        "subject 用繁體中文、50 字內，不以句號結尾；body 說明變更動機而非變更內容。",
+    ],
+)
+```
+
+建置：
+
+```bash
+promptex build
+```
+
+產出 `./.claude/skills/commit-helper/SKILL.md`：
+
+```text
+---
+name: commit-helper
+description: 當使用者要求撰寫 commit 訊息時使用
+---
+
+依 Conventional Commits 撰寫：type(scope): subject。
+
+subject 用繁體中文、50 字內，不以句號結尾；body 說明變更動機而非變更內容。
+```
+
+### 命令列選項
+
+```text
+promptex build [--src <目錄>] [--out <目錄>]
+
+  --src <目錄>   宣告檔所在目錄，預設 prompts
+  --out <目錄>   產物輸出目錄，預設當前目錄
+```
+
+### 程式化呼叫
+
+```python
+from promptex import build, config, define_skill
+
+define_skill("commit-helper", "Commit 訊息協助", config=config(when_to_use="..."), content="...")
+written = build(".")
+```
+
+## 授權
+
+MIT OR Apache-2.0，見 `LICENSE-MIT` 與 `LICENSE-APACHE`。

promptex_py-0.0.1a1/README.md

@@ -0,0 +1,82 @@
+# promptex-py（alpha 原型）
+
+promptex 的 Python SDK **最小原型**。目前的能力只有一項：宣告 skill，建置成
+Claude Code 的 `SKILL.md` 產物。
+
+## 這不是什麼
+
+本套件是早期 alpha，**不是**完整的 promptex。正式版的單一套件內含 SDK、核心的
+預編譯二進位綁定與完整命令列工具三者；本原型只有 SDK 的最窄一條路徑，命令列
+工具只有 `build` 一個動詞，沒有原生綁定、沒有多平台投影、沒有引用與關係圖、
+沒有安裝與所有權登記。
+
+介面與產物格式在正式版之前都會變，不保證任何相容性。正式版發布時本原型會被
+整份取代。
+
+## 安裝
+
+```bash
+pip install --pre promptex-py
+```
+
+需要 Python 3.10 以上。`--pre` 是必要的：預發布版號不會被 pip 預設選中。
+
+## 用法
+
+把宣告寫在 `prompts/` 下：
+
+```python
+# prompts/skill.py
+from promptex import config, define_skill
+
+commit_helper = define_skill(
+    "commit-helper",
+    "Commit 訊息協助",
+    config=config(when_to_use="當使用者要求撰寫 commit 訊息時使用"),
+    content=[
+        "依 Conventional Commits 撰寫：type(scope): subject。",
+        "subject 用繁體中文、50 字內，不以句號結尾；body 說明變更動機而非變更內容。",
+    ],
+)
+```
+
+建置：
+
+```bash
+promptex build
+```
+
+產出 `./.claude/skills/commit-helper/SKILL.md`：
+
+```text
+---
+name: commit-helper
+description: 當使用者要求撰寫 commit 訊息時使用
+---
+
+依 Conventional Commits 撰寫：type(scope): subject。
+
+subject 用繁體中文、50 字內，不以句號結尾；body 說明變更動機而非變更內容。
+```
+
+### 命令列選項
+
+```text
+promptex build [--src <目錄>] [--out <目錄>]
+
+  --src <目錄>   宣告檔所在目錄，預設 prompts
+  --out <目錄>   產物輸出目錄，預設當前目錄
+```
+
+### 程式化呼叫
+
+```python
+from promptex import build, config, define_skill
+
+define_skill("commit-helper", "Commit 訊息協助", config=config(when_to_use="..."), content="...")
+written = build(".")
+```
+
+## 授權
+
+MIT OR Apache-2.0，見 `LICENSE-MIT` 與 `LICENSE-APACHE`。

promptex_py-0.0.1a1/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "promptex-py"
+# PEP 440 的正規化形態：npm 與 crates.io 側寫的是 semver 的 `0.0.1-alpha.1`，
+# PyPI 會把它正規化成 `0.0.1a1`，兩者指同一個版本。三生態版號無法逐字相同，
+# 這是預發布版號的既有限制。
+version = "0.0.1a1"
+description = "promptex 的 Python SDK 最小原型（alpha）：宣告 skill 並投影成 SKILL.md"
+requires-python = ">=3.10"
+license = { text = "MIT OR Apache-2.0" }
+readme = "README.md"
+authors = [{ name = "promptex-ai" }]
+keywords = ["prompt", "prompt-engineering", "ai", "llm", "agent", "claude", "skills", "codegen"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: Software Development :: Code Generators",
+  # 這一項要成立得靠 src/promptex/py.typed 隨 wheel 一起出貨（PEP 561）：
+  # 型別檢查器對已安裝的套件一律先找標記檔，找不到就整個套件視為無標註。
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/promptex-ai/promptex"
+Repository = "https://github.com/promptex-ai/promptex"
+Issues = "https://github.com/promptex-ai/promptex/issues"
+
+[project.scripts]
+promptex = "promptex.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/promptex"]
+
+[tool.hatch.build]
+# 開發樹本身就是 python-source，直譯器跑過測試留下的 __pycache__ 會被收進
+# wheel。那些 .pyc 綁死在建置機的 Python 版本上，對安裝端無用，卻讓 wheel
+# 的內容清單隨「誰在哪台機器上建的」而變。
+exclude = ["**/__pycache__/**"]

promptex_py-0.0.1a1/src/promptex/__init__.py

@@ -0,0 +1,131 @@
+"""promptex 的 Python SDK 最小原型（alpha）。
+
+目前的能力只有一條路徑：宣告 skill，投影成 Claude Code 的 SKILL.md。
+正式版的核心綁定、多平台投影、引用與關係圖都不在本原型範圍內。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+__all__ = [
+    "CapabilityConfig",
+    "Ref",
+    "build",
+    "config",
+    "declared_count",
+    "define_skill",
+    "render_skill",
+    "skill_path",
+]
+
+__version__ = "0.0.1a1"
+
+
+@dataclass(frozen=True)
+class CapabilityConfig:
+    """skill 的觸發設定。"""
+
+    when_to_use: str = ""
+
+
+def config(*, when_to_use: str = "") -> CapabilityConfig:
+    """建立觸發設定。與正式版的宣告形態一致，以具名參數承載。"""
+    return CapabilityConfig(when_to_use=when_to_use)
+
+
+@dataclass(frozen=True)
+class Ref:
+    """宣告後回傳的引用。正式版以它承載節點間的引用關係，本原型只帶識別。"""
+
+    kind: str
+    id: str
+
+
+@dataclass
+class _Skill:
+    """登記處內的正規化形態。"""
+
+    id: str
+    name: str
+    when_to_use: str
+    content: list[str] = field(default_factory=list)
+
+
+# 模組層級的登記處：宣告散落在多個檔案時，逐一回傳並手動彙整會讓每個檔案
+# 都得認識彙整點。正式版的收集語意相同。
+_registry: list[_Skill] = []
+
+
+def _is_valid_id(value: str) -> bool:
+    """id 是否可安全作為單層目錄名。
+
+    產物路徑由 id 直接組成，不擋下來的話 ``../`` 這類值會把檔案寫到輸出
+    目錄之外。
+    """
+    return bool(value) and "/" not in value and "\\" not in value and value not in {".", ".."}
+
+
+def define_skill(
+    id: str,
+    name: str,
+    *,
+    config: CapabilityConfig | None = None,
+    content: str | list[str] | None = None,
+) -> Ref:
+    """宣告一份 skill。
+
+    宣告本身不寫檔；產物在 :func:`build` 被呼叫時一次產出。
+    """
+    if not _is_valid_id(id):
+        raise ValueError(f"skill id 不可為空、且不可含 `/`、`\\` 或 `..`：{id!r}")
+    pieces = [] if content is None else ([content] if isinstance(content, str) else list(content))
+    _registry.append(
+        _Skill(
+            id=id,
+            name=name,
+            when_to_use=(config or CapabilityConfig()).when_to_use,
+            content=pieces,
+        )
+    )
+    return Ref(kind="skill", id=id)
+
+
+def declared_count() -> int:
+    """目前已登記的宣告數。供呼叫端在建置前自我核對用。"""
+    return len(_registry)
+
+
+def render_skill(skill: _Skill) -> str:
+    """把一份 skill 投影成 SKILL.md 的完整內容。
+
+    frontmatter 的 ``name`` 取 id 而非顯示名稱：平台側以 ``name`` 作為喚起時
+    的識別。
+    """
+    header = f"---\nname: {skill.id}\ndescription: {skill.when_to_use}\n---\n"
+    if not skill.content:
+        return header
+    return header + "\n" + "\n\n".join(skill.content) + "\n"
+
+
+def skill_path(out_dir: str | Path, id: str) -> Path:
+    """一份 skill 在輸出目錄下的產物路徑。"""
+    return Path(out_dir) / ".claude" / "skills" / id / "SKILL.md"
+
+
+def build(out_dir: str | Path) -> list[Path]:
+    """把目前登記的全部宣告投影到輸出目錄，回傳產物路徑。
+
+    呼叫後登記處清空：同一行程內連續建置兩個輸出目錄時，第二次不該重複
+    寫出第一次的內容。
+    """
+    skills = list(_registry)
+    _registry.clear()
+    written: list[Path] = []
+    for skill in skills:
+        path = skill_path(out_dir, skill.id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(render_skill(skill), encoding="utf-8")
+        written.append(path)
+    return written

promptex_py-0.0.1a1/src/promptex/__main__.py

@@ -0,0 +1,5 @@
+"""讓 ``python -m promptex`` 與 ``promptex`` 執行檔走同一條路徑。"""
+
+from .cli import main
+
+raise SystemExit(main())

promptex_py-0.0.1a1/src/promptex/cli.py

@@ -0,0 +1,70 @@
+"""promptex 命令列工具（alpha 原型）。
+
+只有一個動詞：``build``。載入來源目錄下的宣告檔，把登記處內的 skill 投影成
+SKILL.md。正式版的其餘動詞（evaluate、declare、config、diagnostics）不在本
+原型範圍內。
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import sys
+from pathlib import Path
+
+from . import build, declared_count
+
+
+def _load_source(path: Path) -> None:
+    """以檔案路徑載入一份宣告檔。
+
+    走 importlib 的 spec 載入而非 ``import``：宣告檔住使用者的專案目錄，
+    不在套件搜尋路徑上，也不該為了載入它去改動 ``sys.path``。
+    """
+    module_name = f"_promptex_source_{path.stem}"
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"無法載入宣告檔：{path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+
+
+def _collect_sources(src_dir: Path) -> list[Path]:
+    """列出來源目錄下的宣告檔，依路徑排序讓載入順序不隨檔案系統而變。"""
+    return sorted(p for p in src_dir.rglob("*.py") if p.name != "__init__.py")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="promptex", description="promptex（alpha 原型）")
+    sub = parser.add_subparsers(dest="verb", required=True)
+    build_parser = sub.add_parser("build", help="把宣告投影成產物")
+    build_parser.add_argument("--src", default="prompts", help="宣告檔所在目錄，預設 prompts")
+    build_parser.add_argument("--out", default=".", help="產物輸出目錄，預設當前目錄")
+
+    args = parser.parse_args(sys.argv[1:] if argv is None else argv)
+
+    src_dir = Path(args.src).resolve()
+    if not src_dir.is_dir():
+        print(f"找不到來源目錄：{src_dir}", file=sys.stderr)
+        return 1
+
+    sources = _collect_sources(src_dir)
+    if not sources:
+        print(f"來源目錄沒有宣告檔（*.py）：{src_dir}", file=sys.stderr)
+        return 1
+
+    for source in sources:
+        _load_source(source)
+
+    if declared_count() == 0:
+        print(f"載入了 {len(sources)} 份宣告檔，但沒有任何 skill 被宣告。", file=sys.stderr)
+        return 1
+
+    for path in build(Path(args.out).resolve()):
+        print(path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

promptex_py-0.0.1a1/tests/test_promptex.py

@@ -0,0 +1,78 @@
+"""SDK 的單元測試。以 stdlib 的 unittest 承載，不引入測試框架依賴。
+
+執行：``PYTHONPATH=src python3 -m unittest discover -s tests``
+"""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+import promptex
+from promptex import build, config, declared_count, define_skill, render_skill, skill_path
+
+HEADER = "---\nname: commit-helper\ndescription: 當使用者要求撰寫 commit 訊息時使用\n---\n"
+PARAGRAPHS = [
+    "依 Conventional Commits 撰寫：type(scope): subject。",
+    "subject 用繁體中文、50 字內，不以句號結尾。",
+]
+
+
+class RenderTests(unittest.TestCase):
+    def setUp(self) -> None:
+        promptex._registry.clear()
+
+    def test_renders_frontmatter_and_paragraphs(self) -> None:
+        define_skill(
+            "commit-helper",
+            "Commit 訊息協助",
+            config=config(when_to_use="當使用者要求撰寫 commit 訊息時使用"),
+            content=PARAGRAPHS,
+        )
+        expected = HEADER + "\n" + "\n\n".join(PARAGRAPHS) + "\n"
+        self.assertEqual(render_skill(promptex._registry[0]), expected)
+
+    def test_renders_frontmatter_only_when_content_is_empty(self) -> None:
+        define_skill(
+            "commit-helper",
+            "Commit 訊息協助",
+            config=config(when_to_use="當使用者要求撰寫 commit 訊息時使用"),
+        )
+        self.assertEqual(render_skill(promptex._registry[0]), HEADER)
+
+    def test_single_string_content_becomes_one_paragraph(self) -> None:
+        define_skill("x", "X", config=config(when_to_use="t"), content="只有一段")
+        self.assertEqual(promptex._registry[0].content, ["只有一段"])
+
+    def test_rejects_ids_that_escape_the_output_directory(self) -> None:
+        with self.assertRaisesRegex(ValueError, "skill id 不可為空"):
+            define_skill("../escape", "X", config=config(when_to_use="t"), content="c")
+
+
+class BuildTests(unittest.TestCase):
+    def setUp(self) -> None:
+        promptex._registry.clear()
+
+    def test_writes_to_claude_skills_layout_and_drains_registry(self) -> None:
+        define_skill(
+            "commit-helper",
+            "Commit 訊息協助",
+            config=config(when_to_use="當使用者要求撰寫 commit 訊息時使用"),
+            content=PARAGRAPHS,
+        )
+        self.assertEqual(declared_count(), 1)
+
+        with tempfile.TemporaryDirectory() as tmp:
+            written = build(tmp)
+            self.assertEqual(written, [skill_path(tmp, "commit-helper")])
+            self.assertEqual(
+                Path(written[0]).read_text(encoding="utf-8"),
+                HEADER + "\n" + "\n\n".join(PARAGRAPHS) + "\n",
+            )
+            self.assertEqual(declared_count(), 0)
+            self.assertEqual(build(tmp), [])
+
+
+if __name__ == "__main__":
+    unittest.main()