# ============================================================
# agent-radar · 项目档案 Schema
# ------------------------------------------------------------
# 本文件有双重身份：
#   1) 人类阅读的填写规范（desc / note 字段）
#   2) scripts/new_project.py 的机器可读骨架生成源
# 改结构时两处要同步，否则脚本生成的空档案会缺字段。
#
# 五维度设计意图：
#   业务(business)  — 它靠什么活着、为谁活着
#   场景(scenario)  — 它在什么场合被用、产出什么
#   技术(tech)      — 它怎么做到的、抽象在哪一层
#   生态(ecosystem) — 它的社区动能（多数字段由脚本自动刷新）
#   风险(risk)      — 它的坑在哪、宣称与实测的落差
# 其中 risk.claim_vs_reality 是全套 schema 里最不该留空的字段：
# 它逼着每篇分析去核实「项目方宣称 vs 实际状态」，防止文章退化成 README 复读。
# ============================================================

version: 1

# ---------- 枚举值 ----------
enums:
  status: [active, watch, archived]          # active=持续追踪 watch=观察中 archived=停更归档
  openness: [L1, L2, L3, L4]                 # 许可证成色分级，详见 license-tiers.yaml
  vendor_type: [startup, bigtech, community, solo, unknown]
  interaction_mode: [cli, ide-plugin, desktop-app, web-app, api, editor-fork]
  human_in_the_loop: [autonomous, approval-gated, supervised, manual]
  maturity: [concept, preview, beta, stable, mature]
  model_binding: [locked, preferred, byom, neutral]   # locked=仅自家模型 byom=自带模型 neutral=完全中立
  visibility: [public, private, none]

# ---------- 字段定义 ----------
# type 用于脚本生成占位值：str->""  int->0  bool->false  list->[]  dict->{}
fields:

  # ===== 顶层标识 =====
  id:            {type: str,  required: true,  desc: "档案唯一标识，小写连字符，如 ipollowork"}
  name:          {type: str,  required: true,  desc: "项目显示名"}
  repo:          {type: str,  required: true,  desc: "GitHub 仓库 owner/name"}
  homepage:      {type: str,  required: false, desc: "官网"}
  added_at:      {type: str,  required: true,  desc: "收录日期 YYYY-MM-DD"}
  status:        {type: str,  required: true,  enum: status, desc: "追踪状态"}

  # ===== 身份层 =====
  identity:
    tagline:     {type: str,  required: true,  desc: "一句话定位，优先用官方原文"}
    vendor:      {type: str,  required: false, desc: "背后公司/组织"}
    vendor_type: {type: str,  required: false, enum: vendor_type}
    region:      {type: str,  required: false, desc: "团队所在地，如 中国/美国/欧洲"}
    first_seen:  {type: str,  required: false, desc: "首次公开时间"}

  # ===== 业务维度 =====
  business:
    positioning: {type: str,  required: true,  desc: "它在产业链里到底站在哪一层"}
    target_users: {type: list, required: true, desc: "目标用户群"}
    monetization: {type: str, required: true,  desc: "变现方式：捐赠/商业授权/SaaS/双轨/未定"}
    license:
      spdx:      {type: str,  required: true,  desc: "SPDX 标识，如 MIT / Apache-2.0 / NOASSERTION"}
      name:      {type: str,  required: true,  desc: "许可证实际名称"}
      openness:  {type: str,  required: true,  enum: openness, desc: "成色分级 L1-L4"}
      redistributable: {type: bool, required: true, desc: "可否公开再分发 —— 直接决定镜像可见性"}
      key_restrictions: {type: list, required: false, desc: "关键限制条款原文要点"}
    moat:        {type: str,  required: false, desc: "护城河/不可轻易复制的部分"}
    competitive_risk: {type: str, required: false, desc: "最容易被谁替代、为什么"}

  # ===== 场景维度 =====
  scenario:
    primary:     {type: list, required: true,  desc: "核心场景"}
    typical_use_cases: {type: list, required: true, desc: "典型用例，写给读者看的具体例子"}
    industries:  {type: list, required: false, desc: "行业落点"}
    interaction_mode: {type: list, required: true, enum: interaction_mode, desc: "交互形态，可多选"}
    human_in_the_loop: {type: str, required: true, enum: human_in_the_loop, desc: "人机协作模式"}
    deliverables: {type: list, required: true, desc: "交付物类型：code/doc/ppt/website/design/video/data/report"}

  # ===== 技术维度 =====
  tech:
    form_factor: {type: str,  required: true,  desc: "产品形态：CLI/IDE插件/桌面应用/Web平台/库"}
    stack:       {type: list, required: true,  desc: "技术栈"}
    engine_abstraction:
      supported: {type: list, required: false, desc: "支持的 agent 引擎/runtime"}
      mechanism: {type: str,  required: false, desc: "统一接入机制描述"}
      abstraction_layer: {type: str, required: false, desc: "抽象层名称，如 Engine Protocol"}
      depth_notes: {type: str, required: false, desc: "**关键**：各引擎接入深度是否对等，逐个说明"}
    extension_system:
      skills:    {type: str,  required: false, desc: "Skills 支持情况"}
      plugins:   {type: str,  required: false, desc: "插件机制"}
      mcp:       {type: str,  required: false, desc: "MCP 支持方式"}
    model_binding: {type: str, required: true, enum: model_binding, desc: "模型绑定程度"}
    local_first: {type: bool, required: true,  desc: "是否可完全本地运行"}
    multi_agent: {type: str,  required: false, desc: "多 Agent 编排方式"}
    permission_sandbox: {type: str, required: false, desc: "权限审批与沙箱机制"}
    observability: {type: str, required: false, desc: "执行过程可观测性"}

  # ===== 生态维度（metrics 由 fetch_stats.py 自动刷新，勿手填） =====
  ecosystem:
    metrics:
      stars:         {type: int,  auto: true}
      forks:         {type: int,  auto: true}
      open_issues:   {type: int,  auto: true}
      subscribers:   {type: int,  auto: true}
      created_at:    {type: str,  auto: true}
      pushed_at:     {type: str,  auto: true}
      size_kb:       {type: int,  auto: true}
      languages:     {type: dict, auto: true}
      latest_release: {type: str, auto: true}
      release_cadence: {type: str, auto: true}
      data_date:     {type: str,  auto: true, desc: "本组数据的抓取日期"}
      stale:         {type: bool, auto: true, desc: "true=本次抓取失败，沿用上次快照"}
    community:     {type: str,  required: false, desc: "社区形态与活跃度"}
    standards:     {type: list, required: false, desc: "采纳/挂靠的标准与联盟，如 OPEA/OpenSSF"}
    notable_events: {type: list, required: false, desc: "关键事件与时间点"}

  # ===== 风险维度 =====
  risk:
    license_risk:  {type: str,  required: true,  desc: "许可证带来的使用/分发风险"}
    vendor_lockin: {type: str,  required: false, desc: "供应商锁定点"}
    # 结构化三项式：claim / actual / source。不用裸字符串，
    # 因为 build_matrix.py 要把它渲染成表格，且缺 source 的断言无法复核。
    claim_vs_reality: {type: list, required: true, desc: "**必填**：每项为 {claim, actual, source} 三项，写清 宣称/实际/证据来源"}
    maturity:      {type: str,  required: true,  enum: maturity}

  # ===== 象限图坐标（0-10，人工评定，供 build_matrix.py 出图） =====
  # 评分是主观判断，但一旦统一口径，横向比较就成立了。
  # 评完请回头看一眼：如果所有项目都打 9 分，说明这套轴失去了区分度。
  chart:
    form_depth:        {type: int, required: false, desc: "形态纵深：0=单点工具 10=统一工作台"}
    engine_neutral:    {type: int, required: false, desc: "引擎立场：0=绑定单引擎 10=多引擎中立"}
    local_first_score: {type: int, required: false, desc: "本地优先：0=强云依赖 10=完全本地可跑"}
    deliverable_depth: {type: int, required: false, desc: "交付物纵深：0=只出代码 10=多模态可编辑产出"}

  # ===== 结论 =====
  verdict:
    one_liner:      {type: str, required: true,  desc: "一句话结论，进总纲索引表"}
    who_should_use: {type: str, required: true}
    who_should_not: {type: str, required: true}

  # ===== 镜像与文章回写 =====
  mirror:
    gitea_repo:  {type: str,  required: false, desc: "gitinbox 下的镜像仓，如 gitinbox/iPolloWork"}
    visibility:  {type: str,  required: false, enum: visibility}
    upstream:    {type: str,  required: false}
    last_sync:   {type: str,  required: false}
    sync_note:   {type: str,  required: false, desc: "如体积过大改用 treeless clone 等降级说明"}

  article:
    emlog_id:    {type: int,  required: false, desc: "emlog 文章 ID，发布后回写"}
    published_at: {type: str, required: false}
    url:         {type: str,  required: false}