Agent 生态系统
一个分层的治理循环。每个组件只拥有一个关注点；它们只通过类型化的 JSON 契约耦合，从不导入彼此的状态机。
不可变的 $shame 目标是 shame-deterministic-instruction-obedience-v1
(skills/shame/immutable_goal.json)：通过将指令服从和完成报告转换为类型化的 pydantic 验证契约、确定性扩展门以及保留的代理评估，使项目代理无法忽略明确指令。散文仅用于展示，不能决定成功与否。下面列出的每个生态系统成员都必须在其边界处维护该目标。
图
使用 $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[生成塑造]
PONY[ponytail\nYAGNI 阶梯，无收据]
end
subgraph TURN[Turn 层 - Pi 会话]
SHAME[shame 扩展\npi.agent_status.v1\n验证、编译、吞入]
TRIAGE[triage-error\n失败词汇表\ncode, cause, next_command]
end
subgraph WORK[工作流层]
ASK[ask\n将意图编译为 DAG 契约]
TAU[tau\n执行 DAG，拥有验收\n类型化节点收据，goal_hash]
end
subgraph OPS[运维层]
WD[project-watchdog\ncron 调度、租约、\n证明门、tick 收据]
HERDR[ops-herdr 桥\n收件箱、静默、\nTTL 死信]
end
MEM[(Memory\n训练示例、\n分类决议、\n项目知识)]
PONY -.-> SHAME
SHAME -->|failed.triage.code| TRIAGE
SHAME -->|needs_* 编译命令| ASK
ASK -->|tau.dag_contract.v1| TAU
TAU -->|节点收据 / handoff v2 携带状态| SHAME
WD -->|ticket_repair through ask| ASK
WD -->|读取判决| TAU
HERDR -->|死信分类代码| TRIAGE
SHAME -->|带标签的示例| MEM
TRIAGE -->|铸币代码| MEM
TAU -->|后运行导出不良节点收据| MEM
所有权表
| 组件 | 拥有 | 发出 | 消费 | 对于 $shame 不可变目标的必须行为 |
|---|---|---|---|---|
| 项目代理 | 在 turn 边界的指令服从 | pi.agent_status.v1 报告 | 操作员指令、工具结果、收据 | 必须将受保护的工作报告为类型化状态数据，对代理可执行的未完成工作使用 continuing.not_done[].next_command，并且绝不能将散文/提交/评审意见视为完成证明。 |
| triage-error | 失败词汇表 (failure_codes.json) | {code, cause, next_command} | 来自任何层的原始错误文本 | 必须使一个原始信号映射到一个目录或铸币代码；模糊的终端标签不能成为有效的决策。 |
| shame | turn 状态 (pi.agent_status.v1) 和 shame.immutable_goal.v1 | 状态对象、不可变目标、训练示例 | 分类代码、人工标签 | 必须保持状态真实性为 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、类型化状态有效载荷、规范的分类代码，并且 not_done 仅出现在 continuing 上。 |
| 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 工单、tau 判决 | 必须暴露机器可读的未完成工作，以便在工单/门/下一步未解决时 done 可以失败。 |
| ops-herdr | 跨会话传输 | 收件箱记录、死信 | 分类代码 | 必须将跨会话的失败/状态作为带有分类代码的类型化收件箱或死信记录携带。 |
| ponytail | 生成极简主义 | ponytail: 债务注释（非收据） | 收据世界中的任何内容 | 绝不能覆盖状态、收据、证明或评估要求。 |
| Memory | 回忆 | 存储/回忆回读响应（非信封收据；回忆是观察结果，永远不包装） | 所有持久化内容 | 必须存储 shame 示例、分类决议和项目知识并支持回读；回忆是观察结果，而不是完成收据。 |
| 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> (可选)",
"parent_refs": [
{"receipt_id": "id", "expected_schema": "s", "expected_producer": "p", "digest": "sha256:<64hex> (可选)"}
],
"triage_code": "目录或铸币代码 (可选)",
"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=forbid模式的字段集更改本质上是破坏性的； 它们需要一个新的模式版本，绝不能就地编辑。
共享 JSON 字段约定
以下字段是实际的共享表面。当一个组件发出或验证与所有者相同的名称、形状和语义时，该组件“共享”一个字段。
| 字段 | 形状 | 所有者 | 共享者 |
|---|---|---|---|
schema | 版本化 id，例如 pi.agent_status.v1 | 每个模式所有者 | 每个契约对象；版本升级是追加式或新名称 |
code（分类） | 目录条目或 <prefix>_unclassified_<8hex> | triage-error | shame failure.triage.code、信封 triage_code、herdr 死信、ask 恢复包 |
cause / next_command | 纯字符串 / 精确可运行命令 | triage-error | 每个分类的消费者；next_command 也是 shame 的 continuing 继续字段 |
goal_hash | sha256: + 64 个小写十六进制字符 | tau（不可变目标数据包） | shame 状态（可选）、信封（可选）、每个 tau 节点收据 |
verified[] | {command, result} 对 | shame | 嵌入状态对象的任何地方的完成状态证明 |
proof[] | 具体路径/URL/ID；pi.agent_status.v1 中的本地路径必须在 done 通过前存在 | shame | 状态对象；看门狗证明门命名相同的工件 |
parent_refs[] | {receipt_id, expected_schema, expected_producer, digest?} | agent-ecosystem 信封 | 升级证据（替换 needs_webgpt 中的临时路径） |
producer / receipt_id / emitted_at | 字符串 / 稳定 id / RFC3339 | agent-ecosystem 信封 | 任何边界包装的收据 |
payload_schema | 版本化 id；当有效载荷声明一个时必须等于 payload.schema | agent-ecosystem 信封 | 任何边界包装的收据 |
| 终端判决 | PASS FAIL BLOCKED NEEDS_ATTENTION | tau | ask 加入、看门狗证明门、流监控器 |
recoverable / not_this | bool / 排除列表 | 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 判断。 禁止作为终端分类（它们是症状而非原因，必须从底层信号重新分类）：NEEDS_ATTENTION、BLOCKED、browser_handler_timeout、unknown_error、generic_failure、 以及任何裸终端判决词。 - 不匹配的信号铸币
<layer-or-unknown>_unclassified_<8hex>，其中 8 个十六进制字符是标准化信号文本的 sha256 的前 8 个字符，因此相同的信号总是铸出相同的代码。铸币会打开工单 + agentic-eval + memory 循环。复发阈值：同一个铸币代码的第二次观察会触发提升或别名化。别名表示： 目录文件中的顶层aliases映射将铸币代码映射到规范代码；由于铸币在标准化信号上是确定性的，重复的信号会重新铸出相同的代码，分类器通过映射将其解析为规范条目（记录为aliased_from）；铸币代码永远不会成为第二个规范标识。工单/eval/memory 副作用按铸币代码是幂等的（以代码字符串为键）。 - 每个命名失败的生态系统组件都使用目录或铸币代码。pydantic 验证器（状态模式、信封）在解析时强制执行此操作，因此模棱两可的标签不可能存在于有效对象中。
设计裁决（来自外部评审）
- 严格性适用于决策，而非观察。保留原始证据的宽松性；保留已接受结果的严格性。类型化的
unknown观察是合法的；模棱两可的决策则不是。 - 铸币的
*_unclassified_*代码获得临时生命周期：在它们复发时提升到目录或别名化到现有代码；绝不让它们蔓延。 - 模式变更是追加式的；破坏性形状变更获得新版本（
tau.agent_handoff.v2模式），绝不就地编辑。 - 不要构建：通用治理事件总线；用于 ponytail 注释、Memory 召回或内部重试的收据。
成员资格
技能或扩展通过在其 SKILL.md 中添加 ## Ecosystem 部分来加入生态系统，命名：它产生哪些模式、消费哪些模式、以及将哪些边界事件包装在信封中。当前成员：shame、triage-error、tau、ask、project-watchdog、ops-herdr。Ponytail 按设计是相邻的。