Dashboard 设计原则

Dashboard 是 PowerContext 中供个人使用和演示的内容查看器，使用静态 token 鉴权，默认关闭。这份文档供开发和评审人员判断页面该展示什么、如何组织阅读，以及一次改动是否保留了用户需要的行为。接口能力以 openapi/powercontext.yaml 和服务实现为依据。

Dashboard 帮助用户完成什么

用户进入 Dashboard 时，可能想确认某项约定，查找解决过类似问题的经验，或继续一项中断的工作。页面需要让用户确定正在查看哪个范围，找到相关记录，并在需要时核对原始材料。

1.0 的核心是阅读已有内容。记忆、经验、技能和交接可以分别存在：只有记忆的范围也应当能够正常使用；没有内容的范围仍有明确的入口和页面结构。生成、审核和保存由现有工具与接口完成，阅读这些结果不应要求用户先配置生成能力。

页面的业务主题来自范围名称、摘要和保存的内容。支付服务、客户访谈或个人研究可以使用同一套界面，不需要为每种业务另造导航。新增区块时，应先说明它帮助用户完成哪项工作，以及现有数据能否支持它表达的含义。

内容和范围的含义

各类内容回答的问题

经验需要保留当时的情境，技能需要保留使用条件，交接表达的是保存时的状态。即使几份内容互有关联，阅读时仍需区分它们能支持什么判断。记录中关于修复完成的说法，需要通过相应依据核对。

首页和目录可以缩短摘要，详情保留完整正文。展示层负责呈现已有信息，不根据拆句或改写补出新的结论。来源引用帮助用户核对内容；有可读原文时提供入口，只有引用信息时如实保留引用。

范围决定正在看什么

范围（Scope）是内容归属和阅读选择的单位。未指定范围的入口使用服务端已配置的默认范围。用户在下拉栏选择另一范围，只改变这次浏览的位置，不改变默认保存位置或工具绑定。

名称相近的范围要能区分。选择器显示范围自身名称和已有的祖先关系，父子关系以服务端记录为准。父级内容不会自动进入子级目录；准备上下文时对其他范围的显式引用，也不等于父子归属。

内容目录和用量均读取当前范围，切换范围时一同更新。父范围的用量不自动包含子范围。例如，一个空子范围可以没有记忆，而父范围仍有记忆；这不构成数据缺失，也不能用父范围的内容填满子范围页面。

数据能支持怎样的判断

没有记录、没有可比较数据、服务未报告数值和读取失败，需要分别表达。只有接口明确返回零时才能显示零。无法读取某个范围或记录时，应说明失败并提供可用的恢复入口，不能静默换成另一份内容。

用量中的参考内容估算只覆盖可比较的记录。减少比例用于说明文本规模的变化，不代表信息完整性、内容质量或账单节省；估算结果为增加时也应如实展示。模型输入、输出和向量用量分别列出，缺报数值保留为未报告。

首页摘要、每日图表和明细表采用同一统计口径。周期和每日归属来自服务端，界面不补造历史数据。

页面如何组织阅读

首页提供概览和入口

首页依次展示用量、记忆与经验及技能、交接。用量提供整体使用情况的入口；记忆和可复用内容供用户查阅；交接保留进入具体工作记录的路径。

每个区块有明确的标题和查看入口，摘要只承担预览作用。宽屏将记忆与经验及技能并排呈现，窄屏按同一阅读顺序排列。某类内容尚未生成时，空状态留在它所属的区块中。

用户也可以从目录、收藏链接或精确引用直接打开记录。

目录用于查找，详情用于阅读

目录帮助用户辨认并选择条目。长列表通过分页控制一次需要浏览的内容，搜索帮助缩小查找范围。搜索的范围和结果上限需要与接口一致；当前一页的筛选不能表现为整个内容库的搜索。

记忆采用目录与正文的阅读方式。经验、技能和交接从目录进入详情，详情承载完整内容和关联材料。条目较多时，摘要可以截短，但用户始终有路径读到全文。

用户打开一条记录后，应能返回所属目录。更换搜索条件从第一页开始；切换范围清除上一范围的记录选择和分页位置，详情返回对应目录。单纯切换语言或主题则保留范围、周期和正在阅读的记录。

原始材料支持就地核对

原始材料列在记录正文之后，读者可以从经验、技能或交接直接打开对应材料。材料使用 Tabler 原生大尺寸弹窗阅读，小屏全屏显示；多份材料通过选单切换。关闭后回到原记录的阅读位置，键盘用户也能完成同样的过程。

材料正文可能很长。阅读区域根据视口分配空间，标题和关闭操作保持可达，正文在该区域内滚动。打开一份材料不应把整页推长到用户找不到原来的位置。某份材料读取失败时，已经打开的记录仍可阅读。

布局与交互如何保持一致

内容变化不改变页面的组织方式

有内容、无内容和搜索无结果时，页面保留相同的标题层级、主要分区和阅读顺序。记忆目录不会因为暂时为空就变成另一种整页视图，用量也不会因为没有记录就丢掉统计区域。

稳定布局需要保留必要的阅读空间，但不要求所有状态像素级等高。预留高度应考虑摘要容量、分页容量和可用视口；长正文可以自然增高。末页条目变少时，分页操作保持容易找到的位置。内容不足一屏时，正文起点也不应向下漂移。

根据阅读空间选择分栏和滚动

页面容器、两侧留白和栅格间距沿用 Tabler 的默认规则。分栏的前提是两侧都有足够的阅读宽度；空间不足时按顺序堆叠，不通过缩小正文字号维持分屏。

小屏上的记忆在条目内展开，打开另一条时收起上一条；桌面使用目录与正文分栏。搜索结果沿用同样的阅读方式，上一页、页码和下一页保持可见，没有可翻阅的页面时禁用对应操作。

列表通常随页面滚动，一页中的条目应直接可见。局部滚动用于需要保持上下文的长正文、材料面板或宽表格。是否增加滚动区域，要看它能否帮助用户保留阅读位置；不能仅为了让卡片看起来整齐而嵌套滚动条。

文案和视觉共同表达层级

标题说明页面或区块的内容，按钮说明执行的操作。业务正文保持原文，界面文案使用直接、具体的表达。用户已经能从导航和内容判断的信息，不需要再用说明文字重复。

字体、字重、按钮和表单状态优先采用 Tabler 的默认选择。记忆、经验和技能条目使用常规字重，避免每条内容都争夺注意力。同一层级的卡片使用一致的边界和间距，箭头用于有方向含义的操作。

中英文和明暗主题适用于全部 Dashboard 页面，包括登录与独立材料页。翻译可以自然换行，但不应打乱导航顺序、按钮分组或主栏比例。主题切换保留相同的信息层级和可读性；业务内容不随界面语言改写。完整 Logo 使用现有品牌资源，favicon 只使用图形部分。

设计与实现的边界

页面能力来自现有接口

页面显示真实可读的数据，操作入口对应已有能力。某个区块失败时，其他可独立读取的内容继续显示。读取错误、权限不足和生成配置缺失各有不同含义，不能合并成无内容。

Dashboard 仅支持内置静态 Bearer 身份，所有 token 持有者共享同一权限。启用需要 POWERCONTEXT_SERVER_DASHBOARD_ENABLED=true、ACCESS_MODE=enforced 和 AUTH_TOKEN；注入认证或授权 Provider 的团队部署必须关闭它。页面读取复用现有 API 并继续执行服务鉴权，不新增数据接口，也不实现成员或角色管理。 个人启用步骤见安装和运行。

目录可以随保存和修订而变化，精确引用仍指向对应的历史版本。引用不存在或无权访问时，应明确处理该结果，不能用当前版本或相似记录代替。

框架负责通用行为，页面负责内容组合

Tabler 提供导航、选择器、卡片、分页、抽屉和图表等通用能力。已有组件直接复用，默认字体、留白、焦点和响应式行为也属于复用范围。

Jinja2 组织内容与页面结构，HTMX 处理导航和片段替换。只有现有能力不能完成必要交互时，才通过 Surreal 连接事件，并用 css-scope-inline 将补充样式限制在所属组件。全局样式只承担少量必要的主题适配。

组件边界按共同的用户行为划分。范围选择在各页使用同一种行为，图表与摘要共用统计语义，材料阅读共用打开、返回和失败恢复方式。业务数据的解释与界面交互各有职责，修改一种记录的展示不应影响其他页面。

偏离框架默认行为需要具体原因。例如，页面片段替换可能提前移除尚未关闭的弹窗，此时需要通过组件公开接口完成清理。补充代码应解决这个副作用，并由相应的行为测试验证；通常的菜单定位和跨断点显隐仍交给框架。

如何判断设计成立

评审从用户要完成的工作出发。用户是否知道正在查看哪个范围，能否找到完整内容，能否核对来源，遇到失败后能否继续阅读，比页面包含多少卡片更有判断价值。

用消融检查必要性

消融时一次移除一项信息、操作或依赖，观察哪项用户任务受到影响。若删除一段说明后仍能准确理解页面，就需要重新考虑这段说明的价值。关闭生成配置后，已保存内容应继续可读；某类内容缺失时，其他目录应能独立使用。

涉及内容精简时，对同一问题比较原文和不同预算的参考内容，记录遗漏的约束、下一步或引用。高精简比例本身不能证明用户仍获得了完成任务所需的信息。

检查容易产生误解的情况

行为测试验证真实的阅读、查找和导航过程；回归测试保留已经发生过的缺陷。测试应当允许实现重构，只要用户可见的行为仍然成立。缓冲区大小、私有调用顺序或已经删除的标签，不应成为测试目标；访问隔离等当前契约仍需要验证拒绝结果。

用真实数据核对页面表达

验证数据通过现有接口保存和生成，数据库只用于只读核对。页面、接口响应和数据库记录应当能对应到同一范围、记录与版本。配置错误、失败请求和结果未知的写入要保留明确证据，恢复前先核实已有结果。

连续多日回放用于检查内容在后续工作中能否继续被读取和召回。每天导入新内容前先检查前日引用，再验证当天的生成、修订和用量归属。记忆提取、经验与技能生成、交接生成和保存都通过实际接口验证；无法生成或没有新候选时如实记录。审核只能使用截至当时的材料，文本中的完成声明不能代替实际验证。

回放使用隔离环境，保留输入窗口、请求和结果，截图与会话内容存放在仓库外。模拟日期可以验证历史读取和每日归属，但几个会话的结果不能证明任意问题的召回质量，也不能证明生产调度长期可靠。

附录：接口与验证入口

以下内容用于查找实现，具体字段、限制和组件配置以代码及接口规格为准。

页面与接口

首页组合上述读取结果。接口只提供有限结果或游标时，页面不推导未经报告的总数。记录与来源身份需要完整保留，不能为了适配某种响应格式而删除或改写。

代码与检查

接口规格位于 openapi/powercontext.yaml，Dashboard 实现位于 src/powercontext/server/dashboard/，行为测试位于 tests/test_dashboard.py，浏览器验收入口为 scripts/dashboard_browser.cjs。固定版本的前端资源与许可证保存在 Dashboard 的 static/vendor/ 中。

在仓库根目录执行基础检查：

make check
uv run pytest tests/test_dashboard.py tests/test_server.py tests/test_access_http.py

对已配置并启动的 Server 执行浏览器验收：

npm install --prefix /tmp/dashboard-browser playwright@1.61.1
/tmp/dashboard-browser/node_modules/.bin/playwright install chromium
POWERCONTEXT_BROWSER_URL=http://127.0.0.1:8765 \
POWERCONTEXT_BROWSER_OUTPUT=/tmp/dashboard-verification \
NODE_PATH=/tmp/dashboard-browser/node_modules \
node scripts/dashboard_browser.cjs

需要认证时通过 POWERCONTEXT_REPLAY_TOKEN 提供当前用户凭据。输出目录应位于仓库外，按工作内容的访问要求保存。

会话回放使用 scripts/dashboard_replay.py，连续多日验证使用 scripts/dashboard_multiday.py，候选内容审核由 scripts/dashboard_review.py 提供支持。两个回放脚本的运行参数可通过 --help 查询。回放配置、操作日志和实验结果属于具体验证记录，不作为页面设计原则。