Agent Ecosystem
單一層層治理迴圈。每個元件只負責一個關注點；它們僅透過型別化的 JSON 合約耦合，絕不匯入彼此的狀態機。
不可變的 $shame 目標是 shame-deterministic-instruction-obedience-v1
（skills/shame/immutable_goal.json）：透過將指令遵從與完成回報轉換成型別化 pydantic 驗證合約、確定性擴充閘門以及保留的代理評估（agentic evals），使專案代理無法忽略明確指令。純文字僅供顯示，不能決定成功與否。以下列出的每個生態系成員都必須在其邊界上維護該目標。
圖表
使用 $create-svg 繪製（原始檔為 scene.yml；重新產生請執行
skills/create-svg/run.sh render skills/agent-ecosystem/scene.yml skills/agent-ecosystem/ecosystem.svg）。
機器可讀的成員清單是 members.json（由 scripts/membership.py validate 驗證；保留的評估確保其保持最新）。
產生它們，上方的 SVG 和下方的 mermaid 區塊是非規範性的圖解；所有權表格和成員的 ## Ecosystem 區段才是規範性的拓撲結構。
flowchart TB
subgraph SHAPE[Generation shaping]
PONY[ponytail\nYAGNI ladder, no receipts]
end
subgraph TURN[Turn layer - Pi session]
SHAME[shame extension\npi.agent_status.v1\nvalidate, compile, swallow]
TRIAGE[triage-error\nfailure vocabulary\ncode, cause, next_command]
end
subgraph WORK[Workflow layer]
ASK[ask\ncompiles intent to DAG contracts]
TAU[tau\nexecutes DAGs, owns acceptance\ntyped node receipts, goal_hash]
end
subgraph OPS[Operations layer]
WD[project-watchdog\ncron dispatch, leases,\nproof gates, tick receipts]
HERDR[ops-herdr bridge\ninbox, quiescence,\nTTL dead-letters]
end
MEM[(Memory\ntraining examples,\ntriage resolutions,\nproject knowledge)]
PONY -.-> SHAME
SHAME -->|failed.triage.code| TRIAGE
SHAME -->|needs_* compiled commands| ASK
ASK -->|tau.dag_contract.v1| TAU
TAU -->|node receipts / handoff v2 carries status| SHAME
WD -->|ticket_repair via ask| ASK
WD -->|reads verdicts| TAU
HERDR -->|dead-letter triage codes| TRIAGE
SHAME -->|labeled examples| MEM
TRIAGE -->|minted codes| MEM
TAU -->|post-run export of bad node receipts| MEM
所有權表格
| 元件 | 擁有 | 發出 | 消費 | 對 $shame 不可變目標的必要義務 |
|---|---|---|---|---|
| project agents | 回合邊界上的指令遵從 | pi.agent_status.v1 報告 | 操作者指示、工具結果、收據 | 必須將受保護的工作回報為型別化狀態資料，使用 continuing.not_done[].next_command 表示代理可執行的未完成工作，且絕不將純文字/提交/審查者意見視為完成證明。 |
| triage-error | 失敗詞彙表（failure_codes.json） | {code, cause, next_command} | 來自任何層級的原始錯誤文字 | 必須使一個原始訊號對應到一個目錄條目或鑄造碼；模糊的終端標籤不能成為有效決策。 |
| shame | 回合狀態（pi.agent_status.v1）和 shame.immutable_goal.v1 | 狀態物件、不可變目標、訓練範例 | triage 碼、人工標籤 | 必須保持狀態真實性為 pydantic 驗證、純文字僅供顯示、且經評估閘門控制。 |
| lazy-report-shame-shame-shame 擴充功能 | Pi message_end 強制執行 | 拒絕封包、渲染後的狀態、後續命令 | 最終狀態 JSON、延續帳本 | 必須拒絕遺失/無效的狀態 JSON，去除模型撰寫的狀態純文字，從驗證資料渲染，並排隊編譯後的延續/升級命令。 |
| status-json-check.mjs | 最終狀態提取與驗證器呼叫 | 帶有驗證後狀態物件的檢查器結果 | 助理文字 | 不得使用正則表達式、純文字標題、markdown、HTML 或 LLM 判斷來決定狀態有效性。 |
| agent_status_schema.py | pydantic 狀態合法性 | 解析通過/失敗 | 最終狀態 JSON | 必須使用 extra=forbid、型別化狀態酬載、規範性 triage 碼，以及僅在 continuing 上使用 not_done，使無效狀態變得不可表示。 |
| compile-status-command.mjs | 型別化狀態到命令的編譯 | 精確的後續命令或無命令 | pydantic 驗證的狀態物件 | 必須機械化地編譯 continuing/needs_* 酬載，並將終端/人類狀態編譯為無自動命令。 |
| agentic-evals | 保留的回歸證明 | 就緒報告 | 固定裝置與命令 | 如果正則/純文字狀態策略回歸或 pydantic 狀態不變量被削弱，必須失敗。 |
| ask | 意圖到 DAG 的編譯 | tau.dag_contract.v1、復原封包 | 狀態升級酬載 | 必須消費型別化的 needs_* 酬載，而非非正式的升級純文字。 |
| tau | DAG 執行與驗收 | 節點收據、tau.agent_handoff.v1/v2、目標雜湊 | DAG 合約、內嵌狀態物件 | 必須擁有不可變的目標雜湊與型別化的驗收收據；審查者的純文字不能取代驗收。 |
| project-watchdog | 排程調度 | tick 收據、證明閘門、鎖、延續帳本 | GitHub ticket、tau 判決 | 必須公開機器可讀的未完成工作，以便在 tickets/閘門/下一步仍未解決時，done 能夠失敗。 |
| ops-herdr | 跨工作階段傳輸 | 收件匣記錄、死信 | triage 碼 | 必須以帶有 triage 碼的型別化收件匣或死信記錄承載跨工作階段的失敗/狀態。 |
| ponytail | 生成極簡主義 | ponytail: 債務註解（非收據） | 不從收據世界消費任何東西 | 不得覆寫狀態、收據、證明或評估要求。 |
| Memory | 回憶 | 儲存/回憶回讀回應（非封包收據；回憶是觀察結果，絕不包裹） | 所有持久性資料 | 必須儲存 shame 範例、triage 解決方案和專案知識並支援回讀；回憶是觀察結果，非完成收據。 |
| agent-ecosystem | 元件所有權與收據邊界 | pi.receipt_envelope.v1 驗證 | 邊界酬載 | 必須發布所有權地圖，並要求在權限變更邊界處進行封包包裹。 |
| goal-helper | 以證明為中心的目標形狀 | 不可變目標提示/檢查清單 | 人類目標文字 | 必須將成功與主要證明、完成標準、允許範圍、禁止漂移、重試預算和停止條件掛勾。 |
pi.receipt_envelope.v1 - 邊界封包
僅在權限變更邊界處將酬載包裹在封包中：調度、交接、驗收、升級、關閉、持久失敗。 內部物件保持未包裹狀態（經審查的 YAGNI 裁決：沒有通用事件匯流排，不在每個工件上都放封包）。
{
"schema": "pi.receipt_envelope.v1",
"receipt_id": "stable-id",
"payload_schema": "pi.agent_status.v1",
"producer": "shame",
"emitted_at": "RFC3339",
"goal_hash": "sha256:<64hex> (optional)",
"parent_refs": [
{"receipt_id": "id", "expected_schema": "s", "expected_producer": "p", "digest": "sha256:<64hex> (optional)"}
],
"triage_code": "catalog or minted code (optional)",
"payload": {}
}
驗證方式：
skills/agent-ecosystem/run.sh validate <envelope.json>
echo '{...}' | skills/agent-ecosystem/run.sh validate -
由 scripts/receipt_envelope.py（pydantic，extra=forbid）強制執行的規則：
triage_code若存在，必須是 triage-error 目錄條目碼或鑄造的*_unclassified_<8hex>碼——與pi.agent_status.v1.failure相同的規則。goal_hash和parent_refs[].digest必須是sha256:+ 64 個小寫十六進位字元。parent_refs需要goal_hash：沒有共享目標的證據邊緣是不受信任的，會導致驗證失敗。- Pydantic 僅證明結構。參考解析是一個獨立的消費者端步驟，包含四個強制檢查：被引用的收據存在；其 schema 等於
expected_schema；其 producer 等於expected_producer；且resolved_parent.goal_hash == envelope.goal_hash（存在的雜湊在比較之前並非共享目標）。當設定了digest時，會套用摘要驗證。結構有效的封包並非已受信任的封包。 payload.schema在每個包裹的酬載中都是必需的，且必須等於封包的payload_schema；匿名酬載會導致驗證失敗。- 任何
extra=forbidschema 的欄位集合變更在本質上都是破壞性的；它們需要新的 schema 版本，絕不能原地編輯。
共享 JSON 欄位慣例
以下欄位是實際的共享表面。當一個元件發出或驗證與擁有者相同的名稱、形狀和語意時，該元件即「共享」該欄位。
| 欄位 | 形狀 | 擁有者 | 共享者 |
|---|---|---|---|
schema | 版本化 ID，例如 pi.agent_status.v1 | 各 schema 擁有者 | 每個合約物件；版本提升是新增或改名 |
code（triage） | 目錄條目或 <prefix>_unclassified_<8hex> | triage-error | shame failure.triage.code、封包 triage_code、herdr 死信、ask 復原封包 |
cause / next_command | 純字串 / 精確可執行的命令 | triage-error | 每個消費 triage 分類的物件；next_command 也是 shame continuing 的繼續執行欄位 |
goal_hash | sha256: + 64 個小寫十六進位字元 | tau（不可變目標封包） | shame 狀態（可選）、封包（可選）、每個 tau 節點收據 |
verified[] | {command, result} 配對 | shame | 狀態物件嵌入處的完成狀態證明 |
proof[] | 具體路徑/URL/ID；pi.agent_status.v1 中的本地路徑必須在 done 通過前存在 | shame | 狀態物件；watchdog 證明閘門命名相同的工件 |
parent_refs[] | {receipt_id, expected_schema, expected_producer, digest?} | agent-ecosystem 封包 | 升級證據（取代 needs_webgpt 中的 ad hoc 路徑） |
producer / receipt_id / emitted_at | 字串 / 穩定 ID / RFC3339 | agent-ecosystem 封包 | 任何邊界包裹的收據 |
payload_schema | 版本化 ID；若酬載宣告 schema，必須等於 payload.schema | agent-ecosystem 封包 | 任何邊界包裹的收據 |
| 終端判決 | PASS FAIL BLOCKED NEEDS_ATTENTION | tau | ask 加入點、watchdog 證明閘門、串流監控器 |
recoverable / not_this | 布林值 / 排除清單 | triage-error 目錄 | 決定重試與升級的消費者 |
triage-error 慣例（此處為規範性，實作在彼處）
- 一個原始訊號對應到一個
{code, cause, next_command}；層級邊界上的通用碼是錯誤，而非分類。 - 目錄條目存放於
skills/triage-error/failure_codes.json，包含{code, layer, match[], cause, next_command, recoverable, not_this[]}。 比對是確定性的：正規化精確為" ".join(text.lower().split())（轉小寫、所有空白序列收縮為單一空格、去除頭尾空格）； 當其任一match[]標記（同樣轉小寫）是正規化後訊息的子字串時，條目即符合； 當給定--layer時，會跳過不同layer的條目；依檔案順序第一個符合的條目獲勝。 絕不使用正則表達式或 LLM 判斷。 禁止作為終端分類（它們是症狀而非原因，必須從底層訊號重新 triage）：NEEDS_ATTENTION、BLOCKED、browser_handler_timeout、unknown_error、generic_failure， 以及任何裸終端判決詞。 - 未匹配的訊號會鑄造
<layer-or-unknown>_unclassified_<8hex>，其中 8 個十六進位字元為正規化訊息文字之 sha256 的前 8 個字元， 因此相同訊號總是鑄造相同碼。鑄造會開啟 ticket + agentic-eval + memory 迴圈。 重複閾值：相同鑄造碼的第二次觀察會觸發提升或別名化。別名表示法：目錄檔案中的頂層aliases對映 將鑄造碼對映到規範條目碼；因為鑄造是基於正規化訊息的確定性過程，重複訊號會重新鑄造相同碼， 分類器透過該對映解析到規範條目（記錄為aliased_from）；鑄造碼絕非第二個規範身份。 ticket/eval/memory 副作用按鑄造碼（以碼字串為鍵）為冪等。 - 每個命名失敗的生態系元件都使用目錄條目或鑄造碼。Pydantic 驗證器（狀態 schema、封包）在解析時強制執行此規則， 因此有效物件中不可能存在模糊標籤。
設計裁決（來自外部審查）
- 嚴格性適用於決策，而非觀察。保持原始證據寬鬆；保持已接受的結果嚴格。型別化的
unknown觀察是合法的；模糊的決策則否。 - 鑄造的
*_unclassified_*碼具有暫定生命週期：當它們重複出現時，提升至目錄或別名為現有碼；切勿讓它們無限制擴散。 - Schema 變更是累加性的；破壞性的形狀變更需使用新版本（
tau.agent_handoff.v2模式），絕不能原地編輯。 - 不應建置：通用治理事件匯流排、ponytail 註解的回執、Memory 回憶或內部重試的回執。
成員資格
技能或擴充功能透過在其 SKILL.md 中加入 ## Ecosystem 區段來加入生態系，該區段需命名：它產生哪些 schema、消費哪些 schema，以及哪些邊界事件被包裹在封包中。目前成員：shame、triage-error、tau、ask、project-watchdog、ops-herdr。Ponytail 按設計為相鄰角色。