实体模型（人物 / 项目 / 任务）

完整规格见 00-product-spec.md

YZOS 将观察数据结晶为可浏览、可检索、可供给上层 AI 的实体档案，统一抽象为 Entity。首期实现三种：

实体	说明
`person`	联系人、自己、未识别发送者
`project`	代码仓库、工作线、产品
`task`	进行中的工作项、待办、AI 正在执行的任务

Tauri 预览 UI 的主要页面就是这三种实体的浏览与审查界面。

自主发现 vs 人工维护

实体有两个来源，自主发现是默认路径，人工维护是增强手段：

来源	触发	示例
自主发现	观察数据到达，实体引擎自动提取	聊天出现新 sender，创建未识别人物；Claude Code 打开 example-project，创建/更新项目；AI 持续 tool use，创建进行中任务
人工维护	用户在 Tauri UI 命名、合并、编辑	未识别「Code·小伟」，用户命名为「小伟」；合并两个重复项目

系统不依赖用户操作也能持续产出可用实体。用户命名/修正会加速收敛，但不是前提条件。

自我迭代维护

实体不是写一次就冻结的。YZOS 持续根据新观察数据自我更新：

新观察 -> 实体信号提取 -> 匹配已有实体?
                              |- 是 -> 更新 summary / last_seen / sightings / links / confidence
                              |- 否 -> 创建候选 -> 累积证据 -> 达到阈值 -> 晋升正式实体
                                        |
                              Cron 维护 -> 合并重复 / 归档过期 / 刷新摘要 / 修正关联
                                        |
                              下一轮观察 -> 继续迭代（闭环）

自我迭代的具体行为：

行为	说明
摘要重写	每次有新 sighting，本地模型增量重新生成 `entity.summary`（不是从头编造）
状态迁移	任务 `in_progress` -> `completed`（AI 工具会话结束且无后续 activity）；项目 `active` -> `archived`（30 天无活动）
置信度升降	同一 sender 出现 3 次，confidence 从 0.3 升到 0.7；长期无证据，降级或合并
自动合并	两个 project 指向同一 `repo_path`，cron 自动合并；同一 voiceprint cluster，关联到 person
自动晋升	未识别人物消息数超过 10 且跨 2 个 platform，自动生成 `display_name` 建议（仍标记 `unrecognized`，等用户确认）
关联刷新	person 在 Lark 聊到 example-project，自动创建 person-project link
矛盾修正	新证据与旧 summary 冲突，标记 `needs_review`，cron 触发摘要重写

人工操作（命名、合并、删除）作为覆盖信号写入 entity_overrides，优先级高于自动推断，但只锁定被覆盖的字段，不阻断其他字段的自动迭代。

统一实体结构

每种实体在 PG 中共享基础字段，扩展字段放 JSONB：

CREATE TABLE entities (
    id              TEXT PRIMARY KEY,
    kind            TEXT NOT NULL,  -- person | project | task
    display_name    TEXT NOT NULL,
    status          TEXT NOT NULL DEFAULT 'active',
    summary         TEXT NOT NULL DEFAULT '',
    first_seen_at   TIMESTAMPTZ,
    last_seen_at    TIMESTAMPTZ,
    message_count   INTEGER NOT NULL DEFAULT 0,
    sighting_count  INTEGER NOT NULL DEFAULT 0,
    confidence      REAL NOT NULL DEFAULT 0.0,
    discovery_kind  TEXT NOT NULL DEFAULT 'auto',  -- auto | manual | merged
    needs_review    BOOLEAN NOT NULL DEFAULT FALSE,
    tags            TEXT[] NOT NULL DEFAULT '{}',
    aliases         TEXT[] NOT NULL DEFAULT '{}',
    metadata        JSONB NOT NULL DEFAULT '{}',
    okf_path        TEXT,
    embedding       vector(384),
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_entities_kind ON entities (kind, last_seen_at DESC);
CREATE INDEX idx_entities_status ON entities (kind, status);
CREATE INDEX idx_entities_confidence ON entities (kind, confidence DESC);

候选实体（晋升前）

自主发现时，证据不足的先进入候选池，避免垃圾实体污染正式库：

CREATE TABLE entity_candidates (
    id              TEXT PRIMARY KEY,
    kind            TEXT NOT NULL,
    hypothesized_name TEXT NOT NULL,
    confidence      REAL NOT NULL DEFAULT 0.0,
    evidence_count  INTEGER NOT NULL DEFAULT 0,
    evidence        JSONB NOT NULL DEFAULT '[]',  -- [{source_kind, source_id, signal, at}]
    promotion_threshold REAL NOT NULL DEFAULT 0.6,
    status          TEXT NOT NULL DEFAULT 'accumulating',  -- accumulating | promoted | discarded
    promoted_entity_id TEXT,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

晋升规则（默认）：

实体	晋升条件
person	同一 `platform_id` 出现 3 次及以上，或跨 2 个 `source_kind` 出现
project	确认 `repo_path` 或 AI 工具 `project_path` 一致 2 次及以上
task	AI tool use 序列 2 步及以上，或聊天/语音中明确提及工作项

迭代审计

每次自动更新留痕，供审查 UI 和调试：

CREATE TABLE entity_revisions (
    id          TEXT PRIMARY KEY,
    entity_id   TEXT NOT NULL REFERENCES entities(id),
    revision_kind TEXT NOT NULL,  -- summary_update | status_change | merge | link_add | confidence_change
    old_value   JSONB,
    new_value   JSONB NOT NULL,
    trigger     TEXT NOT NULL,    -- triage | cron:entity_rollup | manual | reconcile
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

人工覆盖

CREATE TABLE entity_overrides (
    entity_id   TEXT NOT NULL REFERENCES entities(id),
    field       TEXT NOT NULL,     -- display_name | status | merge_into | ...
    value       JSONB NOT NULL,
    set_by      TEXT NOT NULL DEFAULT 'user',
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    PRIMARY KEY (entity_id, field)
);

覆盖字段不再被自动迭代修改；其他字段继续自我更新。

实体之间的关联：

CREATE TABLE entity_links (
    source_id   TEXT NOT NULL REFERENCES entities(id),
    target_id   TEXT NOT NULL REFERENCES entities(id),
    link_kind   TEXT NOT NULL,  -- works_on | involves | blocks | related | spawned_by
    weight      REAL NOT NULL DEFAULT 1.0,
    evidence    JSONB NOT NULL DEFAULT '{}',
    PRIMARY KEY (source_id, target_id, link_kind)
);

实体与原始观察数据的关联：

CREATE TABLE entity_sightings (
    id              TEXT PRIMARY KEY,
    entity_id       TEXT NOT NULL REFERENCES entities(id),
    source_kind     TEXT NOT NULL,  -- activity | chat | ai_tool | voice
    source_id       TEXT NOT NULL,
    platform        TEXT,           -- wechat | telegram | lark | ghostty | claude-code ...
    context_summary TEXT NOT NULL DEFAULT '',
    seen_at         TIMESTAMPTZ NOT NULL,
    metadata        JSONB NOT NULL DEFAULT '{}'
);

人物（Person）

人物详情页把身份、活动、通讯数据汇总在一起呈现。

分类

分组	status	说明
你	`self`	用户自己，唯一
联系人	`recognized`	已命名、已确认的人物
未识别	`unrecognized`	见过但未命名，等用户确认或自动推断

人物档案字段

{
  "id": "person-self",
  "kind": "person",
  "display_name": "小明",
  "status": "self",
  "tags": ["@xiaoming", "夜猫子", "阿明"],
  "message_count": 17,
  "first_seen_at": "2026-06-11T14:45:00+04:00",
  "last_seen_at": "2026-06-25T11:15:00+04:00",
  "metadata": {
    "avatar_letter": "明",
    "voiceprint_status": "not_enrolled",
    "platforms_seen": {
      "wechat": 17,
      "telegram": 3,
      "lark": 5
    },
    "chat_accounts": [
      {"platform": "telegram", "username": "night_owl_dev", "id": "1000000001"}
    ]
  }
}

人物详情页（Tauri 预览 UI）

+-----------------------------------------------------------------+
| 人物 - 已识别 381 人                                             |
| [按姓名、别名或账号搜索...]                                       |
+---------------+---------------------------------------------------+
| 你            |  [明] 小明  自己                                  |
|  · 小明  OK   |  @xiaoming  夜猫子  阿明                          |
|               |  +--------+ +--------+ +--------+                |
| 联系人(3)     |  |消息数 17| |首次出现| |最近一次|                |
|  · 小红       |  |        | |6月11日 | |2天前  |                |
|  · 小刚       |  +--------+ +--------+ +--------+                |
|  · 小丽       |                                                   |
|               |  YZOS 在哪里见过 ta                               |
| 未识别(377)   |  微信  ################  17                       |
|  · 小华       |                                                   |
|  · Code·小伟  |  活动 session (7)                                 |
|  · ...        |  +-------------------------------------------+    |
|               |  | 微信,Telegram,Ghostty,Chrome,Lark          |    |
|               |  | 6月25日 11:15 - 最近 2天前               > |    |
|               |  +-------------------------------------------+    |
|               |  | 微信,Telegram,Ghostty,Chrome,QQ          > |    |
|               |  +-------------------------------------------+    |
|               |                                                   |
|               |  声纹  未录入  [录 10 秒]                          |
|               |  录一小段声音，YZOS 才能在共用麦克风时区分你和其他人 |
|               |                                                   |
|               |  聊天账号                                          |
|               |  Telegram  night_owl_dev (1000000001)             |
+---------------+---------------------------------------------------+

人物识别来源

来源	提取方式
聊天消息	`sender_id` / `sender_name`，创建或关联 entity
活动 OCR	聊天窗口中的发言者名称
语音 diarization	speaker cluster，匹配声纹库或标记未识别
会议转录	参会者名称
用户手动命名	`unrecognized`，确认后变为 `recognized`

声纹

CREATE TABLE voiceprints (
    entity_id    TEXT PRIMARY KEY REFERENCES entities(id),
    embedding    vector(256) NOT NULL,
    sample_path  TEXT NOT NULL,
    enrolled_at  TIMESTAMPTZ NOT NULL,
    duration_ms  INTEGER NOT NULL
);

用户通过 Tauri UI「录 10 秒」录入自己的声纹。办公室场景中，YZOS 用声纹区分「你」和其他说话人，避免面对面对话被误判到你身上。

项目（Project）

从代码仓库路径、窗口标题、AI 工具会话、聊天内容中自动识别项目实体。

识别来源

来源	示例
Git 仓库路径	`/Users/you/code/example-project` -> `example-project`
AI 工具会话	Claude Code project path
窗口标题 / OCR	「内部管理后台」
聊天提及	Lark 群讨论「internal-dashboard DNS」
用户手动	设置中关联目录

项目档案示例

{
  "id": "project-example-project",
  "kind": "project",
  "display_name": "示例项目",
  "status": "active",
  "summary": "统一示例服务，近期 SAML/OIDC 认证集成与生产故障恢复。",
  "first_seen_at": "2026-05-01T00:00:00+04:00",
  "last_seen_at": "2026-06-27T18:00:00+04:00",
  "tags": ["java", "k8s", "auth"],
  "metadata": {
    "repo_path": "/Users/you/code/example-project",
    "project_line": "internal-tools",
    "platforms_seen": {
      "ghostty": 45,
      "google_chrome": 30,
      "claude-code": 20
    },
    "ai_tools_active": ["claude-code"],
    "related_people": ["person-xiaohong", "person-xiaoli"],
    "open_tasks_count": 3
  }
}

项目详情页（Tauri 预览 UI）

+-----------------------------------------------------------------+
| 项目 - 已识别 24 个                                              |
+---------------+---------------------------------------------------+
| 活跃(8)       |  示例项目                                        |
|  · 示例项目  OK|  internal-tools 项目线                           |
|  · internal-  |  +--------+ +--------+ +--------+                |
|    dashboard  |  |活跃 7天| |AI工具  | |进行中  |                |
|  · billing-   |  |        | |Claude  | |任务 3  |                |
|    service    |  +--------+ +--------+ +--------+                |
|               |                                                   |
| 近期(12)      |  摘要                                             |
| 归档(4)       |  SAML ACS URL 修复、OIDC 兼容、生产 DB 恢复        |
|               |                                                   |
|               |  YZOS 在哪里见过它                                |
|               |  Ghostty      #########  45h                     |
|               |  Chrome       ######     30h                     |
|               |  Claude Code  ####       20h                     |
|               |                                                   |
|               |  关联人物                                         |
|               |  小红 (Lark)  ·  小丽 (微信)                      |
|               |                                                   |
|               |  进行中任务 (3)                                   |
|               |  · SAML ACS URL 修复  claude-code  进行中       > |
|               |  · DB 迁移方案       待开始                      > |
|               |                                                   |
|               |  相关知识 (5)                                     |
|               |  · SAML ACS URL 缺少 base_url 前缀              > |
+---------------+---------------------------------------------------+

任务（Task）

从 AI 工具执行、终端命令、聊天安排、语音讨论中识别工作项。

识别来源

来源	示例
AI 工具 tool use	Claude Code `Edit src/auth/saml.py`
AI 自主执行	Codex 持续跑测试
聊天安排	Lark「明天推进 DB 迁移」
语音讨论	「下午把证书巡检逻辑修了」
活动推断	同一项目连续 3 天做同一件事

任务状态

status	说明
`in_progress`	进行中（AI 工具活跃 / 用户正在做）
`pending`	待开始（从聊天/语音中提取的计划）
`completed`	已完成
`blocked`	阻塞中
`stale`	长期无活动，待归档

任务档案示例

{
  "id": "task-saml-acs-fix",
  "kind": "task",
  "display_name": "SAML ACS URL 修复",
  "status": "in_progress",
  "summary": "修复 SAML ACS URL 缺少 base_url 前缀，前端同步 use_absolute_acs_url 标志。",
  "first_seen_at": "2026-06-27T14:30:00+04:00",
  "last_seen_at": "2026-06-27T15:45:00+04:00",
  "tags": ["saml", "auth"],
  "metadata": {
    "project_id": "project-example-project",
    "executor": "claude-code",
    "executor_status": "autonomous",
    "involved_people": [],
    "tool_uses": [
      {"tool": "Edit", "target": "src/auth/saml.py"},
      {"tool": "Bash", "command": "pytest tests/auth/"}
    ],
    "source": "ai_tool_session"
  }
}

任务详情页（Tauri 预览 UI）

+-----------------------------------------------------------------+
| 任务 - 进行中 12 · 待开始 5                                      |
+---------------+---------------------------------------------------+
| 进行中(12)    |  SAML ACS URL 修复                                |
|  · SAML  OK   |  示例项目 · Claude Code · 进行中                  |
|  · DNS监控    |  +--------+ +--------+ +--------+                |
|  · DB迁移     |  |开始    | |持续    | |Tool use|                |
|               |  |6月27日 | |1h 15m  | | 8 次   |                |
| 待开始(5)     |  +--------+ +--------+ +--------+                |
| 已完成(今日3) |                                                   |
|               |  摘要                                             |
|               |  修复 SAML ACS URL 缺少 base_url 前缀...          |
|               |                                                   |
|               |  执行者                                           |
|               |  Claude Code（自主执行中，用户已切到其他 app）     |
|               |                                                   |
|               |  Tool Use 时间线                                  |
|               |  14:32  Edit src/auth/saml.py                     |
|               |  14:45  Bash pytest tests/auth/ -> passed          |
|               |                                                   |
|               |  关联项目 -> 示例项目                              |
|               |  关联知识 -> SAML ACS URL 前缀问题                 |
+---------------+---------------------------------------------------+

实体引擎（自主发现 + 自我迭代）

独立模块 entity_engine，在 Triage 和 Cron 两个阶段运行。

实时发现（Triage 内嵌）

每次观察 session 结束后，同步执行：

1. Signal Extractor - 从 OCR/聊天/AI日志/语音中提取实体信号
   person:  {platform, platform_id, display_name?, voice_cluster?}
   project: {repo_path?, window_title?, ai_project_path?, keywords[]}
   task:    {action_verb, target_file?, ai_tool_uses[], chat_intent?}

2. Entity Matcher - 与已有 entities / candidates 匹配（embedding + 规则）
   相似度 > 0.85   -> 同一实体
   0.6 - 0.85       -> 候选池累积
   < 0.6            -> 新候选

3. Entity Updater - 更新正式实体或候选
   - UPSERT sighting
   - 增量重写 summary（本地模型，输入=旧 summary + 新证据）
   - 刷新 confidence、last_seen、links
   - 检查 entity_overrides，跳过被人工锁定的字段

4. OKF Writer - 同步写 entities/{kind}/{id}.md
5. Indexer - 更新 PG embedding

定时自我维护（Cron）

任务	调度	自我维护行为
`entity_rollup`	每天 02:00	所有实体 summary 全量重写（基于近期 sightings 聚合）
`entity_merge`	每周	高置信度重复实体自动合并（同 `repo_path`、同 voiceprint、同 `platform_id`）
`entity_promote`	每小时	候选池达阈值，晋升正式实体
`entity_demote`	每天	长期无证据的正式实体，降级/归档/丢弃
`entity_archive`	每天	任务 `completed` / 项目 30 天无活动，归档为 `archived`
`entity_link_refresh`	每天	从共现分析刷新 person-project-task 关联
`entity_reconcile`	每天	OKF 实体档案与 PG 对账
`entity_review_scan`	每天	标记矛盾/低置信度实体为 `needs_review`，Tauri UI 高亮

自我迭代闭环

flowchart TD
    O[Observe] --> T[Triage + Entity Engine]
    T --> M{匹配}
    M -->|已有实体| U[增量更新 summary/links/confidence]
    M -->|候选| C[entity_candidates 累积证据]
    C -->|达阈值| P[晋升 -> entities]
    M -->|新信号| C
    U --> OKF[OKF + PG Index]
    P --> OKF
    OKF --> S[MCP 供上层 AI]
    OKF --> UI[Tauri 预览]
    CRON[Cron 自我维护] --> U
    CRON --> MERGE[自动合并/归档/晋升]
    MERGE --> OKF
    USER[用户命名/修正] --> OV[entity_overrides]
    OV -.->|锁定字段| U
    O --> CRON

实体结晶流程（端到端）

flowchart TD
    A[Observe 原始数据] --> B[Signal Extractor]
    B --> C{匹配已有实体?}
    C -->|是| D[增量更新 + sighting]
    C -->|候选| E[累积 evidence]
    C -->|否| E
    E --> F{达晋升阈值?}
    F -->|是| G[创建正式 entity]
    F -->|否| H[留候选池]
    D --> I[重写 summary + 刷新 links]
    G --> I
    I --> J[OKF 档案 + PG embedding]
    J --> K[Tauri 预览 / MCP 供料]
    L[Cron 自我维护] --> I
    L --> M[合并/归档/晋升/对账]

MCP 供料示例

上层 AI（Claude Code）问「示例项目现在什么情况」：

-> yzos_entity_get(id="project-example-project")
<- {summary, open_tasks: [task-saml-acs-fix, ...], related_people: [...]}

-> yzos_entity_search(kind="task", project="example-project", status="in_progress")
<- [{display_name: "SAML ACS URL 修复", executor: "claude-code", ...}]

上层 AI 问「今天和谁聊过」：

-> yzos_entity_list(kind="person", since="today")
<- [{display_name: "小红", message_count: 12, platforms: ["wechat"]}, ...]