python-resource-management

python-resource-management 技能總覽

python-resource-management 技能是做什麼的

python-resource-management 技能可協助代理產出在 Python 中能夠可預期地取得、使用並釋放資源的程式碼。它的重點不是一般性的 Python 風格建議，而是專注在 context manager、清理保證、例外安全的 teardown、巢狀資源處理、非同步資源生命週期，以及能讓狀態維持可控的串流模式。

誰適合使用這個技能

這個技能特別適合後端工程師、API 開發者，以及處理檔案、資料庫連線、socket、暫存資源、背景串流等情境的自動化團隊；凡是資源洩漏會在正式環境造成問題的程式路徑，都很適合使用。尤其在 python-resource-management for Backend Development 這類情境下，當請求會開啟連線、串流資料，或需要在失敗時仍能確定完成清理時，它會特別有幫助。

真正要解決的工作是什麼

大多數使用者不是想聽一段關於 with 的教學，而是需要直接能用的程式碼來完成以下工作：

• 把脆弱的 try/finally 清理流程改寫成更安全的 context manager
• 設計帶有 __enter__ 與 __exit__ 的自訂資源包裝
• 用 async with 建立非同步資源處理
• 判斷什麼時候應該吞掉例外、什麼時候應該重新拋出
• 乾淨地管理多個資源，避免 teardown 邏輯彼此糾結
• 實作能正確累積或釋放狀態的串流回應

這個技能和一般 Python 提示有什麼不同

一般提示可能會產出在 happy path 下「看起來能跑」的 Python，但忽略 teardown 的邊界情況。python-resource-management 技能在生命週期正確性是關鍵時更有優勢：例如例外發生時的清理、資源釋放順序、非同步協定方法，以及以 contextlib 為核心的模式。當你在意失敗情境、部分寫入，或長生命週期 handle 的安全處理時，它會比泛用型 coding prompt 更實用。

安裝前你該知道的事

這個技能是一份精簡的指引檔，不是包含多個 helper script 或分散在多個檔案中的完整套件。這對快速導入是優點，但也代表輸出品質很仰賴你給代理的提示內容。如果你能描述清楚資源類型、生命週期規則、同步或非同步模式，以及失敗時的行為，這個技能更有可能產出可直接上線的程式碼。

如何使用 python-resource-management 技能

如何安裝 python-resource-management 技能

請從 wshobson/agents repository 安裝這個技能：

npx skills add https://github.com/wshobson/agents --skill python-resource-management

安裝後，在你的代理工作流程中，以和其他 repository skills 相同的方式載入它。如果你的環境支援技能自動選用，請用資源生命週期、清理、串流或 context manager 設計這類描述來表達任務，讓代理能自然觸發 python-resource-management。

先讀這個檔案

先從這個檔案開始：

• plugins/python-development/skills/python-resource-management/SKILL.md

這個技能沒有額外的 scripts、rules 或 reference folders，因此幾乎所有可用的指引都集中在這一個檔案裡。不要先假設它涵蓋 retry、pooling 策略，或 framework-specific 整合；先把這份內容讀完。

這個技能要吃到哪些輸入才會發揮得好

若想讓 python-resource-management usage 更可靠，請提供以下資訊：

• 資源類型：file、DB connection、socket、temporary directory、lock、stream
• 同步或非同步執行模型
• 資源取得步驟
• 必須執行的清理步驟
• 是否每一種例外都必須完成清理
• 是否有任何例外應該被 suppress
• 資源是巢狀存在還是動態建立
• 輸出是可重用的抽象，還是單一本地 code block

弱輸入：

• 「把這段弄乾淨一點。」

強輸入：

• 「Refactor this async FastAPI endpoint so an httpx.AsyncClient is opened once per request, closed even on cancellation, and the streaming response does not retain the whole payload in memory.」

把模糊需求轉成強提示

這個技能的好提示通常包含四個部分：

1. 目前的程式碼或既有模式
2. 生命週期需求
3. 失敗時的行為
4. 希望的抽象層級

範例：

Use the python-resource-management skill.

I have Python code that opens a file, writes partial results, and also uses a DB session. Refactor it so:
- both resources are managed deterministically
- DB cleanup still happens if file writing fails
- exceptions are not suppressed
- the result should use standard library patterns where possible
- show the final code and explain why the cleanup order is safe

這比只要求「best practices」更好，因為它給了代理明確的資源圖與例外策略。

python-resource-management for Backend Development 的最佳使用情境

當你需要處理以下問題時，這個技能很適合：

• 用 context manager 包裝 DB session 或 transaction
• 確保檔案與暫存資源一定會被關閉
• 實作 request-scoped client
• 在 network call 周圍建立非同步清理流程
• 以逐塊方式串流資料，不必不必要地保留完整狀態
• 取代散落在多個函式中的臨時 teardown 邏輯

若任務重點主要是 ORM 設計、效能調校，或 framework routing，而不是資源生命週期複雜度，這個技能就沒那麼有幫助。

這個技能主要會生成哪些核心模式

可以預期這個技能會傾向引導出以下模式：

• with 與 async with
• contextlib.contextmanager
• contextlib.asynccontextmanager
• 以 __enter__ / __exit__ 實作的 class-based context managers
• 以 __aenter__ / __aexit__ 實作的 class-based async managers
• 在 finally 中明確清理
• 謹慎處理例外傳遞或 suppress 的決策

也正因為這個聚焦方向，python-resource-management skill 在生命週期密集型程式碼上，比泛用 Python 助手更精準。

使用這個技能的實務工作流程

一個可靠的工作流程是：

1. 找出程式路徑中取得的每一個資源
2. 註明每個資源由誰擁有，以及擁有權何時結束
3. 決定要用 sync 還是 async protocol
4. 說清楚例外是否必須往外傳遞
5. 請代理重構成支援的其中一種模式
6. 檢查清理順序與 cancellation 行為
7. 測試強制失敗路徑，而不只是成功路徑

如果你跳過第 2 步，代理可能會產出過早關閉共享資源，或把 context 包在錯誤範圍上的程式碼。

能提升輸出品質的提示範例

可以使用這類提示：

Use python-resource-management to convert this `try/finally` block into a reusable context manager. Keep the public call site simple and do not suppress exceptions.

Use python-resource-management to design an async context manager for a WebSocket client. The connection must close on timeout, cancellation, or normal exit.

Use python-resource-management to restructure this generator-based streaming response so chunk production is incremental and all file handles are released after iteration stops early.

這些提示之所以有效，是因為它們明確指定了生命週期保證，而那正是這個技能真正處理的主題。

常見導入阻礙

常見卡點通常不是安裝問題，而是設計上的模糊地帶：

• 不清楚清理責任到底屬於誰
• 把共享資源和本地資源混在同一個 context manager 裡
• 想要 framework-specific 行為，卻沒說出 framework 名稱
• 沒有交代是否允許 suppress 例外
• 忘了非同步 cancellation 路徑

如果第一次回答看起來很泛，通常代表提示缺少了上述其中一項資訊。

這個技能不能取代什麼

python-resource-management guide 並不能取代：

• framework docs 裡的 dependency injection 或 lifespan hooks
• 各 driver 對 transaction boundary 的特定規則
• 串流背壓的 load testing
• 涉及 temp files、credentials 或 socket handling 的安全審查

正確用法是：先用這個技能把程式碼整理成生命週期安全的結構，再用你實際部署的 library 或 framework 進一步驗證。

python-resource-management 技能 FAQ

python-resource-management 適合初學者嗎？

適合，但前提是你已經懂基本 Python 語法，並希望把 with、async with 或 contextlib 用對。如果你還在理解 file handle、DB session 或 async client 本身是做什麼，這個技能就沒那麼初學者友善，因為結果品質取決於你是否理解自己正在管理的資源。

什麼時候該用它，而不是一般 coding prompt？

當主要風險是資源洩漏、teardown 不正確，或巢狀清理邏輯混亂時，就該用 python-resource-management。如果你的任務只是「寫一個 Python function」，一般 prompt 就夠了；但如果你的任務是「確保這個 connection 在 streaming 失敗時也一定會關閉」，那這個技能會是更好的選擇。

python-resource-management 技能涵蓋 async code 嗎？

有。原始指引明確包含 async context manager，以及 __aenter__ / __aexit__ 協定。如果你的程式使用 asyncio、web handler、async database client 或 streaming coroutine，請直接在提示裡寫明。

它能幫忙處理 streaming response 嗎？

可以，而且這正是值得安裝它的其中一個重要理由。這個技能明確提到建構帶有累積狀態的 streaming response，因此當你需要增量輸出、又不想洩漏 handle 或保留過多記憶體時，它很有參考價值。

這個技能對例外 suppress 有既定立場嗎？

它會說明核心規則：__exit__ 回傳 True 會 suppress 例外，回傳 False 則會讓例外繼續傳遞。這很有用，但你仍然需要明確告訴代理你想要哪一種行為。在後端系統中，除非你有非常清楚的復原策略，否則默默 suppress 通常不是好的預設值。

python-resource-management 對資料庫 pooling 夠用嗎？

單靠它還不夠。它能協助你建立 connection 或 session cleanup 的模型，但不能取代 pool configuration、driver tuning，或 transaction semantics。請搭配你的 DB library docs 一起使用。

什麼情況下這個技能不適合？

若任務重點主要是以下內容，就可以先跳過它：

• business logic
• framework routing
• schema design
• 與資源生命週期無關的 performance profiling
• 不會取得或釋放重要資源的程式碼

在這些情況下，python-resource-management install 的判斷很簡單：你大概還不需要這個技能。

如何改善 python-resource-management 技能的使用效果

先把資源擁有權邊界講清楚

想讓 python-resource-management 更快產出好結果，最有效的方法就是明確說出每個資源由誰擁有。例如：

• 「The function creates the file handle and must close it.」
• 「The DB session is injected and must not be closed here.」
• 「The HTTP client should live for one request only.」

沒有擁有權邊界時，產生的程式碼很容易在錯誤層級關閉共享資源。

明確指定清理順序

對巢狀資源來說，清理順序很重要。請直接告訴代理哪個資源必須先釋放，以及原因。範例：

Use python-resource-management. The temp file must flush before the upload client closes, and the DB transaction should only commit after the upload succeeds.

這能避免產出表面整齊、但 teardown 順序不安全的程式碼。

不只要程式碼，也要求它解釋失敗路徑

很值得追加的要求是：

Explain what happens on success, on an exception inside the block, and on an exception during cleanup.

這會迫使代理真的去推理生命週期，而不是只生成一個看起來漂亮的 context manager。

一開始就說清楚是 sync 還是 async

很多品質不佳的輸出，都來自於沒有先指定執行模式。如果真實程式是 async，請在第一句就說。否則模型可能會產出一個看似合理、實際上卻不適合你技術棧的 sync with 模式。

提供一段真實的程式碼樣本

即使只是部分片段，也比長篇抽象描述更能提升輸出品質。這樣模型才能在套用資源管理模式時，同時保留呼叫端的人體工學、命名方式與例外流程。

特別留意這些常見失敗模式

請優先檢查第一版輸出是否有以下問題：

• 清理發生在錯誤的 scope
• 在你沒要求的情況下 suppress 了例外
• 把共享依賴包進本地 context manager
• 對 async 資源使用 sync context manager
• 串流程式仍然把所有資料累積在記憶體中
• 明明用 contextlib 就夠，卻硬做成自訂 context manager

這些通常就是值得用第二輪提示修正的地方。

要求最簡單但安全的模式

如果你要的是好維護的程式碼，請直接講明。範例：

Use the simplest safe standard-library pattern. Prefer `contextlib.contextmanager` unless a class-based context manager is clearly needed.

這通常能改善可讀性，也能避免過度設計。

用精準修正迭代，不要每次都整段重來

拿到第一版回答後，盡量用狹義、具體的回饋來修正，而不是重新下非常寬泛的需求：

• 「Do not suppress exceptions.」
• 「Make this asynccontextmanager.」
• 「The caller owns the session; remove session closing.」
• 「Refactor to support two nested resources.」
• 「Keep streaming incremental; do not buffer the full response.」

這種迭代方式，通常比一再要求完整重寫，更能從 python-resource-management skill 榨出價值。

搭配能強迫清理發生的測試

如果想提高信心，請要求代理產出能模擬「使用途中失敗」與「teardown 過程失敗」的測試。資源管理程式碼常常表面看起來正確，但真正遇到 cancellation、中途串流失敗，或巢狀例外路徑時才暴露問題。

把 python-resource-management 當成重構工具來用

python-resource-management 最好的長期用法，不只是從零生成新程式碼。它也很適合拿來檢視那些「目前能跑，但暗藏 cleanup bug」的既有後端程式。把現有實作餵給代理，先請它找出生命週期風險，再要求重寫；通常會比直接從零開始要一份全新實作，更容易得到可信的結果。