# Workspace Curated Timeline MVP 更新时间：2026-05-21 ## 1. MVP 一句话定义 MVP 提供一条默认可展示的 workspace curated timeline： ```text AI 实时生成草稿，人工可以确认、编辑、隐藏和补充；原始证据只用于编辑追溯，不做复杂 AI 建议系统。 ``` MVP 的核心目标不是让 AI 一次生成最终 RCA 级别 timeline，而是让紧急 case 中的 workspace 页面能实时展示“足够有用、可编辑、可追溯”的最新进展。 ## 2. 用户价值 MVP 要解决三个问题： 1. 默认页不能再展示噪声很高的 raw event feed。 2. 紧急处理中，用户打开 workspace 要能看到 AI 自动整理出的最新进展草稿。 3. 人工可以快速把草稿修成正式 timeline，并且后续 AI 不会覆盖人工内容。 ## 3. MVP 包含什么 ### 3.1 默认 Curated Timeline 默认 workspace timeline 页面展示 curated entries： - `draft`: AI 自动生成，默认可见，带 `AI draft` 标记。 - `confirmed`: 人工确认、人工新增或人工编辑后的正式 entry。 默认不展示： - `hidden` - `superseded` hidden entry 表示用户明确不希望展示该 entry。后续 AI draft generation 必须尊重 hidden 记录，不能基于同一组 evidence 反复生成相同 draft。 排序： ```text ORDER BY occurred_at ASC, sort_order ASC, id ASC ``` 第一版不支持完全自由拖拽排序。用户主要通过编辑 `occurred_at` 修正事实时间；`sort_order` 只处理同一时间点内的展示顺序。 ### 3.2 人工操作 MVP 支持： - 新增 timeline entry。 - 编辑 timeline entry。 - 确认 AI draft。 - 隐藏 entry。 - 给 entry 绑定 evidence。 - 从 evidence 创建 entry。 人工新增和人工编辑后的 entry 都视为正式内容。 AI 不能覆盖： - 人工新增 entry。 - 人工编辑过的 entry。 - 人工确认过且后续人工编辑过的 entry。 当新 evidence 与已有 confirmed entry 描述的是同一事件时，MVP 不创建重复 draft。系统可以把 evidence 绑定到 confirmed entry，或在 entry metadata 中记录 unreviewed supporting evidence，但不能自动修改 confirmed entry 正文。 ### 3.3 Evidence Stream 编辑模式 默认页不展示 raw evidence。 用户进入编辑模式后，展示： ```text 左侧：Evidence Stream 右侧：Curated Timeline ``` 左侧 evidence 支持： - 按 source 过滤。 - 按 issue key 过滤。 - 按时间范围过滤。 - 查看原始内容。 - 查看是否已绑定到 entry。 右侧 timeline 支持： - 新增 entry。 - 编辑 entry。 - 确认 draft。 - 隐藏 draft。 - 绑定 evidence。 ### 3.4 Jira Evidence 增量同步 Jira issue/comment 是 MVP 的核心 evidence 来源之一。 同步流程： ```text workspace bound issue -> fetch issue lightweight metadata -> if issue updated, fetch changed comments with overlap -> upsert workspace_timeline_evidence -> trigger AI draft generation for new/changed evidence ``` 同步必须避免每次全量拉 comments。 如果 Jira API 支持 comment `updated_at` 增量查询，优先使用。 如果不支持： - 从最新 comment page 往前扫描到 overlap window。 - overlap 起点默认为 `last_seen_comment_updated_at - 24h`。 - overlap window 内全部 comment 重新计算 hash 并 upsert。 - 不采用“遇到第一个 unchanged comment 就停止”的策略。 ### 3.5 DevOps Evidence 增量同步 MVP 需要接入 DevOps 深度操作记录，作为 curated timeline 的 evidence 来源。 MVP 范围内的 DevOps evidence 包括： - workspace 绑定集群的 operation records。 - workspace 绑定集群的 config change records。 - operation/config change 的状态、申请人、原因、参数、输出、创建时间、完成时间。 - 如果 evict leader、scale、restart、failover 等操作已经记录在 DevOps operation/config change 中，则作为 evidence 同步。 MVP 不要求从 DevOps 之外推断操作事实。例如： - 不从 TiKV live store state 推断操作。 - 不从 monitoring 指标推断操作。 - 不从 AWS incident 自动补全操作背景。 同步流程： ```text workspace bound cluster -> fetch cluster metadata -> fetch operations/config changes since last sync with overlap -> refetch non-terminal operations/config changes until terminal -> upsert workspace_timeline_evidence -> trigger AI draft generation for new/changed evidence ``` DevOps evidence 写入统一的 `workspace_timeline_evidence` 表： ```text source = devops source_type = devops_operation | devops_config_change source_key = /operation/ source_key = /config-change/ ``` DevOps operation/config change 的原始 payload 保存在 `metadata_json` 中，供编辑模式追溯。 DevOps 增量同步必须处理“创建后状态变化”： - 如果 DevOps API 支持 `updated_at` cursor，优先按 `updated_at` 增量。 - 如果只支持 `created_at` 查询，则对未终态记录持续 refetch，直到进入 terminal state。 - terminal state 的具体枚举以 DevOps API 返回 schema 或配置映射为准。 - 未识别状态默认按 non-terminal 处理，但必须有最大 refetch TTL，避免无限轮询。 - MVP 默认最大 refetch TTL 为 7 天；超过 TTL 后停止高频 refetch，并在 evidence `metadata_json` 中记录 `terminal_state_unknown=true`。 ### 3.6 AI Draft Generation AI 对新增或变化的 evidence 生成 draft timeline entry。 AI 输入： - 新增或变化的 evidence。 - 附近已有 entries。 - workspace 基础上下文。 AI 输出： - 是否值得进入 timeline。 - 动作：创建 draft、更新 draft、绑定到已有 confirmed entry、忽略。 - 事实时间。 - 标题。 - 详情。 - event kind。 - entities。 - evidence ids。 - `draft_fingerprint`。 - confidence。 AI 可以直接更新： ```text source = ai status = draft ``` AI 不可以直接更新： ```text source = human status = confirmed metadata_json.human_edited = true ``` AI draft generation 还需要做去重/抑制： - 如果 evidence 已经绑定到 hidden entry，不再基于同一 evidence 创建相同 draft。 - 如果新 draft candidate 的 `draft_fingerprint` 命中 hidden entry，不直接复活旧内容；只有当 evidence 明显新增事实时才创建新 draft，并在 metadata 中记录关联的 hidden entry。 - 如果 evidence 已经绑定到 confirmed entry，不创建重复 draft。 - 如果新 draft candidate 的 `draft_fingerprint` 命中 confirmed entry，不创建重复 draft；可以把 evidence 绑定为 supporting evidence，或记录为 unreviewed supporting evidence。 - 如果 evidence 与已有 AI draft 高置信匹配，可以更新该 draft。 - 如果匹配不确定，优先新建 draft，但必须保留 evidence 关联，方便人工处理。 MVP 使用 `draft_fingerprint` 做确定性去重和抑制。推荐组成： ```text event_kind + normalized topic/title + occurred_at rounded to 5 minutes + primary entity ids/names ``` `draft_fingerprint` 写入 `workspace_timeline_entries.metadata_json`。AI 输出必须包含该字段；如果 AI 未能给出，服务端用同样规则兜底生成。 ### 3.7 基础追溯 每条 entry 可以绑定多条 evidence。 entry 详情页或编辑模式中需要能看到： - evidence 来源。 - evidence 时间。 - evidence actor。 - evidence 原文。 人工补充的 entry 可以没有 evidence，但 UI 上应能区分： - 有 evidence 支撑。 - 人工补充，无系统 evidence。 ### 3.8 基础审计 MVP 至少记录人工动作： - 人工新增。 - 人工编辑。 - 人工确认 draft。 - 人工隐藏 entry。 这些动作写入 revision 表，或在第一小步中至少记录到 entry 的 `created_by`、`updated_by`、`updated_at`。 ## 4. MVP 不包含什么 MVP 明确不做： - 不接入 monitoring 指标。 - 不自动补齐首次告警时间。 - 不自动补齐 duration/QPS 影响窗口。 - 不自动查询 TiKV store 状态。 - 不从 TiKV live state 或 monitoring 自动推断 leader eviction；只同步 DevOps 已有操作记录。 - 不建设完整 `workspace_timeline_atomic_facts` 表。 - 不建设通用 `workspace_timeline_suggestions` 系统。 - 不建设持久化 dirty scope 表。 - 不做 AI 对 confirmed/human entry 的自动修改建议。 - 不做复杂 split UI。 - 不做完整 RCA 文档生成。 - 不保证 AI draft 与最终人工 timeline 完全一致。 这些能力可以在 MVP 验证后作为后续阶段独立设计。 ## 5. MVP 数据表 MVP 使用 4 张必需表和 1 张可选审计表。 必需： - `workspace_timeline_evidence` - `workspace_timeline_entries` - `workspace_timeline_entry_evidence` - `workspace_timeline_sync_states` 可选但建议： - `workspace_timeline_entry_revisions` ### 5.1 workspace_timeline_evidence 保存原始证据。 ```sql CREATE TABLE workspace_timeline_evidence ( id BIGINT PRIMARY KEY AUTO_INCREMENT, workspace_id BIGINT NOT NULL, source VARCHAR(64) NOT NULL, source_type VARCHAR(64) NOT NULL, source_key VARCHAR(512) NOT NULL, occurred_at DATETIME(3) NULL, source_updated_at DATETIME(3) NULL, observed_at DATETIME(3) NOT NULL, actor_id VARCHAR(255) NULL, actor_display_name VARCHAR(255) NULL, content LONGTEXT NULL, content_hash VARCHAR(128) NOT NULL, metadata_json JSON NOT NULL, created_at DATETIME(3) NOT NULL, updated_at DATETIME(3) NOT NULL, UNIQUE KEY uk_workspace_timeline_evidence_source ( workspace_id, source, source_type, source_key ), KEY idx_workspace_timeline_evidence_workspace_time ( workspace_id, occurred_at ), KEY idx_workspace_timeline_evidence_workspace_source_updated ( workspace_id, source_updated_at ), KEY idx_workspace_timeline_evidence_workspace_updated ( workspace_id, updated_at ) ); ``` MVP 中 `source/source_type` 至少支持： - `jira / jira_comment` - `jira / jira_status` - `devops / devops_operation` - `devops / devops_config_change` - `manual / manual_note` `source_updated_at` 表示外部系统中的更新时间，例如 Jira comment updated time、DevOps operation updated/closed/applied time。`updated_at` 仍表示本地数据库行更新时间。 ### 5.2 workspace_timeline_entries 保存 curated timeline entry。 ```sql CREATE TABLE workspace_timeline_entries ( id BIGINT PRIMARY KEY AUTO_INCREMENT, workspace_id BIGINT NOT NULL, occurred_at DATETIME(3) NOT NULL, sort_order INT NULL, title TEXT NOT NULL, details LONGTEXT NULL, event_kind VARCHAR(128) NULL, topic VARCHAR(255) NULL, entities_json JSON NOT NULL, status VARCHAR(64) NOT NULL, source VARCHAR(64) NOT NULL, confidence DECIMAL(5,4) NULL, superseded_by BIGINT NULL, metadata_json JSON NOT NULL, version BIGINT NOT NULL DEFAULT 1, created_by VARCHAR(255) NULL, updated_by VARCHAR(255) NULL, created_at DATETIME(3) NOT NULL, updated_at DATETIME(3) NOT NULL, KEY idx_workspace_timeline_entries_workspace_time ( workspace_id, occurred_at ), KEY idx_workspace_timeline_entries_workspace_status ( workspace_id, status ) ); ``` `status`: - `draft` - `confirmed` - `hidden` - `superseded` `source`: - `ai` - `human` - `system` ### 5.3 workspace_timeline_entry_evidence 保存 entry 和 evidence 的关联。 ```sql CREATE TABLE workspace_timeline_entry_evidence ( workspace_id BIGINT NOT NULL, entry_id BIGINT NOT NULL, evidence_id BIGINT NOT NULL, relation VARCHAR(64) NOT NULL, created_at DATETIME(3) NOT NULL, PRIMARY KEY (entry_id, evidence_id), KEY idx_workspace_timeline_entry_evidence_workspace ( workspace_id ), KEY idx_workspace_timeline_entry_evidence_evidence ( evidence_id ) ); ``` `relation`: - `primary` - `supporting` - `conflicting` ### 5.4 workspace_timeline_sync_states 保存增量同步水位。 ```sql CREATE TABLE workspace_timeline_sync_states ( id BIGINT PRIMARY KEY AUTO_INCREMENT, workspace_id BIGINT NOT NULL, source VARCHAR(64) NOT NULL, source_type VARCHAR(64) NOT NULL, source_key VARCHAR(512) NOT NULL, last_seen_updated_at DATETIME(3) NULL, last_seen_cursor VARCHAR(512) NULL, last_seen_content_hash VARCHAR(128) NULL, metadata_json JSON NOT NULL, created_at DATETIME(3) NOT NULL, updated_at DATETIME(3) NOT NULL, UNIQUE KEY uk_workspace_timeline_sync_state ( workspace_id, source, source_type, source_key ) ); ``` `source_type` 用于区分同一 source 下不同 cursor，例如： - `jira_issue_comments` - `devops_operations` - `devops_config_changes` Jira sync state 示例： ```text source = jira source_type = jira_issue_comments source_key = issue/ST-2663 ``` DevOps sync state 示例： ```text source = devops source_type = devops_operations source_key = cluster/ source = devops source_type = devops_config_changes source_key = cluster/ ``` ### 5.5 workspace_timeline_entry_revisions 保存人工修改审计。 ```sql CREATE TABLE workspace_timeline_entry_revisions ( id BIGINT PRIMARY KEY AUTO_INCREMENT, entry_id BIGINT NOT NULL, workspace_id BIGINT NOT NULL, changed_by VARCHAR(255) NOT NULL, change_type VARCHAR(64) NOT NULL, before_json JSON NULL, after_json JSON NULL, created_at DATETIME(3) NOT NULL, KEY idx_workspace_timeline_entry_revisions_entry ( entry_id ), KEY idx_workspace_timeline_entry_revisions_workspace ( workspace_id ) ); ``` ## 6. MVP API ### 6.1 获取 curated timeline ```http GET /api/v1/ticketmanager/workspace/workspaces/{id}/curated-timeline ``` 默认返回： - `draft` - `confirmed` 不返回： - `hidden` - `superseded` ### 6.2 新增 entry ```http POST /api/v1/ticketmanager/workspace/workspaces/{id}/curated-timeline ``` 结果： - `status = confirmed` - `source = human` - `metadata_json.human_edited = true` ### 6.3 编辑 entry ```http PATCH /api/v1/ticketmanager/workspace/curated-timeline/{entry_id} ``` 要求： - request 带 `version`。 - 成功后 `version + 1`。 - 版本冲突返回 conflict。 ### 6.4 确认 draft ```http POST /api/v1/ticketmanager/workspace/curated-timeline/{entry_id}/confirm ``` 结果： - `status = confirmed` - 保留 `source = ai`，表示最初由 AI 创建。 - 记录确认人。 ### 6.5 隐藏 entry ```http POST /api/v1/ticketmanager/workspace/curated-timeline/{entry_id}/hide ``` 结果： - `status = hidden` - 默认 timeline 不再展示。 ### 6.6 获取 evidence stream ```http GET /api/v1/ticketmanager/workspace/workspaces/{id}/timeline-evidence ``` 支持过滤： - `source` - `source_type` - `issue_key` - `actor` - `start` - `end` - `bound=true|false` ### 6.7 绑定 evidence ```http POST /api/v1/ticketmanager/workspace/curated-timeline/{entry_id}/evidence ``` 绑定时必须校验： - entry 和 evidence 属于同一个 workspace。 - hidden entry 默认不允许继续绑定新 evidence，除非用户显式恢复或编辑。 - relation 默认为 `supporting`，用户可指定 `primary`。 ### 6.8 手动刷新 ```http POST /api/v1/ticketmanager/workspace/workspaces/{id}/timeline-sync ``` ## 7. MVP 后台任务 MVP 只需要两类任务。 ### 7.1 workspace-timeline-sync-job 职责： - 查找 active workspace。 - 查找 workspace 绑定的 Jira issues。 - 查找 workspace 绑定的 clusters。 - 拉取 issue lightweight metadata。 - 增量拉取 Jira comments。 - 增量拉取 DevOps operations/config changes。 - upsert `workspace_timeline_evidence`。 - 更新 `workspace_timeline_sync_states`。 - 触发 draft generation。 ### 7.2 workspace-timeline-draft-job 职责： - 接收新增或变化 evidence。 - 加载附近已有 entries。 - 调用 AI 生成 draft candidates。 - 创建新的 AI draft entry。 - 或更新已有 AI draft entry。 - 或把 evidence 绑定到高置信匹配的 confirmed entry。 - 绑定 evidence。 - 不覆盖人工内容。 - 不基于 hidden entry 的已绑定 evidence 反复生成相同 draft。 - 不为已高置信匹配 confirmed entry 的 evidence 创建重复 draft。 AI 生成失败时的重试行为（2026-09-07）： - `services.workspace.timeline.aiDraftsEnabled=true` 且有待处理 evidence 时，Agent 不可用、调用超时或输出解析失败都返回错误；不再回退为按关键词分类、复制 comment 的规则 draft。没有待处理 evidence 时正常返回，无需 Agent 可用。 - 已采集的原始 evidence 保留在数据库中。失败的 AI 调用不创建 entry、不绑定 evidence，也不写入 AI 已处理标记，因此下一次同步可直接从持久化 backlog 重试，无需 Jira 再出现新 comment。 - 重试由已有的周期 watcher 或手动 `timeline-sync` 触发。周期 watcher 仍仅处理创建不超过 3 天的 firing workspace，并按上次尝试时间及配置间隔调度；默认 case workspace 为 20 分钟，war room 为 5 分钟，实际开始时间还受 watcher 轮询与队列影响。 - 单次调用不额外循环重试；手动刷新失败会返回错误，后台失败会进入现有任务错误日志和指标。 - 显式关闭 `aiDraftsEnabled` 时仍使用原有规则模式。本次变更不自动清理或重新归纳历史规则条目。 ## 8. MVP 状态机 ```text AI creates entry -> draft draft -> confirmed 人工确认 -> hidden 人工隐藏 confirmed -> confirmed 人工编辑后仍保持 confirmed -> hidden 人工隐藏 hidden -> confirmed 人工恢复，MVP 可不做恢复接口 ``` hide 语义： - hidden entry 不默认展示。 - hidden entry 绑定过的 evidence 会参与 suppression。 - hidden entry 的 `draft_fingerprint` 会参与 suppression。 - 如果后续同一事件出现新的强相关 evidence，系统可以创建新 draft，但 metadata 必须记录它与 hidden entry 的关系，避免无提示地“复活”旧内容。 AI 只能直接修改： ```text status = draft source = ai metadata_json.human_edited != true ``` AI 不能直接修改： ```text status = confirmed source = human metadata_json.human_edited = true ``` ## 9. MVP 成功标准 MVP 成功不要求 AI 完美，而要求产品闭环成立。 必须满足： - 用户打开 workspace 默认看到 curated timeline，而不是 raw event feed。 - 新 Jira comment 进入后，可以自动生成 AI draft entry。 - 新 DevOps operation/config change 进入后，可以自动生成或补充 AI draft entry。 - AI draft 默认可见。 - 人工可以确认、编辑、隐藏 draft。 - 人工可以新增缺失 entry。 - AI 不覆盖人工编辑后的内容。 - entry 可以追溯到 evidence，或明确是人工补充。 - 后续同步不再每次全量拉取所有 comments。 - 隐藏过的 draft 不会在下一轮同步中无变化地重复出现。 - confirmed entry 不会因为新 supporting evidence 进入而重复生成同主题 draft。 - DevOps operation/config change 的状态更新能被同步到 evidence。 可量化指标： - draft 接受率。 - draft 被编辑后确认的比例。 - hidden draft 比例。 - 每个 case 人工新增 entry 数。 - Jira comment 拉取量相对全量同步的下降比例。 - DevOps operation/config change 拉取量相对全量同步的下降比例。 - AI 覆盖人工内容次数，必须为 0。 ## 10. MVP 之后再做 MVP 验证后再考虑： - `workspace_timeline_atomic_facts` - `workspace_timeline_suggestions` - `workspace_timeline_dirty_scopes` - AI 对 confirmed entry 的旁路建议。 - 更复杂的 merge/split UI。 - monitoring 指标接入。 - 自动补齐影响窗口。 - RCA 文档生成。 - 多 source 综合排序和冲突检测。