Explorer 交互设计

专题结论

Explorer 把图浏览、决策审查、来源血缘、时间回放和推理实验拆成多个工作台，信息架构很适合作为可问责语义系统的交互样本。主要问题包括决策理由、先例和合规尚未接入当前决策前端，部分标签比后端算法实际保证更强，且安全模式下前端没有发现 API key 录入和发送链路。

建议：强参照工作台划分，以及已经实现的图、来源和时间审查流程；决策审查只参照列表与因果链主从骨架，复用前补齐详情接入并校准标签、证据等级、双时态表达和认证入口。

1. 前后端技术边界

Explorer 后端使用 FastAPI（提供 HTTP、WebSocket、静态资源和路由装配的 Web 框架，约第 11 行），前端使用 React（工作台组件框架，锁定 19.2.5）和 TypeScript（前端类型语言，锁定 5.9.3）。

图可视化依赖 Sigma（图渲染库，锁定 3.0.2）与 Graphology（图数据结构库，锁定 0.26.0）；时间轴使用 vis-timeline（交互式时间轴库，锁定 8.5.0）；服务端状态查询使用 @tanstack/react-query（前端异步数据缓存库，锁定 5.99.2）。

这套栈适合快速构建调查型工作台，但大图规模、布局稳定性、缓存失效、实时更新和认证状态仍需端到端测试。

2. 五个可借鉴的工作台

3. 决策工作台：现有形态有限，后端语义仍需降级

当前 DecisionWorkspace（实现决策列表、筛选、选中项摘要和所谓因果链展示的前端工作台，约第 88 行）实际流程是“列表筛选 → 选中决策 → 查看 ID、类别、结果与邻居链”。它没有读取完整决策详情，也没有调用先例或合规接口。因此可以直接借鉴主从骨架，但“理由、关系、先例和合规并置”属于建议补齐的目标形态，不是当前已经实现的界面；相关后端接口接入后仍需明确其算法含义。

原始调用链

DecisionWorkspace.loadChain()（选中决策后请求链数据的前端内部函数）调用决策链 HTTP 路由；get_causal_chain()（把路由参数转换为邻居链响应的方法）调用 GraphSession.get_neighbors()（把深度参数转发给上下文图的会话方法），最终进入 ContextGraph.get_neighbors()（遍历普通邻接关系的方法）。输入是决策 ID，输出是最多五跳的邻居列表；链路没有增加因果边类型过滤。

3.1 因果链

get_causal_chain()（以通用邻居查询返回所谓决策链的路由方法，约第 67 行）调用最多五跳的通用邻居遍历，没有限制为因果关系。因此界面不能直接把全部结果标为“因果”。

原项目关键片段——get_causal_chain()（使用通用邻居遍历形成决策链响应的路由方法）。

固定提交片段：通用邻居形成的决策链 原项目关键片段

async def get_causal_chain(
    decision_id: str,
    session: GraphSession = Depends(get_session),
):
    node = await asyncio.to_thread(session.get_node, decision_id)
    if node is None:
        raise HTTPException(status_code=404, detail=f"Decision '{decision_id}' not found")

    neighbors = await asyncio.to_thread(session.get_neighbors, decision_id, 5)
    chain = [
        {
            "id": neighbor.get("id"),
            "type": neighbor.get("type"),
            "relationship": neighbor.get("relationship"),
            "hop": neighbor.get("hop"),
            "content": neighbor.get("content", ""),
        }
        for neighbor in neighbors
    ]
    return CausalChainResponse(decision_id=decision_id, chain=chain)

这段实现证明响应来自通用邻居查询，而不是只沿显式因果边遍历。可借鉴的是前端选中对象后渐进加载关系链的主从交互；不能照搬的是“因果链”标签，除非后端改用因果关系过滤并返回证据等级。

建议把关系分成“显式因果”“推测影响”“普通邻接”，并显示边类型、来源、确认人和证据强度。真正只沿因果边的距离能力位于 causal_distance()（使用因果分析器计算两个节点因果距离的路由方法，约第 129 行），两者不应混为一谈。

3.2 先例

get_precedents()（按类别相同和场景词集合重叠给历史决策打分的方法，约第 90 行）更接近“相似决策候选”，不是经过法律或业务认定的正式先例。

建议 UI 改为“候选先例”，显示类别匹配、词重叠、时间、适用政策和人工确认状态；只有完成确认后才进入正式先例集合。

3.3 合规

check_compliance()（只检查三种违规关系边并据此返回合规状态的方法，约第 143 行）没有执行完整策略引擎。没有发现违规边不等于证明合规。

建议状态改为“未发现已记录违规关系”，并同时显示规则覆盖率、规则版本、最后执行时间和未知项。只有完整规则集成功执行后才能展示“已验证合规”。

4. 来源泳道与时间轴

来源泳道把“谁、做了什么、产生什么”分层，适合审计调查。建议增加：

• 默认从当前实体向上游展开，避免一次加载全图；
• 每条边显示来源动作、时间、版本和可信度；
• 节点可直接跳转到原始文档定位或处理日志；
• 撤回节点以独立状态显示，并支持查看受影响后代。

时间轴当前提供图历史回放的良好基础，但双时态项目应把业务有效时间与系统记录时间分开。最佳交互是双轴切换、并排快照，以及“事后补录”醒目标记。

5. 节点检查器与推理工作台

节点检查器值得扩展为“逐字段证据面板”：每个字段展示当前值、有效期、记录时间、来源、处理活动、版本和冲突状态。关系边也应显示同样的时态和证据维度，而不是只列目标节点。

推理工作台应增加规则版本、事实版本、变量绑定、执行摘要和重放状态。结果列表中的每个结论都应能展开到证明步骤并继续跳转到来源证据。

下面是抽象示例（不是原项目原样界面），展示建议的决策审查布局：

┌ 决策列表 ───────────┬ 决策详情 ──────────────────────┐
│ 状态 / 时间 / 人     │ 结果、理由、审批、规则版本       │
│ 风险 / 待重审筛选    │ 证据：原文定位、有效期、记录时间   │
│ 候选先例置信度       │ 关系：显式因果 / 推测影响 / 邻接   │
└─────────────────────┴───────────────────────────────┘
│ 底部抽屉：版本差异、推理证明、来源泳道、重放状态         │
└─────────────────────────────────────────────────────┘

6. 认证与安全交互缺口

require_auth()（在受保护路由上校验 API key 的依赖函数，约第 46 行）要求客户端发送 X-API-Key（Explorer 受保护接口使用的认证请求头，约第 19 行）。静态搜索没有在原生前端发现相应的录入、持久化或请求注入代码。

上述负面证据来自对固定提交中 Explorer 前端源码的逐文件静态检索，检索了请求头名、API key 和 Authorization 相关表达；已存在的替代接口是后端 require_auth()（校验请求头的认证依赖），缺失的是前端登录、凭据存储和 fetch 请求注入关系。由于本次未构建或运行 Explorer，这一结论属于固定提交的静态实现事实，不是浏览器运行测试结果。

这意味着安全模式至少需要一种补充方案：反向代理在可信会话后注入请求头，或前端实现登录、短期令牌、安全存储和统一请求拦截。不要把长期 API key 放入构建产物、浏览器本地存储或 URL。

7. 可借鉴交互清单

1. 工作台按“图、决策、来源、推理”分域，保持全局实体与时间上下文。
2. 主从决策审查保留列表上下文，详情支持关系和证据下钻。
3. 来源泳道先回答角色与活动，再允许切换通用图布局。
4. 双时态切换器始终显示当前轴和快照时间。
5. 所有算法结果显示保证等级：显式、启发式、已验证、未知或失败。
6. 删除、撤回、重算和批准动作先展示影响范围，再要求理由和确认。
7. 认证失效时提供明确恢复路径，WebSocket 与普通 API 使用一致身份。

8. 引入或参照结论

9. 源码依据

返回 Semantica 项目分析主报告