02-V-界面与交互.md
13.9 KB
02-V-界面与交互
管理后台是黑灯工厂的"驾驶舱"（架构文档第 13 节），不只是配置页面，而是覆盖项目创建、目标提出、bug 反馈、实时看板、过程检查、Artifact/Skill 管理的完整人机交互控制台。MVP 单用户，无角色权限矩阵；MVP 单项目，页面里预留项目筛选但不强制做完整的项目列表/切换体验。
实时性原则：凡标注"实时"的页面/组件，均通过 WebSocket 订阅 execution_event 流更新（架构文档 13.1 节决策 3），不做轮询。
2.0 导航壳层（新增，2026-07-30，源自 docs/wireframes/ 连页原型）
此前各页面只逐条描述字段/事件，没有定义跨页共享的导航结构，会导致同一个信息架构问题被不同实现者各自猜测。以下结构在制作 docs/wireframes/*.html 连页原型时确定，供实现时直接采用：
- 常驻顶部导航（除
v_project_setup外全部页面共享）：仪表盘（v_dashboard）→任务（v_task_board）→产物（v_artifact_browser）→技能库（v_skill_library）→设置（下拉菜单，含并发数/预算护栏/日志保留三个子项，分别指向v_concurrency_settings/v_budget_settings/v_log_retention_settings） - 不进常驻导航的页面：
v_project_setup——首次使用或点导航栏右上角"切换项目"链接进入，属于项目切换流程，不是常规导航项v_goal_composer/v_bug_feedback——通过v_dashboard的按钮进入（click_propose_goal/click_report_bug），原型阶段做成独立路由页面而非弹层（02-V 原描述"可作为弹层，也可独立路由"在此处收敛为"独立路由"，弹层与否是纯 UI 实现细节，不影响信息结构，实现时如改用弹层不需要回来改本节）v_task_detail/v_skill_audit_log——分别从v_task_board/v_skill_library的列表项点击进入，不是导航项
- 导航栏右侧：当前项目名 + "切换项目"链接（指向
v_project_setup）
参照实现（无构建步骤的静态 HTML，DOM/class 命名与本文档字段一一对应，可直接作为实现起点）：docs/wireframes/v_project_setup.html 起，共 12 个路由页面 + v_graph_visualizer.html 内嵌组件示范。
2.1 页面：v_project_setup 项目创建/选择
- 参照原型：
docs/wireframes/v_project_setup.html - 路由：
/setup（首次使用或需要更换目标项目时进入） - 载体说明（架构文档 13.1 节决策 5）：控制台是本地 Web 应用，不是桌面应用；点击"选择文件夹"时前端调用
c_pick_folder，由本机常驻的后端进程代为拉起 OS 原生文件夹选择对话框并返回真实绝对路径，不使用浏览器 File System Access API - 字段：
folder_path默认只读文本展示（由c_pick_folder回填，避免手动输入拼错路径），必填；仅当c_pick_folder返回DIALOG_UNAVAILABLE时，字段切换为可编辑的手动输入兜底project_name文本输入，非必填（留空则取文件夹名）
- 交互事件：
click_pick_folder→ 触发c_pick_folder，成功回填folder_path；用户取消系统对话框则folder_path保持原值不变；返回DIALOG_UNAVAILABLE时提示"当前环境不支持弹窗选择，请手动输入路径"并解锁手动编辑 - 提交流程：
- 选择文件夹后先校验
has_git_repo（探测.git是否存在） - 若不是 Git 仓库，弹出确认态"该文件夹还不是 Git 仓库，是否代为初始化（
git init）？"——用户确认前不写入任何文件（对应护栏规则：Prohibited/Explicit permission required类操作不能静默执行） - 确认后调用
c_project_create，创建.graphlemon/子目录 - 成功 → 跳转
v_dashboard；失败 → 展示具体错误（如路径不可写）
- 选择文件夹后先校验
- 异常态：文件夹不存在、无写权限、路径已被注册为其他项目（幂等命中，直接跳转已有项目看板而非报错）
2.2 页面：v_dashboard 实时看板首页
- 参照原型：
docs/wireframes/v_dashboard.html - 路由：
/（默认首页） - 权限：
all - 展示内容（全部实时刷新）：
- Org Graph 三节点状态卡片：
planner/coder/validator各自当前是否有active的work_graph_run，高亮当前task.assigned_org_node - 当前任务概要：
goal_text摘要、loop_round、status - 预算用量条：引用
budget_guardrail_config.current_usage/limit_value，实时更新 - 最近事件时间线：最近 N 条
execution_event，滚动追加（新事件从顶部滑入，对应 WebSocket 推送到达）
- Org Graph 三节点状态卡片：
- 交互事件：
click_propose_goal→ 打开v_goal_composerclick_report_bug→ 打开v_bug_feedbackclick_task_card→ 跳转v_task_detail
- 异常态：无任何任务时展示"暂无运行中任务"空态 + 醒目的"提出第一个目标"引导按钮；WebSocket 连接断开时展示"实时连接已断开，正在重连"提示条，不阻塞页面其余只读内容展示
- 信息态（新增，2026-07-29）：有任务处于
waiting_for_quota时展示"等待 Claude Code 额度恢复（{session|weekly|opus}），预计 {剩余等待时长}"提示条——样式是信息性的浅色条，不是blocked_pending_human那种醒目告警样式，因为这是自愈型阻塞不需要人工操作；click可展开跳转到对应v_task_detail
2.3 页面：v_goal_composer 提出目标
- 参照原型：
docs/wireframes/v_goal_composer.html - 路由：
/goals/new（可作为v_dashboard的弹层，也可独立路由） - 字段：
goal_text多行文本输入，必填，校验maxLen:4000
- 提交流程：提交前校验非空 → 确认态展示即将创建的任务摘要 → 调用
c_task_create（created_via=human_console）→ 成功跳转v_task_detail - 异常态：为空提交时内联校验提示，不发起请求
2.4 页面：v_bug_feedback 人工反馈 bug
- 参照原型：
docs/wireframes/v_bug_feedback.html - 路由：
/bugs/new - 字段：
description多行文本，必填repro_steps多行文本，非必填（允许先反馈现象，复现步骤后补）related_task_id下拉选择器，非必填（关联到某个已有任务；留空则视为新发现的独立问题）
- 提交流程：提交 → 调用
c_bug_report_create（创建bug_record(source=human, status=open)）→ 成功提示"已提交，Validator 将进行归因确认" → 跳转到该 bug 的详情视图（复用v_task_detail的 bug 展示区，或独立v_bug_detail，MVP 复用前者） - 异常态：
description为空时内联校验拦截
2.5 页面：v_task_board 任务看板
- 参照原型：
docs/wireframes/v_task_board.html - 路由：
/tasks - 字段：
keyword搜索框，非必填，校验maxLen:128status_filter下拉，选项对应task.status枚举org_node_filter下拉，选项planner|coder|validator
- 展示列表项（实时）：
task_id、goal_text摘要、status、assigned_org_node、loop_round、updated_at，status变化时该行有动效高亮（对应收到task_status_changed事件） - 交互事件：
click_row→ 跳转v_task_detail；click_search→ 触发c_task_list - 异常态：空态"暂无任务"；加载失败态提示重试
2.6 页面：v_task_detail 任务详情 / 过程检查
- 参照原型：
docs/wireframes/v_task_detail.html - 路由：
/tasks/:task_id - 字段：只读展示
task全部字段 + 关联artifact列表 + 关联bug_record列表 - 子模块：
- 内嵌
v_graph_visualizer（该 task 当前work_graph_run的实时图结构） org_node=coder的 to-do 树视图（新增，2026-07-30，回应"task 层级关系看不出来"的核对）：把当前work_graph_run.graph_manifest（即 to-do list 本身，见 01-M §1.3 补充说明）渲染为缩进树，而不只是v_graph_visualizer的按层 DAG 行；每个 to-do 节点标注对应work_node_execution.status，点开能展开到该节点的执行详情/日志（复用下方"每个 work_node_execution 支持展开"能力）。体现的层级是project → task → work_graph_run → to-do 树（graph_manifest）→ work_node_execution → execution_log_file，明确这是 task 内部单个 Coder Work Graph 的结构，不是多个 task 组成的树。- 事件时间线：该 task 全部
execution_event，按时间正序展示，支持展开查看payload详情（这是"检查过程"诉求的核心落地） - 每个
work_node_execution支持展开查看input_payload/output_payload/reflection_notes/retry_count - 内嵌
v_log_viewer（该work_node_execution的原始执行日志，控制台内直接查看，见 2.7.1）
- 内嵌
- 交互事件：
click_artifact_link→ 打开对应文件（目标项目内.graphlemon/runs/或源码路径）click_view_raw_log→ 展开v_log_viewer（不再是外部深链，见架构文档 13.1 节决策 4 的修正）click_retry（仅status=blocked_pending_human时可见）→ 触发人工干预（manual_resume）
- 异常态：
blocked_pending_human状态需醒目告警样式
2.7 页面：v_graph_visualizer Org/Work Graph 实时可视化
- 参照原型：
docs/wireframes/v_graph_visualizer.html - 内嵌组件，非独立路由
- 展示内容：
- Org Graph 层：固定三节点图，高亮当前节点
- Work Graph 层：当前
work_graph_run.graph_manifest渲染的节点/边图，节点按work_node_execution.status实时着色（done=绿、running=蓝、reflecting/retrying=黄、waiting_for_quota=浅蓝+时钟图标（信息性，非告警样式，见 03-C 3.6 节）、blocked/failed=红、pending=灰），状态变化时对应节点有过渡动效（对应收到node_status_changed事件）
- 交互事件：
hover_node→ tooltip 展示input_schema_ref/output_schema_ref/retry_count摘要；waiting_for_quota态额外展示quota_limit_type和已等待时长 - 无可执行变化时可回归条件：无
work_graph_run记录时展示"尚未开始规划"占位态
2.7.1 组件：v_log_viewer 原始执行日志查看器（架构文档 13.1 节决策 4）
- 内嵌组件，非独立路由，被
v_task_detail按node_exec_id引用 - 字段：
node_exec_id（必填，决定查看哪个 Work Node 的日志） - 展示内容：
work_node_execution.status IN (pending, running, reflecting, retrying)时：实时滚动模式，通过 WebSocket 订阅该节点日志流，新内容持续追加到底部（对应execution_event(event_type=log_appended)）status IN (done, blocked, failed)时：静态模式，一次性拉取execution_log_file全量内容（大文件分页加载，避免一次性渲染卡顿）
- 交互事件：
toggle_auto_scroll→ 前端本地状态，是否自动滚动到最新一行click_download→ 下载完整日志文件（c_execution_log_get的下载态）
- 异常态：
execution_log_file.status=purged（已被定时清理）→ 展示"该日志已超过保留期限被清理，保留天数可在设置中调整"，不报错- 日志文件本身写入失败/丢失 → 展示"日志暂不可用"而非空白页面
2.8 页面：v_artifact_browser Artifact 浏览器
- 参照原型：
docs/wireframes/v_artifact_browser.html - 路由：
/artifacts - 字段：
artifact_type_filter下拉、task_id_filter下拉 - 展示：列表 + 预览（Markdown 类型直接渲染，代码类型语法高亮，均为只读）
- 交互事件：
click_row→ 展示depends_on_artifact_ids血缘链（图形化展示版本依赖关系） - 异常态：空态"暂无产物"
2.9 页面：v_skill_library Skill 库管理
- 参照原型：
docs/wireframes/v_skill_library.html - 路由：
/skills - 展示：
skill列表（按owner_org_node分组：Planner/Coder/Validator），每项展示source（是否迁移自 Hermes profile / 新建 / 自动迭代产生） - 交互事件：
click_skill→ 跳转v_skill_audit_log
2.10 页面：v_skill_audit_log Skill 变更审计日志
- 参照原型：
docs/wireframes/v_skill_audit_log.html - 路由：
/skills/:skill_id/audit - 字段：只读列表，展示
skill_iteration记录：applied_at、triggered_by_bug_id、change_summary、before/after_git_commit_sha - 交互事件：
click_diff→ 展示 Git diffclick_rollback→ 触发c_skill_rollback，生成新的skill_iteration记录
- 异常态：空态"该 Skill 尚无自主迭代记录"
2.11 页面：v_concurrency_settings 并发数配置
- 参照原型：
docs/wireframes/v_concurrency_settings.html - 路由：
/settings/concurrency - 字段：
max_concurrent_goals数字输入，必填，校验range:1-50 - 交互事件：
submit_save→ 触发c_concurrency_config_update - 提交流程：校验 → 确认态 → 成功提示"已更新，下一个新 Goal 起生效"
2.12 页面：v_budget_settings 预算护栏配置
- 参照原型：
docs/wireframes/v_budget_settings.html - 路由：
/settings/budget - 字段：
scope下拉、limit_type下拉、limit_value数字输入，均必填 - 展示：当前用量进度条（实时）
- 交互事件：
submit_save→ 触发c_budget_config_update - 异常态：超限时展示告警条 + "查看已暂停任务"链接（跳转
v_task_board预置status_filter=blocked_pending_human）
2.13 页面：v_log_retention_settings 日志保留策略配置（架构文档 13.1 节决策 4）
- 参照原型：
docs/wireframes/v_log_retention_settings.html - 路由：
/settings/log-retention - 字段：
retention_days数字输入，必填，校验>0max_total_size_mb数字输入，非必填
- 展示：当前日志总占用大小（汇总所有
status=active|closed的execution_log_file.size_bytes） - 交互事件：
submit_save→ 触发c_log_retention_config_update - 异常态：
retention_days填 0 或负数时内联校验拦截