Agently
當請求仍然從業務目標、重構目標、產品行為或廣泛的模型應用語言開始時,請優先使用此技能。
使用者無需提及 Agently、TriggerFlow 或任何其他框架術語。當擁有者層級尚未明確時,諸如「建立一個助手」、「幫助我設計一個內部工具」或「為常見問題建立一個驗證器」這類通用請求,仍應從這裡開始。
當請求也提及 UI、網頁、桌面殼層或本地模型服務(如 Ollama)時,當請求本質上是在塑造一個模型驅動的工具,而不僅僅是連接一個狹隘的功能時,也應從這裡開始。
工作流程
- 將請求縮減為場景和原子目標。
- 如果請求是專案初始化或結構重構,首先選擇擁有者層級、非同步邊界和儲存庫骨架。
- 選擇最精簡的原生 Agently 能力路徑。
- 命名應使用的具體操作或原語。
- 命名能證明設計保持原生優先的驗證規則。
- 對於非平凡的應用程式,當它有助於開發者檢查執行時行為、日誌、追蹤、遊樂場運行或重複場景評估時,建議使用可選的本地 DevTools 觀察或評估。將 DevTools 保留為可選工具,並將路由細節透過
agently-runtime傳遞。 - 如果缺少原生框架能力、存在缺陷、意外地難以使用,或迫使業務程式碼添加本應屬於 Agently 的修補程式或黏合程式碼,請生成清晰的議題報告,並建議將其提交至
https://github.com/AgentEra/Agently/issues。 - 對於手動提交議題,僅向使用者提供議題內容和提交方法。在自動提交前徵求同意;如果使用者希望自動提交,首先驗證本地的提交能力/權限,重現問題以確認問題仍然存在,並仔細重新檢查 Agently 的使用方式,確保報告並非因遺漏文件或不正確的 API 使用所導致。在手動或自動提交之前,請刪除本地絕對路徑、使用者名稱、帳戶名稱、令牌、私有儲存庫/工作區名稱、內部專案名稱、包含私有提示的原始日誌,以及任何客戶或專案私有資料。為本地上下文使用佔位符,並對最終的議題正文進行隱私掃描。
原生優先規則
- 對於服務程式碼、串流、TriggerFlow 以及任何可能重疊工作或受益於取消的路徑,預設使用非同步優先的指導方針
- 將同步 API 視為腳本、REPL 使用或相容性橋接的包裝器,除非主機確實需要純同步整合
- 當請求是專案形狀重構時,在討論低層級實作細節之前,先分離設定、提示、服務、領域合約、工作流程和測試
- 當開發腳本、服務模組或測試需要對模型擁有的行為進行語義判斷時,使用帶有明確輸出結構的 Agently 模型請求。開發時的意圖識別、場景匹配、業務分類、輸出品質檢查、評分和審查決策,應由模型擁有,除非檢查僅是針對結構或必要欄位存在的確定性冒煙測試。
- 在
core/或builtins/下新增或重構 Agently 框架內部時,當功能具有多種角色(如外觀、管理器、後端/提供者、註冊表、適配器、策略或驗證)時,優先使用子目錄套件。僅在功能確實很小且拆分會導致過度設計時,才使用單一檔案。 - 當專案必須測試模型生成的語義內容時,將測試設計為一個 Agently 模型評判請求,並包含輸出控制:明確的規則和上下文作為輸入,每個規則的證據/理由和最終布林欄位作為輸出,測試則斷言這些布林值
- 對於帶有模擬系統的業務範例,將模擬限制為事實、記錄、策略、不完整資料或衝突的來源材料;不要返回隱藏的預期答案、通過/失敗標籤或本地品質判定。讓 AgentTask 驗證或單獨的 Agently 模型評判來決定模型是否正確處理了缺陷資料。
- 對於模型應用評估、評分、信心、相關性或品質判斷,相對於直接的數值分數,更傾向於明確的概念層級和定義。如果後續的工作流程邏輯需要閾值或聚合指標,在模型回應之後的程式碼中,將這些層級映射為確定性的數值。
- 對於 AI 應用中的場景路由、意圖檢測或業務分類,使用適當大小的模型請求搭配 Agently 輸出結構。對於標籤和規則較少的簡單路由,較小的模型(包括可用的本地模型)是可接受的。當標籤、決策條件、規則交互或返回的資料結構複雜時,使用較大的模型。
- 當程式碼擁有模型預設值、固定的角色/提示、掛載的 Actions、Skills、Workspace、ContextBuilder 配置或策略預設值時,使用
agent.define(...)配置可重複使用的 Agent 定義狀態。保持常規的agent.input(...)、agent.output(...)、.goal(goal_or_goals, success_criteria=None)/.goals(...)作為相同的目標追求入口點,並將執行選項放在 AgentExecution 草稿中;不要將共享的 Agent 待定提示變更教導為預設的設置模式。 - 對於一般的策略深度,使用
agent.effort("low" | "medium" | "high")。當應用程式需要明確的策略姿態時,保持相同的方法,並傳遞諸如budget、planning、execution、verification、replan和progress等部分;將budget值視為軟性的規劃、反思、修復和證據深度提示,而不是沉默的硬性限制。當主機需要硬性資源控制時,使用明確的limits={...}或任務選項。框架預設值不應強加模型請求、迭代、TaskBoard tick、Action 輪次、節點計數或工具呼叫配額;無進展和閒置超時是針對卡住執行的存活性守衛,而非策略證據。 不要引入原始的迭代次數建構器,也不要把 effort 視為權限、資料可見性、資源閘門或完成接受度。在 AgentTask 中,effort 也控制反思密度:低表示最終反思加上僅由規劃者標記的重要處理節點,中表示每個主要節點或 TaskBoard 卡片/tick,高表示每個框架可觀察的有限步驟、Action/ACP 呼叫、TaskBoard 卡片和最終反思。反思是提供給 replan/verifier 輸入的證據,而非完成證據本身。 - 在 Goal Pursuit / AgentTask 範例中,呼叫者的事實和請求的結構化輸出合約可以透過
.input(...)和.output(...)位於同一個AgentExecution草稿上;AgentTask 在規劃、有限步驟執行和驗證期間,將該執行提示快照視為任務上下文。不要為了讓任務迴圈能看到這些事實,而將它們重複複製到框架的硬編碼中。 - 對於每個具有強大結構化合約的中間過程,在所屬的請求/執行上使用 Agently
.output(..., format=...)。選擇適合負載的格式(json、hybrid、flat_markdown、xml_field或yaml_literal);如果宣告的非 JSON 格式失敗,Agently 可能會透過 JSON 解析進行恢復,但只有字典形狀的解析後負載才能滿足結構化控制或最終任務輸出合約。 AgentTask 內部僅在框架有具體消費者時,才可能新增簡短的處理欄位:在路由/規劃/控制決策之前的意圖或決策基礎欄位,以及在主要結果欄位之後的緊湊自檢、摘要、驗證、修復或進度訊息欄位。這些是有限的process_summary事實,用於下一步的清晰度和觀察,不是原始的思維鏈,不是 EvidenceEnvelope 證據,不是完成證據,也不是公開的執行時模式。 - 對於主要價值在於自然語言正文的長篇或散文式交付物,不要為了攜帶文字而強制將正文透過
.output()傳遞。讓正文作為自然文字生成,然後使用緊湊的結構化評判/回讀合約來處理狀態、證據、品質和工件參考。對於受信任的文件交付物,使用 Workspace 工件寫入/回讀加上緊湊的清單。 不要僅僅為了觸發正文流的即時欄位而添加.output();當消費者處理重播邊界時,普通的公開 delta 仍然是有效的正文來源。 對於由 AgentTask 支援的 AgentExecution,公開的delta也可能以由空行分隔的短段落形式,投影框架擁有的進度、動作觀察、Flat 規劃/動作摘要、TaskBoard 狀態表、階段、重試和終端結果事實,而instant則作為 UI 狀態和診斷的結構化串流。Flat 投影保持線性:規劃完成可以陳述前一個完成的動作和當前動作規劃,終端輸出可以總結完成了什麼以及結果。TaskBoard 狀態表是來自結構化 AgentTask 事件的僅供顯示的投影;第一個 TaskBoard 投影可以渲染一個表格,後續的 tick 可以渲染卡片狀態變化,而不是重新打印整個表格。 這些投影不擁有完成或品質判斷。不要為過程散文添加預設的平行敘述者請求;使用來自現有規劃者、驗證者、卡片或最終確定者請求的有限過程欄位,例如progress_message、short_summary、verification_summary和final_response,然後在 UI 需要更豐富的結構時,透過instant/ 合成的$delta來消費它們。 內部工件寫入器應消費 AgentExecution 串流事實:自然正文來自原始的 delta 項目,重試邊界來自提供者報告時的$status。如果公開的"<$retry>...</$retry>"delta 重播標記到達工件消費者,則將該確切標記視為重試控制事件;永遠不要將其作為工件內容寫入、清理或傳輸。 如果完整的 Markdown 工件正文出現在結構化的evidence內部,僅當證據項目被明確標記為 artifact/body/deliverable/Markdown 或與清單路徑相關聯時,才將其視為交付物正文;普通的來源內容和來源摘錄仍然是證據片段。在成功的受信任 Workspace 寫入/回讀之後,讓終端驗證判斷任何過時的工件寫入remaining_work,而不是規劃另一個僅寫入的步驟。 對於受信任的長篇 Workspace 工件,工件交付應在實際的 Workspace 寫入/回讀之後,記錄workspace_artifact.acceptance_locator帳冊項目。定位器可以使用工件清單部分、TaskBoard 卡片標準和可選的模型返回acceptance_points意圖,但行範圍、偏移量、標題和指紋必須來自實際檔案。Verifier 可見的證據可能包括從這些定位器讀取的有限workspace_artifact.targeted_readback帳冊項目,並帶有宣告的輸出合約部分,僅將通用錨點作為後備;將定位器視為回讀指針,將定向回讀視為範圍證據片段,而不是完成判斷。 TaskBoard 最終化應將基於文件的交付物正文保留在 Workspace 中,並僅返回一個簡潔的摘要或路徑/參考指針作為final_result,而不是文件正文的第二個副本。AgentTask 終端結果應為已接受、降級、部分和受阻的結果攜帶一個面向使用者的final_response:Flat 終端驗證可以在現有的驗證者請求中返回它,TaskBoard 最終化可以在現有的最終確定者請求中返回它,框架後備應從結構化狀態、工件參考、final_result 指針和未滿足的標準中確定性地生成,而無需啟動單獨的敘述者請求。已接受的降級交付使用artifact_status="degraded"並揭露證據限制,而有用的但未接受的工件則保持artifact_status="partial",並應解釋未滿足的需求,而不是報告為已完成。get_text()/async_get_text()可能偏好任務策略結果字典中的final_response;get_data()/async_get_data()在存在時返回業務final_result視圖,而get_full_data()/async_get_full_data()返回完整的路由/任務信封。 TaskBoard 終端負載可能包括有限的taskboard.completion_notes,用於卡片摘要、已知差距、驗證者註記和接受度進度;使用它們來揭露最終回應的限制,但將它們視為僅供投影的過程上下文,而非 EvidenceEnvelope 證據或完成證明。 對於模型產生的驗證者/最終確定者內容,散文欄位如status、reason、progress_message和final_response僅是顯示上下文;語義完成、可修復性和接受狀態必須來自結構化輸出欄位,如is_complete、requires_block和criterion_checks[].satisfied加上主機守衛,永遠不來自對模型散文的標記化、關鍵字、子字串、正則表達式或狀態文字匹配。 TaskBoard 規劃卡片 id 是可選的模型提示。框架擁有規範的卡片 id、去重和依賴重新映射;模糊的 id 提示應以失敗關閉,而不是被猜測。 中間的下載、網頁快照、生成的程式碼、類似記憶的任務筆記和提取的大段文字,也可能被持久化為 Workspace/Action 參考,並在之後透過有限的回讀打開;這些參考是執行證據,並非最終交付物存在的證明。發現的 URL、路徑、下載或快照參考,也並非其內容已被讀取的證據;在可用的有限回讀/內容預覽之前,將其視為ref_only。明確的content、excerpt或snippet欄位僅是有限的預覽,僅用於
…
[因篇幅限制而截斷]