{
  "contract_version": "1.1.0",
  "site": {
    "title": "UX Zondev",
    "origin": "https://ux.zondev.top",
    "updated_at": "2026-04-14",
    "purpose": "Provide durable UX guidance for humans and agents."
  },
  "documents": {
    "text_entry": "/llms.txt",
    "canonical": "/data/agent-contract.json",
    "overview": "/data/overview.json",
    "start": "/data/start.json",
    "map": "/data/map.json",
    "chapters": "/data/chapters.json",
    "methods": "/data/methods.json",
    "cases": "/data/cases.json",
    "skills": "/data/skills.json",
    "patterns": "/data/patterns.json",
    "patterns_compat": "/patterns",
    "sources": "/data/sources.json",
    "site_map": "/data/site-map.json",
    "read_order": [
      "/llms.txt",
      "/data/agent-contract.json",
      "/data/overview.json",
      "/data/start.json",
      "/data/skills.json",
      "/data/map.json",
      "/data/chapters.json",
      "/data/methods.json",
      "/data/cases.json",
      "/data/patterns.json",
      "/data/sources.json"
    ],
    "conflict_precedence": [
      "/data/agent-contract.json",
      "/data/overview.json",
      "/data/start.json",
      "/data/skills.json",
      "/data/map.json",
      "/data/chapters.json",
      "/data/methods.json",
      "/data/cases.json",
      "/data/patterns.json",
      "/data/sources.json",
      "/llms.txt"
    ],
    "collections": [
      {
        "path": "/start",
        "purpose": "按问题语句快速路由到对应技能包"
      },
      {
        "path": "/map",
        "purpose": "知识结构、体系地图与视觉图谱"
      },
      {
        "path": "/chapters",
        "purpose": "按主题系统阅读用户、心智、研究与行为"
      },
      {
        "path": "/methods",
        "purpose": "设计流程骨架、体验地图与设计工具"
      },
      {
        "path": "/cases",
        "purpose": "真实案例的公开证据层"
      },
      {
        "path": "/skills",
        "purpose": "可复用技能包：触发场景、清单、AI 指令、证据链"
      },
      {
        "path": "/patterns",
        "purpose": "兼容旧路径（已迁移到 /skills）"
      },
      {
        "path": "/sources",
        "purpose": "本地档案与公开来源的证据网"
      },
      {
        "path": "/start",
        "purpose": "问题到技能包的快速路由入口"
      },
      {
        "path": "/skills",
        "purpose": "固定 schema 的技能包集合页"
      }
    ]
  },
  "principles": [
    {
      "id": "clarity-before-intelligence",
      "rule": "先解释这是什么、给谁、为什么值得继续，再让人决定。"
    },
    {
      "id": "state-must-be-visible",
      "rule": "等待、执行、交接和失败时都必须持续暴露状态。"
    },
    {
      "id": "approval-before-impact",
      "rule": "外部发送、扣费、提交、覆盖、删除、发布等动作必须先明确确认。"
    },
    {
      "id": "recovery-is-part-of-the-flow",
      "rule": "失败时必须给出恢复路径、回退路径或人工接手入口。"
    }
  ],
  "roles": [
    {
      "id": "visitor",
      "label": "第一次进入的人",
      "must_see": [
        "这是什么",
        "给谁",
        "下一步",
        "是否值得继续"
      ]
    },
    {
      "id": "builder",
      "label": "正在改产品的人",
      "must_see": [
        "问题在哪一层",
        "该看哪类方法",
        "该用哪类审计工具"
      ]
    },
    {
      "id": "agent",
      "label": "执行中的 AI / Agent",
      "must_see": [
        "身份边界",
        "当前状态",
        "审批边界",
        "失败恢复规则"
      ]
    },
    {
      "id": "human-operator",
      "label": "人工接手者",
      "must_see": [
        "当前 owner",
        "已完成什么",
        "还差什么",
        "从哪里继续"
      ]
    }
  ],
  "task_types": [
    {
      "id": "homepage-clarity-audit",
      "start_from": [
        "/start",
        "/skills/first-screen-positioning",
        "/patterns/first-screen-positioning",
        "/methods"
      ],
      "must_return": [
        "定位判断",
        "主动作判断",
        "信息层级问题",
        "建议改法"
      ]
    },
    {
      "id": "service-chain-audit",
      "start_from": [
        "/start",
        "/methods",
        "/skills/recovery-and-human-handoff",
        "/patterns/recovery-and-human-handoff"
      ],
      "must_return": [
        "触点与角色",
        "状态暴露",
        "handoff 设计",
        "恢复路径"
      ]
    },
    {
      "id": "human-confirmation-design",
      "start_from": [
        "/skills/acceptance-before-human-confirmation",
        "/patterns/acceptance-before-human-confirmation",
        "/cases/task-system-v2-today-focus"
      ],
      "must_return": [
        "确认问题",
        "为何仍需要人",
        "AI 是否还能继续做",
        "下一步"
      ]
    },
    {
      "id": "service-recovery-audit",
      "start_from": [
        "/cases/openclaw-feishu-service-recovery",
        "/sources/openclaw-feishu-problem-map"
      ],
      "must_return": [
        "症状分层",
        "证据与根因",
        "P0 / P1 修复顺序",
        "验收条件"
      ]
    },
    {
      "id": "delivery-validation",
      "start_from": [
        "/cases/ux-site-homepage-iteration",
        "/data/agent-contract.json"
      ],
      "must_return": [
        "正式域名",
        "内容是否匹配 brief",
        "状态或回执是否可见",
        "失败时如何补救"
      ]
    }
  ],
  "state_models": {
    "experience": [
      {
        "id": "entry",
        "must_show": [
          "你是谁",
          "适合谁",
          "为什么值得继续"
        ],
        "fails_when": [
          "用户需要先追问页面是做什么的"
        ]
      },
      {
        "id": "decision",
        "must_show": [
          "唯一优先的下一步",
          "必要的分支说明"
        ],
        "fails_when": [
          "用户不知道先点哪里"
        ]
      },
      {
        "id": "execution",
        "must_show": [
          "当前状态",
          "进度或等待说明",
          "是否可取消或暂停"
        ],
        "fails_when": [
          "系统静默运行，用户只能猜"
        ]
      },
      {
        "id": "handoff",
        "must_show": [
          "现在是谁在处理",
          "为什么切换",
          "下一次可见更新点"
        ],
        "fails_when": [
          "跨系统、跨角色切换后责任不明"
        ]
      },
      {
        "id": "recovery",
        "must_show": [
          "失败原因",
          "补救动作",
          "人工接手入口"
        ],
        "fails_when": [
          "失败后没有出路"
        ]
      }
    ],
    "human_confirmation": [
      {
        "id": "confirmation_payload",
        "required_fields": [
          "目标",
          "现状",
          "差距",
          "AI还能做",
          "为何需要你",
          "请确认"
        ],
        "fails_when": [
          "任务只写了待确认，但没有明确确认问题"
        ]
      }
    ],
    "agent_task_lifecycle": [
      {
        "id": "captured",
        "required_fields": [
          "goal",
          "source",
          "owner"
        ],
        "fails_when": [
          "任务进入系统，但没有 owner 或来源"
        ]
      },
      {
        "id": "clarified",
        "required_fields": [
          "scope",
          "next_step",
          "acceptance_criteria"
        ],
        "fails_when": [
          "任务只有标题，没有下一步和验收标准"
        ]
      },
      {
        "id": "in_progress",
        "required_fields": [
          "current_status",
          "last_visible_update"
        ],
        "fails_when": [
          "系统在执行，但外部看不到任何状态"
        ]
      },
      {
        "id": "handoff_ready",
        "required_fields": [
          "current_owner",
          "next_owner",
          "handoff_reason",
          "resume_point"
        ],
        "fails_when": [
          "交接发生了，但下一位 owner 和恢复点不清楚"
        ]
      },
      {
        "id": "resolved",
        "required_fields": [
          "result_or_failure",
          "evidence",
          "next_path"
        ],
        "fails_when": [
          "系统结束了，但没有结果证据或恢复路径"
        ]
      }
    ]
  },
  "approval_policies": {
    "high_impact_actions": [
      "external_send",
      "charge",
      "submit",
      "overwrite",
      "delete",
      "publish",
      "permission_change"
    ],
    "rules": [
      "如果 agent 代替人执行动作，必须明确区分“建议”与“已执行”。",
      "长链路自动化中，要明确哪些步骤可以自动做，哪些必须人工点头。",
      "没有确认 payload 的任务，不能进入 human gate。"
    ],
    "representation_rules": [
      "审批前要暴露待执行动作、影响范围和回退方式。",
      "审批通过后，要把结果和证据写回可见状态。",
      "涉及主观判断、方向选择或真实世界动作时，不得默认替人拍板。"
    ]
  },
  "handoff": {
    "required_fields": [
      "current_owner",
      "next_owner",
      "handoff_reason",
      "current_state",
      "next_visible_update",
      "recovery_path"
    ],
    "failure_signals": [
      "责任切换后没有 owner",
      "交接后没有回执",
      "用户只能靠日志回忆现在轮到谁"
    ]
  },
  "recovery": {
    "required_fields": [
      "failure_reason",
      "what_completed",
      "what_failed",
      "retry_or_back_path",
      "human_takeover_path"
    ],
    "failure_signals": [
      "只说失败，不说怎么补救",
      "只给重试按钮，不说明原因",
      "人工接手入口缺失"
    ]
  },
  "delivery_definition": {
    "required_checks": [
      "bound_domain",
      "current_brief_match",
      "fresh_primary_asset",
      "critical_action_verified"
    ],
    "failure_signals": [
      "只给预览链接，没有给最终绑定域名",
      "页面可访问，但内容还是旧素材或旧主题",
      "关键动作没有被真实验证"
    ]
  },
  "retrieval": {
    "default_questions": [
      "问题发生在 entry、decision、execution、handoff 还是 recovery？",
      "这更像页面问题、流程问题，还是服务恢复问题？",
      "这一步是否需要人类明确审批或确认？",
      "应该先去 /start 分诊，还是直接看技能包、案例、方法或来源证据？"
    ],
    "routing": [
      {
        "need": "先做问题分诊",
        "read": [
          "/start",
          "/data/start.json"
        ]
      },
      {
        "need": "可复用技能包",
        "read": [
          "/skills",
          "/data/skills.json",
          "/data/patterns.json"
        ]
      },
      {
        "need": "设计流程",
        "read": [
          "/methods",
          "/data/methods.json"
        ]
      },
      {
        "need": "真实证据",
        "read": [
          "/cases",
          "/data/cases.json"
        ]
      },
      {
        "need": "来源与来路",
        "read": [
          "/sources",
          "/data/sources.json"
        ]
      },
      {
        "need": "任务 / 状态 / 审批 / 恢复协议",
        "read": [
          "/data/agent-contract.json"
        ]
      },
      {
        "need": "问题路由",
        "read": [
          "/start",
          "/data/start.json"
        ]
      },
      {
        "need": "技能包",
        "read": [
          "/skills",
          "/data/skills.json"
        ]
      }
    ]
  },
  "retrieval_guides": [
    {
      "page": "/start",
      "useWhen": "还不确定问题属于哪一类，或需要从用户语句快速路由",
      "returns": [
        "问题分类",
        "推荐技能",
        "下一步入口"
      ]
    },
    {
      "page": "/skills",
      "useWhen": "需要可即取即用的技能包与 AI 指令模板",
      "returns": [
        "触发场景",
        "检查清单",
        "输入输出",
        "可复制 prompt",
        "来源证据"
      ]
    },
    {
      "page": "/methods",
      "useWhen": "需要知道项目该按什么设计流程推进",
      "returns": [
        "流程骨架",
        "体验地图",
        "设计工具"
      ]
    },
    {
      "page": "/cases",
      "useWhen": "需要真实落地证据、失败样本或改法示例",
      "returns": [
        "问题 -> 干预 -> 结果"
      ]
    },
    {
      "page": "/patterns",
      "useWhen": "兼容旧路径调用",
      "returns": [
        "已映射到技能包模型"
      ]
    },
    {
      "page": "/sources",
      "useWhen": "需要判断这些规则的来源、方法来路和项目档案",
      "returns": [
        "世界准则",
        "本地经验",
        "反向关联"
      ]
    }
  ],
  "task_frames": [
    {
      "id": "homepage-clarity-audit",
      "trigger": "需要判断页面是否让陌生人看得懂",
      "startFrom": [
        "/start",
        "/skills/first-screen-positioning",
        "/patterns/first-screen-positioning",
        "/methods",
        "ux-clarity-audit"
      ],
      "checkFor": [
        "定位",
        "主动作",
        "信息层级",
        "是否在对用户说话"
      ]
    },
    {
      "id": "service-chain-audit",
      "trigger": "需要判断体验在哪个触点或交接点断掉",
      "startFrom": [
        "/start",
        "/methods#journey-map",
        "/skills/recovery-and-human-handoff",
        "/patterns/recovery-and-human-handoff",
        "ux-service-audit"
      ],
      "checkFor": [
        "触点",
        "状态",
        "交接",
        "恢复",
        "owner"
      ]
    },
    {
      "id": "skill-pack-selection",
      "trigger": "需要把具体问题归到可复用技能包",
      "startFrom": [
        "/start",
        "/skills",
        "/patterns",
        "/cases"
      ],
      "checkFor": [
        "问题是否重复出现",
        "是否跨页面",
        "是否跨角色或系统",
        "是否已有对应技能包"
      ]
    }
  ],
  "approval_rules_human": [
    "外部发送、扣费、提交、覆盖、删除、发布等高影响动作之前必须先确认。",
    "如果 agent 代替人执行动作，必须明确区分“建议”与“已执行”。",
    "长链路自动化中，要明确哪些步骤可以自动做，哪些必须人工点头。"
  ],
  "handoff_rules_human": [
    "每一次跨角色或跨系统切换，都要说明谁接手、接手后能看到什么。",
    "handoff 不是把人踢出流程，而是让责任和状态持续可见。"
  ],
  "recovery_rules_human": [
    "错误提示不能只说失败，要同时给原因、回退、重试或人工入口。",
    "恢复路径和成功路径一样需要被设计，而不是上线后再补。"
  ]
}