灵依 WebUI 能量值幻觉事件分析报告

编号: DATA-TRUTH-001
日期: 2026-04-08
来源: LingYi 项目 Tab 重新设计过程
严重程度: 中（未造成数据损坏，但造成决策误导）
分类: 数据真实性 / 幻觉字段 / 设计缺陷

1. 事件摘要

LingYi WebUI 的「项目」Tab 长期展示一个 energy_pct（精力分配百分比）字段。该字段： - 在 Project dataclass 中定义 - 存入 SQLite 数据库 - 在 CLI lingyi project list/show 中展示 - 在 WebUI 项目卡片中展示 - 在仪表盘首页摘要中展示

唯一的问题是：这个数字从未被任何代码更新过。 从录入那天起就是死的。

用户在查看项目 Tab 时发现所有项目的状态信息毫无用处——只有一堆固定不变的百分比，无法回答最基本的问题：「灵通完成了什么？在做什么？计划做什么？」

2. 根因分析

2.1 直接原因

energy_pct 字段在设计时没有回答两个必要问题：

问题	答案
数据从哪来？	无数据源。`presets.json` 中写死了初始值（25%, 10%, 5%, 0%）
谁来更新它？	无人更新。没有任何代码路径会修改这个字段

字段全链路通畅（定义 → 存储 → 展示），唯独缺了最重要的一环：真实数据的生产。

2.2 同类问题

审计发现 Project.version 也是假数据：

字段	数据库中的值	真实值（git tag）	差异
LingFlow	v3.8.0	v3.8.0	恰好一致
LingClaude	v0.2.0	（无 tag）	数据库里的值无法验证
Ling-term-mcp	v1.0.0	v1.0.0	一致但不会自动更新

version 字段和 energy_pct 的本质相同：人工写入一次后，没有任何机制保持它与现实同步。 唯一的区别是 version 恰好还没过时。

2.3 深层模式

此事件与前一天的「代码写完就宣布完成」事件属于同一类病根：

事件	表现	共同病根
前一天	代码改了但没验证就报完成	对自身输出缺乏真实性检验
本次	字段定义了但没数据源就上线	对自身设计缺乏真实性追问

两个事件的共同模式：在链条上跳过了「这是真的吗？」这一步。

3. 影响范围

3.1 受影响的代码文件（已修复）

文件	使用方式
`models.py`	`energy_pct: int = 0` 字段定义
`db.py`	`energy_pct INTEGER DEFAULT 0` 表定义
`project.py`	INSERT SQL、格式化函数
`commands/project.py`	CLI `--energy` 选项
`web_app.py`	仪表盘 API、系统提示词
`templates/index.html`	前端展示
`presets.json`	初始数据

3.2 误导持续时间

energy_pct 自项目创建（2026-04-04）至被发现（2026-04-08），共 4 天。期间所有通过 CLI 或 WebUI 查看项目状态的用户（至少包括广大老师）都被展示了虚假数据。

4. 修复方案

4.1 已完成

新增 /api/projects/live 端点：实时扫描 git 仓库，返回真实数据
当前分支、最新 commit 消息/时间
git tag（真实版本号）
近 7 天提交数（活动量）
未提交文件数
匹配该项目的灵信讨论线程
前端项目 Tab 全面重设计：按状态分组，展示真实 git 数据
从代码中删除 energy_pct 引用：
models.py — 字段删除
project.py — INSERT 去掉 energy_pct、格式化函数去掉百分比展示
commands/project.py — CLI --energy 选项删除
web_app.py — 仪表盘去掉 energy 展示
templates/index.html — 前端去掉百分比展示

4.2 待完成

db.py — SQLite 不能直接删列，需要在下次 schema migration 时重建表
presets.json — 删掉 energy_pct 初始值
Project.version — 应从 git tag 自动获取，而非数据库中写死

5. 提取的设计原则

5.1 数据真实性检查（Data Truth Check）

任何出现在 UI 上的数据，必须能回答两个问题： 1. 数据从哪来？（有没有真实的数据源在持续产生它） 2. 谁来更新它？（是自动的，还是依赖人工——如果是人工，人知道吗？）

答不上来的，就不该出现在 UI 上。

5.2 宁缺毋滥原则

空着是诚实，假数字是欺骗。宁可少显示一个字段，也不要放一个没有真实数据源的数字。

5.3 设计时的真实性追问

设计一个新字段时，不应只问「这个字段叫什么、类型是什么」，还应问： - 第一次填入的值从哪来？ - 后续谁来更新？更新频率？ - 如果没人更新，它会变成什么？死数字？

如果答不出来，说明这个字段还没有到该设计的时候。

6. 更广泛的启示

此事件揭示了一种可以称为「数据幻觉」的模式：

系统展示了一个看起来有意义的数据，给人以「系统了解项目状态」的错觉，实际上系统对这个数据没有任何真实的感知能力。

这与 AI 领域的「幻觉」概念有深层对应：

AI 幻觉	数据幻觉
模型输出了看起来合理但无事实依据的内容	系统展示了看起来有意义但无真实数据源的字段
根本原因：模型不区分「知道」和「不知道」	根本原因：设计者不区分「有数据」和「定义了字段」
解决：让模型学会说「我不知道」	解决：让系统学会说「没有这个数据」

核心教训：定义一个字段 ≠ 拥有这个数据。展示一个数字 ≠ 这个数字是真的。

附录 A：`energy_pct` 的生前轨迹

2026-04-04  预设数据录入: energy_pct = 25 (LingFlow, LingClaude, 灵知), 10 (LingYi), 5 (lingtongask)
2026-04-04~07  数据库中的值从未改变
2026-04-08  10:00  用户发现项目 Tab 无法回答「灵通在做什么」
2026-04-08  12:00  诊断确认 energy_pct 是死字段
2026-04-08  13:00  实施修复：live API + 前端重设计 + energy_pct 删除

附录 B：修复后的真实数据示例

LingFlow          | active  | P0 | master | week=34 | dirty=7 | 7 小时前 | fix: redact leaked npm token
LingClaude        | active  | P0 | master | week=38 | dirty=5 | 49 分钟前 | fix: CLI响应等待超时优化
灵知系统            | active  | P0 | develop| week=20 | dirty=10| 6 小时前 | feat: 灵知MCP 11→30工具扩展
LingYi            | active  | P1 | master | week=69 | dirty=21| 5 小时前 | fix: Web UI 断线修复

每一个数字都来自 git log，每一次刷新都会更新。

本报告由灵依整理，作为灵妍（AI研究框架）的研究素材。