Skip to content

Project Features

Junlang-7 edited this page Sep 22, 2026 · 7 revisions

FocusLoop 项目功能说明

事实基线:默认分支 main,commit e596d6f,核对日期 2026-09-22。

本页只把已经进入默认分支的能力标为“可用”。只存在于功能分支的实现标为“开发中”,设计方案标为“规划中”。

1. 产品定位

FocusLoop 是一个本地优先的学习连续性工具,面向容易在开始任务、维持注意力或中断后重新进入状态时遇到困难的学习者。

它的核心目标不是让学习者一直与聊天机器人对话,而是维护一条可恢复的学习链路:

导入材料 → 生成课程与微任务 → 开始专注 Session
→ 记录学习事件和当前位置 → 识别卡住或中断
→ 给出低打扰建议或 Resume Card → 回到原任务
→ 在 Dashboard 查看过程与结果

FocusLoop 不进行 ADHD、智力、人格或心理健康诊断,也不根据行为生成临床结论。

2. 功能状态总览

功能领域 用户可以做什么 状态 当前边界
内置演示课程 直接打开示例课程并体验完整学习流程 可用 用于演示和开发验证
学习材料导入 从本机选择或粘贴 .txt、.md 内容 可用 暂不支持 PDF、Word、网页抓取
课程与微任务生成 从材料章节确定性生成概念、阅读/练习任务和部分测验 可用 不是模型生成;最多选取有限章节
课程浏览 查看概念、材料原文、任务顺序、预计时长和完成状态 可用 当前以单人、本地课程为单位
Focus Session 启动/结束 Session,开始、暂停、继续和完成任务 可用 计时器主要由桌面 UI 管理
学习状态识别 根据任务、求助、答题、离开和空闲事件维护八种学习状态 可用 使用确定性状态机,不做心理诊断
“我卡住了” 选择六类卡点原因,并获得规则驱动的行动建议 可用 默认分支可展示并接受/拒绝建议;真实任务拆分仍未实现
干预策略 根据状态选择微启动、简化、提示、例子、提问、休息或恢复 可用 是否主动出现由规则决定;模型不决定打断时机
Learning Checkpoint 保存当前概念、任务、步骤、已掌握/未解决内容和下一步 可用 内容主要从当前任务进度推导
Resume Card 中断后显示上次位置、已完成内容、未解决内容和下一步 可用 默认分支尚未提供短/中/长三档 Resume
Resume 操作 接受或忽略恢复建议,并记录恢复延迟 可用 更完整的恢复成功指标仍在开发分支
Dashboard 查看时长、完成任务、中断次数、恢复延迟和干预结果 可用 指标均来自本地数据
Insights 按当前 Session、今天、近 7 天或全部时间查看趋势 可用 包含状态时间分布、活动日历和课程占比
学习事件时间线 查看任务、求助、中断、恢复等事件;相邻重复事件折叠显示 可用 是过程记录,不是人格或能力评价
浏览器 Bridge 通过 Chrome/Edge MV3 扩展发送标签切换和 idle 元数据 可用 不读取 URL、标题、页面内容、表单或 Cookie
Demo Event Simulator 不安装扩展也可模拟分心、返回、困惑、过载和成功 可用 仅开发版显示,打包版本隐藏
Agent Context Inspector 在开发模式查看 Agent 当前可见的有界上下文及省略项 可用 不是完整数据库或完整 Provider 请求
中英文界面 在英文和简体中文之间切换 可用 设置保存在本地
主题 跟随系统或固定为浅色/深色 可用 设置保存在本地
离线运行 无网络、无账号、无 API Key 完成核心流程 可用 Mock Provider 只用于确定性离线路径
可选 DeepSeek 基础设施 配置环境变量后加载远端 Provider,并在界面显示运行模式 基础已接入 当前 main 没有会在正常 UI 流程中调用它的 Tutor 功能
Contextual Tutor 围绕当前步骤提供解释、提示、例子、苏格拉底提问等六种模式 开发中 已有未合并功能分支,不属于当前 main
Resume 三档和重新参与指标 按离开时长选择 Short/Medium/Long,并计算 5 分钟窗口指标 开发中 已有未合并功能分支;指标口径仍需产品校准
完整 Stuck Rescue 闭环 将建议变成可执行微步骤,并评估救援结果 开发中 默认分支已有建议和结果记录,完整执行链路未合并
任务自适应 缩小、拆分、改变形式或重排任务 规划中 需要确认、幂等和计划版本控制
学习复盘与偏好 周复盘、证据化偏好建议、确认/编辑/删除 规划中 不允许自动形成长期人格或诊断标签
Agent Memory Working、Episodic、Preference 三级记忆及删除控制 规划中 保留期和删除语义尚未冻结
Agent Tools 受权限控制的读取、可逆操作和结构性操作 规划中 模型不能直接操作 SQLite 或任意 IPC
统一 Model Runtime Provider 路由、结构化输出、超时、取消、流式和降级 规划中 当前只有较小的 Provider abstraction
完整 Agent Eval 固定场景、隐私/越权测试、质量趋势和发布门槛 开发中 确定性场景只在未合并功能分支中形成

“开发中”的判断来自当前可见但尚未进入 main 的分支:Contextual Tutor 见 feat/ag3-contextual-tutor,Resume/Rescue/Eval 合并开发见 feat/agent-phase1-evals-rescue。分支被合并、关闭或重写后,应同步更新本页状态和事实基线。

3. 已可使用的核心流程

3.1 导入材料并生成课程

学习者可以:

  1. 使用内置演示课程;或从本机选择 .txt / .md 文件;
  2. 在需要时直接粘贴材料内容;
  3. 让 FocusLoop 按章节提取概念;
  4. 确定性生成阅读任务、练习任务和满足条件时的测验;
  5. 在课程页查看概念摘要、对应材料、任务类型、顺序和预计时长。

相同材料会产生稳定结果,不要求网络或模型。生成规则位于 micro-task-generator.ts。

3.2 运行专注 Session

Focus Workspace 每次突出一个当前任务,支持:

  • 开始任务;
  • 暂停和继续计时;
  • 计时结束后增加一分钟;
  • 完成当前任务并进入下一任务;
  • 查看整个 Session 的完成进度;
  • 主动点击“我卡住了”并选择原因;
  • 结束 Session。

卡点原因是闭合集合:无法开始、任务太大、不理解、想不起来、哪里出错、疲惫/过载。它描述当前学习情境,不会被保存为长期人格标签。

3.3 学习状态与干预

状态机维护八种状态:

  • READY
  • INITIATION_FRICTION
  • FOCUSED
  • CONFUSED
  • OVERLOADED
  • DISTRACTED
  • INTERRUPTED
  • RESUMING

输入来自任务开始/完成、测验结果、主动求助、标签离开/返回和系统 idle 等事件。规则决定是否保持安静,或提供 MICRO_START、SIMPLIFY、HINT、EXAMPLE、QUESTION、BREAK、RESUME 等建议。

当前默认分支已经支持建议展示、原因说明、接受和拒绝记录,但 SIMPLIFY 等建议尚不会真正改写 Session Plan。完整任务变更属于后续 Task Adaptation。

3.4 中断恢复

当标签离开或系统 idle 超过阈值时,FocusLoop 可以进入 INTERRUPTED,并创建 Learning Checkpoint。返回后显示 Resume Card,其中包括:

  • 上次所在课程、概念和任务;
  • 最近完成的内容;
  • 仍未解决的内容;
  • 推荐的下一步;
  • 预计重新进入任务所需时间。

学习者可以继续或忽略。系统记录卡片展示时间、接受/忽略时间和恢复延迟。

默认分支只有统一 Resume Card;Short/Medium/Long 三档策略和“接受后 5 分钟是否重新参与”的指标目前只在未合并开发分支。

3.5 Dashboard 与 Insights

Dashboard 同时提供当前 Session 和跨 Session 两类视图:

  • Session 时长与任务完成数;
  • 中断次数;
  • 平均恢复延迟;
  • 各类干预的展示、接受、拒绝和任务完成结果;
  • 学习事件时间线;
  • 当前 Session、今天、近 7 天、全部时间四种统计窗口;
  • 各学习状态的时间占比;
  • 每日活动热力图;
  • 完成任务、中断、Session 数量;
  • 多课程时的时间占比。

这些统计从本地 Session 和事件重算,不依赖远端分析服务。

4. 浏览器扩展与模拟器

可选的 Chrome/Edge Manifest V3 扩展用于向桌面应用发送:

  • 学习标签是否仍处于活动状态;
  • 用户是否进入 idle;
  • 离开和返回的时长;
  • 防重放所需的事件标识。

扩展只申请 idle、storage、alarms 和可选的本机 127.0.0.1 访问权限。它不申请页面访问权限,因此不会读取 URL、标题、正文、输入框、Cookie 或浏览历史。

桌面 Bridge 只监听 127.0.0.1,使用每次启动重新生成的 token,并校验协议版本、消息大小、事件类型和 payload。

开发环境中的 Demo Event Simulator 提供同一套核心事件,无需安装扩展即可演示完整路径。

5. 本地数据、隐私与安全边界

默认情况下:

  • 不需要账号或登录;
  • 没有中央业务服务器;
  • 课程、材料、Session、事件、Checkpoint、干预和设置保存在本机 SQLite;
  • 核心路径不需要网络;
  • DeepSeek Provider 只有在用户提供环境变量时才加载;当前 main 的正常 UI 流程不会用它回答 Tutor 问题;
  • API Key 不写入仓库或数据库;
  • Renderer 使用 Electron sandbox、contextIsolation 和关闭的 nodeIntegration;
  • Renderer 只能调用白名单中的、再次校验参数的 IPC 方法。

更完整的说明见隐私边界和架构文档。

6. 设置与可访问性

当前设置包括:

  • 英文 / 简体中文;
  • 跟随系统 / 浅色 / 深色主题;
  • 是否在界面和开发者 Inspector 中显示材料正文。

主要交互为按钮、表单、进度条、计时器和可聚焦的选择组,并为核心操作提供 ARIA 名称和键盘焦点管理。

7. 当前明确不支持

以下能力不应被描述为当前产品功能:

  • PDF、Word 或网页材料导入;
  • 移动端;
  • 多人协作;
  • 云端账号与同步;
  • 自动诊断 ADHD 或其他心理/认知状态;
  • 摄像头、麦克风、眼动或屏幕录制;
  • Agent 自动、静默改写学习计划;
  • 长期学习者画像;
  • 模型直接访问数据库、文件系统或任意 Electron IPC;
  • 已发布的 Contextual Tutor、Task Adaptation、Reflection 或完整 Agent Tool System。

8. 功能规划入口

后续能力和交付依赖见:

阅读这些页面时,应以页首标注的分支和 commit 为准;“规划中”的接口、数据模型和指标不等于默认分支已经支持。

Clone this wiki locally