人工智能AI AgentAgent记忆MCP服务【免费下载链接】engramPersistent memory system for AI coding agents. Agent-agnostic Go binary with SQLite FTS5, MCP server, HTTP API, CLI, and TUI.项目地址https://gitcode.com/gh_mirrors/engra/engram点击查看免费下载Engram 是一个面向 AI 编码代理的持久记忆系统其云控制面Cloud Dashboard是一套基于 Go templ 服务端渲染 HTMX 局部刷新的浏览器 UI。本文以仓库中的 skills/ui-elements/SKILL.md 为骨架结合 internal/cloud/dashboard 的真实组件与测试实现系统讲解在 Engram Dashboard 中新增页面、卡片、指标、表格与详情流时应遵守的设计规则和落地方式。读完本文你将掌握何时该用这套规范、五条 UX 铁律与四条组合规则的含义、每条规则对应的 templ/HTMX 组件证据以及如何通过测试守护UI 不能撒谎这一核心不变式。何时使用这套规范按 skills/ui-elements/SKILL.md 的When to Use定义以下场景应当套用本规范为 Dashboard 新增一个页面或 partial局部片段创建卡片card、指标metric、表格table、列表list或详情视图detail view设计相关实体之间的关联导航connected navigation。在 Engram 中这些 UI 元素全部落在internal/cloud/dashboard包内通过 templ 模板.templ 生成的*_templ.go与 HTMX 属性hx-get、hx-target、hx-swap、hx-include组合实现具体挂载路径可参考 docs/codebase/dashboard.md 中的架构说明Browser → cloudserver认证/会话/管理员边界→ dashboardhandlers templ 静态资源→ DashboardStore 接口 → cloudstorePostgres 读模型。UX 五条铁律每条都有源码佐证原文档定义了五条 UX 规则它们不是空泛的审美建议而是可以在 components.templ 中逐条对号入座的实现约束。1. 每条列表项都应通向有用之处Every list item should lead somewhere useful when domain relationships exist.当实体之间存在领域关系时任何列表项都必须是可点击的入口而不是死胡同。代码中最直接的体现是列表 partial 用a classcard-link包裹整张卡片ObservationsPartialcomponents.templ#L328-L352把每条 observation 包成a href/dashboard/observations/{project}/{sessionID}/{syncID}PromptsPartial同样把每条 prompt 包成指向详情页的卡片链接ProjectsListPartialcomponents.templ#L500-L539把每个项目包成指向/dashboard/projects/{project}的card-link。对应测试 dashboard_test.go#L257-L321TestBrowserObservationsAreClickable、TestBrowserSessionsAreClickable、TestBrowserPromptsAreClickable逐一断言这些 href 确实存在。2. 优先使用连接流project → session → observation → full detailPrefer connected flows: project - session - observation - full detail.这是 Engram Dashboard 关联导航的黄金链路在 URL 结构上体现得尤为清晰这也是 SKILL 中connected navigation的核心实现项目卡片 →/dashboard/projects/{project}ProjectDetailPage项目详情页内通过#project-tabs三个子标签继续下钻到该项目的 observations / sessions / promptsSession 行 →/dashboard/sessions/{project}/{sessionID}SessionDetailPage页面展示会话元数据 该会话内的 observations 与 promptsObservation 卡片 →/dashboard/observations/{project}/{sessionID}/{syncID}ObservationDetailPage详情页除完整内容外还带LINKED SESSION面板与More from this Session相关列表。值得注意的细节observation/prompt 详情 URL 使用syncID而非纯数据库自增 ID测试TestObservationDetailURLUsesSyncIDdashboard_test.go#L1907与TestPromptDetailURLUsesSyncIDdashboard_test.go#L1947专门守护这一约定确保详情地址与同步合同保持一致。3. 空状态必须说明缺什么、以及什么能解锁数据Empty states must explain what is missing and what unlocks data.EmptyState是 Dashboard 的共享组件components.templ#L41-L48渲染NO SIGNAL YET小标题 主标题 说明文案配合 styles.css#L856-L871 的居中空状态样式。它在整个界面中大量复用并且文案始终在回答缺什么 / 怎么解锁首页无同步项目时Project metrics will show up here after the first successful sync.——明确指出数据从首次同步解锁无匹配的 observationNo observations match the current project, search text, or type filter.——指出是过滤条件导致为空无托管用户Create the first managed user above. Every managed user is deny-by-default and cannot sync any project until an admin grants one explicitly.——既说明缺什么也说明解锁路径管理员显式授权项目无项目授权This user is deny-by-default: it cannot sync any project until an admin grants one explicitly above.。4. 指标必须反映真实系统状态而不是装饰性计数器Metrics must reflect real system state, not decorative counters.首页指标条由DashboardStatsPartialcomponents.templ#L146-L222渲染四个指标卡Sessions / Observations / Prompts / Projects Synced全部来自cloudstore.DashboardProjectRow的真实聚合值汇总函数totalStatSessions、totalStatObservations、totalStatPrompts定义在 helpers.go#L207-L233。每个指标卡同时是stat-card-link点击直接跳转到对应的过滤视图——指标不仅真实还承担导航职责。Admin 侧同样如此AdminPage与AdminHealthPage展示的 DB 连接状态、Contributors、Sessions、Observations、Prompts、Projects、Paused Projects 均来自DashboardSystemHealth读模型components.templ#L755-L802其中数据库连接直接渲染Connected / Disconnected徽章。5. 详情页应展示元数据、内容与下一步相关链接Detail pages should show metadata, content, and the next relevant links.ObservationDetailPage是标准范本元数据表Chunk ID / Session / Created / Tool / Topic Key→CONTENT区块结构化内容渲染→LINKED SESSION面板 →More from this Session相关列表。PromptDetailPagecomponents.templ#L423-L461同样在元数据后追加LINKED SESSION与Other Prompts from this Session。SessionDetailPage则在会话元数据Session ID / Project / Directory / Started / Ended / Summary之外下钻展示该会话的 Observations 与 Prompts 两组列表。结构化内容渲染逻辑在 helpers.go#L343-L492自动识别**What/Why/Where/Learned**结构字段或##标题分节转成structured-block区块列表预览则通过renderInlineStructuredPreview压成单行摘要。组合规则什么时候用什么元素原文档给出四条组合规则配合DashboardStore接口dashboard.go#L59-L96能看清每种元素的适用场景指标用于定位而不是替代核心内容metric-strip/stat-card只承担概览与导航点击后进入真实内容页详情本身由 card / table / detail 承载可浏览实体用卡片密集对比的管理数据用表格observations 与 prompts 用.card列表有标题、预览、时间戳 footer而 sessions、contributors、admin projects、managed users、audit log 等密集行数据统一用.data-tablestyles.css#L819-L848会话表还包在.table-scroll中应对横向溢出测试TestSessionsTableWrappedInScrollContainer守护避免嵌套框架框数据面板使用.data-frame/.browser-content-frame单层边框.structured-block仅用于表达内容内部层级操作控件要紧贴其作用的实体项目同步开关直接放在项目行内AdminProjectsPage的switch-formcomponents.templ#L807-L882启用/禁用按钮紧挨目标项目托管用户的 Enable/Disable、Revoke 按钮同样各自贴在所属行内。关联导航的工程化分页与局部刷新导航不止是链接还包括列表翻页体验。Pagination结构helpers.go#L33-L38提供Offset/HasPrev/HasNext/ShowPagination/Start/End/PageNumbers全套能力parsePagination负责把?pagepageSize参数钳制在合法范围默认每页 10 条、最小 10、最大 100UI 提供{10, 25, 50, 100}四种档位helpers.go#L21-L30。两种分页条分工明确PaginationBarcomponents.templ#L53-L86完整页面跳转paginationURL保留现有查询参数project / q / type 等HtmxPaginationBarcomponents.templ#L92-L125以hx-get向指定 endpoint 发起局部请求hx-target指向内容容器、hx-include携带现有筛选条件翻页不刷新整页。注释特别强调 URL 使用?page而非page以避免产生畸形的?URL。对应测试TestBrowserPaginationHonorsPageParam、TestBrowserPaginationBeyondTotalClampsToLastPage、TestBrowserPartialRendersPaginationBardashboard_test.go覆盖了页码越界钳制与局部刷新渲染。核心不变式UI 不能撒谎skills/ui-elements/SKILL.md 的精神内核在 docs/codebase/dashboard.md#L45-L47 中被总结为一条硬性架构约束The UI cannot lie. If it shows sync paused, every push path must be blocked server-side.落实到实现上项目卡片上的Paused徽章ProjectsListPartial读取的是cloudstore.ProjectSyncControl.SyncEnabled而真正的执行阻断在cloudserver/cloudstore层如POST /sync/push、POST /sync/mutations/push的服务器端策略不是 templ/HTMX 里的摆设Admin 项目控制页AdminProjectsPage的每个开关都 POST 到/dashboard/admin/projects/{project}/sync由 cloudserver 强制执行并审计托管用户managed users页面的所有变更表单create / enable / disable / tokens / grants也全部指向 cloudserver 拥有的路由dashboard包只渲染状态与结果、绝不自行决定授权见 dashboard.go#L98-L108 的ManagedUsersStore只读边界注释非管理员访问 Admin 面返回 403AdminForbidden测试TestAdminProjectsRequires403ForNonAdmin、TestAdminUsersRequires403ForNonAdmin等一整套 403 用例守护此不变式。视觉系统TUI 对齐的设计令牌static/styles.css 顶部定义了与 TUI 视觉对齐的 CSS 变量--engram-base: #191724、--engram-surface: #1f1d2e、--engram-primary: #c4a7e7、--engram-success: #9ccfd8、--engram-warning: #f6c177、--engram-danger: #eb6f92等styles.css#L3-L20。语义化徽章StatusBadge据此着色decision/architecture → success、bugfix → danger、discovery/learning → warninghelpers.go#L571-L583头部与按钮使用等宽显示字体族营造终端气质section-kicker的大写字母间距排版用于区分层级。设计一个看起来属于 Engram的新组件应当复用这些令牌而不是另起一套色板。用测试守护这套规范internal/cloud/dashboard/dashboard_test.go是这套 UI 规范最完整的验收清单值得在新增组件时对照阅读可点击性TestContributorDetailPageRendersDrillDown、TestBrowserObservationsAreClickable、TestDashboardHomeStatCardsAreClickable断言 metric-card 必须包在a中且 href 指向有意义的钻取视图URL 约定TestObservationDetailURLUsesSyncID、TestPromptDetailURLUsesSyncID、TestObservationCardHrefIsNotMalformedHTMX 接线TestMountAddsHTMXNavigationWiringForBrowserProjectsAndAdmin、TestDashboardHomeHTMXWiring、TestBrowserPageHTMXWiring、TestProjectsPageHTMXWiring、TestMountHTMXAndProjectDetailParity空状态与降级TestMountStoreErrorsReturnDegradedNon200Responsesstore 出错时 htmx 路由返回独立 503 片段而非整页管理权限一整套 403 用例以及TestAdminSyncToggleHTMXPostIncludesFormFieldsHTMX 表单必须携带enabled字段。这些测试把每条列表项通向有用之处指标反映真实状态详情页带元数据与相关链接等抽象规则翻译成了可断言的机器行为——这正是 Engram UI 元素规范能长期不被架空的根本原因。后续新增页面或 partial 时遵循本文的规则并参照TestMount...系列测试补齐路由、认证、HTMX partial 与边缘用例即可。赞分享人工智能AI AgentAgent记忆MCP服务【免费下载链接】engramPersistent memory system for AI coding agents. Agent-agnostic Go binary with SQLite FTS5, MCP server, HTTP API, CLI, and TUI.项目地址https://gitcode.com/gh_mirrors/engra/engram点击查看免费下载相关推荐Hugo Blox Tag Cloud 组件实战为 Markdown Slides 幻灯片站搭建标签导航页Hugo Blox Tag Cloud 组件实战为 Markdown Slides 幻灯片站搭建标签导航页 导读 本文以 markdown slides 起始静态站点前端开发工具Metabase Dashboard Markdown标题卡片与文本卡片实战指南Metabase Dashboard Markdown标题卡片与文本卡片实战指南 导读 本文基于 Metabase 官方仪表板文档 dashboard ma数据分析数据可视化后端数据库客户端企业应用Nuxt UI v4 ContentNavigation 组件实战指南基于 nuxt/content 的手风琴式页面导航Nuxt UI v4 ContentNavigation 组件实战指南基于 nuxt/content 的手风琴式页面导航 导读 UContentNaviga前端UI组件上一篇WXT 国际化I18n完全指南从原生 browser.i18n 到 wxt-dev/i18n 的类型安全方案下一篇XGP存档提取终极指南简单三步实现游戏进度无损迁移创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考