Repository navigation
Project Features
事实基线:默认分支
main@e596d6f, 核对日期 2026-09-22。本页是唯一的「当前能力台账」。只存在于功能分支的实现标为「分支完成」,只开了 PR 的标为 「PR 已开」,两者都不算可用。这里不写愿景,只写能被链接复核的事实。
设计完成 → 分支完成 → PR 已开 → 已合并 → CI 绿 → E2E 验证 → 已发布
| 状态 | 含义 | 最低证据 |
|---|---|---|
| 设计完成 | 范围、契约、DoD 已写入方案页 | 方案页链接 |
| 分支完成 | 代码在功能分支上完成并通过本地门禁 | 分支名 + commit |
| PR 已开 | 已开 PR,等待 CI | PR 编号 |
| 已合并 | 该能力已进入 main(能力口径) |
merge commit |
| CI 绿 | 该能力在 main 上的必需检查已通过(运行链接见本节末) |
main 的 workflow run 链接;可另附实现文件或 commit |
| E2E 验证 | golden path 里有该能力的用户可见断言并通过 | e2e 测试名 + main 上的 CI run |
| 已发布 | 出现在已发布的 Release 中(草稿 Release 不算) | Release tag |
五条硬规则:
- 不得越级。E2E 被环境阻塞时,最高只能标到「CI 绿」,且必须在“已知限制”写明阻塞原因。
- 测试数量不是证据。「N 项测试通过」无法复核,证据必须是 commit、PR 或 CI run 链接。
- 同名不等于可用。存在同名类型、按钮或文案,不等于该能力已经闭环。
-
状态是能力口径,不是 PR 口径:
已合并与CI 绿都指该能力已经在main上,而不是某个 PR 的 检查通过;某个 PR 的结果只写在该 PR 对应的那一行里。 -
一个能力被拆成“已合并部分 + 分支部分”时,状态只描述已合并部分,分支部分必须在“已知限制”里点名。
例:AG1 的边界与 omission 已合并,13 类事件投影仍在分支。本节凡是
CI 绿都引用main@e596d6f的必需检查:CI、 Coverage、 Code scanning。
| # | 重点 | 要回答的问题 |
|---|---|---|
| 1 | 定位 | 一句话说清它是什么,不含术语 |
| 2 | 用户怎么用 | 入口在哪、按什么顺序操作、看到什么 |
| 3 | 何时发生 | 谁决定它发生:确定性策略 / 用户主动 / 模型只生成内容 |
| 4 | 永不做什么 | 不变量:不诊断、不静默改计划、不直连数据库、不上传原始内容 |
| 5 | 数据与边界 | 读什么、写什么、存在哪、什么会离开本机、各项上限 |
| 6 | 状态与证据 | 按 1.1 的状态 + commit / PR / CI / E2E 链接 |
| 7 | 已知限制 | 现在做不到什么,以及为什么(含开放问题) |
| 8 | 依赖 | 上游必须先有什么,下游等它什么 |
| 9 | 怎么验证 | 测试文件、e2e 测试名、可复现的手动演示路径 |
FocusLoop 是一个本地优先的学习连续性工具,面向在开始任务、维持注意力和中断后重新进入 时有困难的学习者。它不是聊天机器人:核心目标是维护一条可恢复的学习链路。
导入材料 → 生成课程与微任务 → 开始 Focus Session
→ 记录学习事件与当前位置 → 识别卡住或中断
→ 低打扰建议或 Resume Card → 回到原任务
→ 在 Dashboard / Insights 查看过程与结果
FocusLoop 不做 ADHD、智力、人格或心理健康诊断,也不根据行为生成临床结论。
| 分组 | 功能 | 状态 | 证据 | 当前边界 |
|---|---|---|---|---|
| A 学习 | 内置演示课程 | E2E 验证 | golden path | 用于演示与开发验证 |
| A 学习 | 本机材料导入(.txt / .md) |
E2E 验证 |
af2e74f (#81) |
不支持 PDF / Word / 网页抓取 |
| A 学习 | 课程与微任务生成 | CI 绿 | micro-task-generator.ts |
确定性规则,不是模型生成 |
| A 学习 | 课程浏览 | CI 绿 | 课程页 + store 读取 | 单人、本地课程为单位 |
| A 学习 | Focus Session 计时 | E2E 验证 | golden path | 计时由桌面 UI 管理 |
| A 学习 | 任务生命周期(暂停/继续/延长) | E2E 验证 |
257efe0 (#76)、2b4934f (#75) |
计时结束后延长一分钟 |
| B 干预 | 学习状态机(八态) | CI 绿 | packages/learning-state |
确定性状态机,不做心理诊断 |
| B 干预 | 「我卡住了」六类原因 | E2E 验证 |
534bc1c (#100) |
原因先被记录,再决定行动 |
| B 干预 | 干预策略(确定性 8 类 action) | CI 绿 | packages/intervention-policy |
模型不决定是否打断 |
| B 干预 | 干预结果记录与 Dashboard 汇总 | CI 绿 | outcome 事件 + Dashboard | 记录展示/接受/拒绝/完成 |
| B 干预 | Rescue 计划与成功评估器 | 已合并 |
ae1d690 (PR #124) |
接受 MICRO_START 会真正缩小任务(#171);SIMPLIFY 会拆成 1–5 分钟步骤(#172) |
| C 恢复 | Learning Checkpoint | CI 绿 |
buildCheckpoint + store |
内容主要从任务进度推导 |
| C 恢复 | Resume Card(统一版) | E2E 验证 |
packages/continuity + Dashboard |
三档已上屏:短档 #196、长档 #203 的 e2e 钉在策略边界 |
| C 恢复 | Resume 三档 + 重新参与指标 | E2E 验证 |
classifyResumeGap / ResumePolicyConfig / evaluateResumeOutcome;96ac295 (#119) |
reengaged/progressed/stalledAgain 已分列;见 §4.C3 |
| D 观察 | Dashboard | CI 绿 | 当前 Session 与跨 Session 两类视图 | 指标全部本地重算 |
| D 观察 | Insights(四个时间窗) | CI 绿 | 状态占比、日历、课程占比 | 不依赖远端分析服务 |
| D 观察 | 学习事件时间线 | CI 绿 | 相邻重复事件折叠 | 是过程记录,不是能力评价 |
| E 环境 | 浏览器 Bridge(MV3) | CI 绿 | 扩展 + 本机 bridge | 不读 URL / 标题 / 正文 / Cookie |
| E 环境 | 应用自身的分心感知 | E2E 验证 | 窗口失焦 / 系统空闲;旧调试栏已删除(#254) | 不请求任何权限;可关(FOCUSLOOP_DISTRACTION_SENSOR=0) |
| E 环境 | 中英文界面 | E2E 验证 |
messages.en/zh.ts + 编译期强制 |
设置存本地 |
| E 环境 | 主题(跟随系统 / 浅 / 深) | CI 绿 | token 门禁(禁用字面色值) | 设置存本地 |
| E 环境 | 离线运行 | E2E 验证 | Mock Provider | 无账号、无网络可完成核心流程 |
| E 环境 | 可选 DeepSeek Provider | 已合并 | packages/llm-provider |
main 的正常 UI 流程不调用它 |
| E 环境 | Agent Context Inspector(AG1) | 已移除 | 原 63acc28 (#99),移除见 §E7 |
面板、三个 IPC 通道与 outbound 缓冲一并删除;AgentContext 本身不变 |
| F Agent | AG1 Learning Context | E2E 验证 |
63acc28 (#99);投影穷举 d938bb8 (#188) |
投影与敏感 payload 回归均已合并,见 §4.F1 |
| F Agent | AG2 Stuck Rescue | E2E 验证 |
534bc1c (#100);2677645 (#181)、cd6e886 (#183)、b0fabd8 (#184) |
MICRO_START/SIMPLIFY 真正改写、HINT/EXAMPLE 有 grounding;provider 变体已交付(#205) |
| F Agent | AG3 Contextual Tutor | 已合并 |
107a30f (#101) |
领域层已只返回闭合码;AgentContextOmission.detail 仍是英文句子 |
| F Agent | AG4 Task Adaptation | 设计完成 | 方案页 AG4;读时派生改写已合并(#171/#172) | 无持久化 AdaptiveTask,计划级改写待 AG8 phase 2 |
| F Agent | AG5 Cognitive Resume | E2E 验证 |
6df7e08 基线 + 9d2e55d (#196)、d9f1783 (#203)、78555af (#206) |
三档、指标分列、长档关键想法均已合并,见 §4.C3 |
| F Agent | AG6 Learning Reflection | 已合并 |
e81f034 (#241)、2453035 (#242)、2640719 (#243)、#247、#236 |
词表/派生/反思/建议/确认入库全部交付;ADR 0003 补 preference-write 格 |
| F Agent | AG7 Agent Memory | E2E 验证 |
ADR 0001、6a4a0cf (#129)、5e3d764 (#221)、cb2d33a (#222)、d40ba0a (#223) |
三类边界、检查 UI、偏好单项删除、时间窗清理均已合并,见 §4.C3 与 §4.F |
| F Agent | AG8 Tools & Actions | E2E 验证 | 信封 bf0844b (#126);确认屏 b870e00 (#218);b624064 (#216)、e59ea9b (#217)、d08790f (#219) |
contract / 四个读工具 / 权限矩阵 / 工具审计均已合并;写工具(AG8.3–8.5)与模型工具调用解析未实现,见 #93 |
| F Agent | AG9 Model Runtime | 已合并 |
6c89f97… 系列 #125/#147/#156/#161/#162;conformance dc6b0de (#165) |
结构化/流式/abort/重试/预算均已合并,见 §4.F9 |
| F Agent | AG10 Evaluation & Guardrails | E2E 验证 |
656bb70 (#118)、dc6b0de (#165)、3bbcdae (#186)、394c061 (#220)、#212 |
runner 与场景数据集已合并;工具安全九场景补齐越权 / 畸形 / 伪造类 |
「CI 绿」指该能力所在 PR 的全部必需检查在
main上通过(quality×3 OS、golden path×2、coverage、package (smoke)、CodeQL、analyze)。「E2E 验证」表示golden path里有对应的 用户可见断言。
- 定位:不导入任何材料也能走完整条学习链路。
-
用户怎么用:Home 的课程卡片(
查看/开始)→ 进入课程页;内置演示课程与导入的课程走同一条渲染路径。 - 何时发生:用户主动。
- 永不做什么:不联网获取课程;不覆盖用户自己导入的课程。
- 数据与边界:演示材料是仓库内固定文本,首次启动写入本机 SQLite。
-
状态与证据:E2E 验证 —
golden path第一个测试;main @ e596d6f。 - 已知限制:只用于演示与开发验证,不代表任意材料的生成质量。
- 依赖:无(是其他一切功能的入口)。
-
怎么验证:
pnpm e2e(apps/desktop-e2e/tests/golden-path.spec.ts)。
-
定位:把学习者自己的
.txt/.md变成课程,而不是手打。 -
用户怎么用:Home → 把文件拖到区域里,或点击区域选择文件(也仍可直接粘贴内容)→ 确认文件名 → 生成课程。拖入时区域自己会变(虚线转实线 + 强调色,文案变成「松开即可导入」),读完的文件以一行呈现:文件名、体积、
移除文件。 - 何时发生:用户主动,一次性动作。
- 永不做什么:不上传文件;不读文件系统里未选择的内容;不抓取网页。
-
数据与边界:内容走 IPC 校验后写入本机 SQLite;文件名有长度与字符规则。拖拽只接受带文件的拖动(
isFileDrag):拖来的文字选中项不进入拖入态,否则等于答应了一次什么也不会发生的放下。被拒的文件(过大/空/非纯文本/读不出)只在区域下方说明原因,且不改动表单里已有的文件。 -
状态与证据:E2E 验证 —
af2e74f(#81),含663a121(#80) 的文件名规则修正;拖拽与文件行由golden path的「a file dragged onto the zone is taken…」用例覆盖。 -
已知限制:仅
.txt/.md;不支持 PDF、Word、网页。 - 依赖:IPC 白名单 + material parser。
-
怎么验证:
golden path的导入用例;apps/desktop/electron/ipc/validate.spec.ts。
- 定位:把材料按章节转成概念 + 可执行的小任务,确定性且可复现。
- 用户怎么用:导入后自动生成,课程页看到概念、阅读/练习任务与预计时长。
- 何时发生:导入时由纯函数执行,无模型参与。
- 永不做什么:不调用模型生成任务;不对同一材料产生随机结果。
- 数据与边界:只读取材料文本;最多选取有限章节;结果全部本机持久化。
-
状态与证据:CI 绿 —
packages/agent-core/src/micro-task-generator.ts及其单测。 - 已知限制:不是模型生成,因此不理解语义;测验只在满足条件时生成。
- 依赖:material parser。
-
怎么验证:
agent-core单测;对同一材料重复生成结果一致。
- 定位:看清一门课的整体结构,以及自己走到哪一步。
- 用户怎么用:课程页查看概念摘要、材料原文、任务顺序、预计时长与完成状态。
- 何时发生:读取时派生,不产生新事实。
- 永不做什么:不在浏览时改写任务或进度。
- 数据与边界:从 SQLite 读取课程/任务/进度;材料正文是否显示由设置决定。
- 状态与证据:CI 绿 — 课程页组件 + store 读取。
- 已知限制:以单人、本地课程为单位;无共享或多设备视图。
- 依赖:A3。
-
怎么验证:desktop 单测 +
golden path。
- 定位:一次专注的最小单位,有开始、有结束、有当前位置。
- 用户怎么用:课程页开始 Session → 计时器运行 → 结束 Session。
- 何时发生:用户主动开始/结束;空闲与标签事件由系统侧产生。
- 永不做什么:不在 Session 之外记录学习事件;不静默结束 Session。
- 数据与边界:Session 起止时间、任务进度、事件写入本机 SQLite。
-
状态与证据:E2E 验证 —
golden path。 - 已知限制:计时主要由桌面 UI 管理,跨设备/跨进程不可靠。
- 依赖:A4。
-
怎么验证:
pnpm e2e。
- 定位:把「做不动」拆成可以按一下的小动作。
- 用户怎么用:开始任务;暂停/继续计时;计时结束后加一分钟;完成并进入下一个任务。
- 何时发生:由用户动作或确定性计时规则触发。
- 永不做什么:不自动跳过任务;不在用户未确认时改变任务内容。
- 数据与边界:任务状态与事件写本机;完成动作只发一次事件。
-
状态与证据:E2E 验证 —
2b4934f(#75)、257efe0(#76)。 -
已知限制:
MICRO_START/SIMPLIFY已能真正缩小、拆分当前任务(#171/#172,读时派生,不写课程);其余动作与计划级改写仍属 AG4。打开完整计划时页面会向上滚动一段:计划是从底边升起的抽屉(bottom: 16px),而步骤是从顶部排布的,所以抽屉顶边会压到步骤自己的控件上——1157×732 上实测「Start for 3 minutes」与抽屉标题被画在同一批像素上(148×32 px),按下去落到抽屉上,等于按钮按不动。缩抽屉会让五块的计划只剩 133px;预留布局空间移动不了任何东西,因为步骤是靠顶部排布的。所以改成让窗口滚动到步骤让开抽屉:只按实测的相交量滚(不是按抽屉高度),因此步骤标题不会被推出屏幕;抽屉打开期间由--plan-sheet-max给滚动容器预留这条余量,窗口尺寸变化时同一检查会再跑一次。代价是会话标题栏被滚出视野,换来的是开始按钮按得动。golden path的「the open plan never covers the step it describes」用例钉住这一点。 - 依赖:A5;其余动作与计划级改写依赖 AG4 + AG8。
-
怎么验证:
golden path的任务推进断言;learning-state单测。
- 定位:用可解释的机器状态,回答「现在处在哪种学习情境」。
- 用户怎么用:不直接操作;状态驱动干预选择与 Dashboard 分布。
- 何时发生:完全由事件驱动,确定性转移,无模型参与。
- 永不做什么:不做心理诊断;不把情境状态写成长期人格标签。
- 数据与边界:输入为任务开始/完成、答题结果、求助、标签离开/返回、系统 idle。
-
状态与证据:CI 绿 —
packages/learning-state,八态:READY、INITIATION_FRICTION、FOCUSED、CONFUSED、OVERLOADED、DISTRACTED、INTERRUPTED、RESUMING。 - 已知限制:状态质量取决于事件质量;浏览器侧的标签页级事件需要扩展,应用自身的窗口/空闲信号不需要(见 E2)。
- 依赖:事件契约 + store。
-
怎么验证:
learning-state单测(含乱序、重复事件、确定性重放)。
- 定位:让学习者用一个词说清卡在哪,而不是打一段话。
- 用户怎么用:Focus 页点「我卡住了」→ 六选一。
- 何时发生:用户主动;原因决定随后走哪条确定性规则。
- 永不做什么:不猜原因(无原因不等于默认某个原因);原因不进入长期画像。
-
数据与边界:原因以
HELP_REQUESTED事件落库;六项闭合集合:cannot-start、too-big、do-not-understand、went-wrong、cannot-recall、tired。 -
状态与证据:E2E 验证 —
534bc1c(#100),PR #100。 - 已知限制:原因被记录后,真正「改写任务」的动作仍未实现(AG4)。
- 依赖:B1。
-
怎么验证:
packages/shared-types/src/stuck.ts的闭合枚举 + IPC 校验拒绝未知值。
- 定位:什么时候该安静、什么时候给一个具体动作,由规则决定。
- 用户怎么用:建议以卡片出现,可接受或忽略。
- 何时发生:确定性策略;模型只生成内容,不决定是否打断。
- 永不做什么:不在冷却期内反复打断;不因连续求助而升级为诊断性判断。
-
数据与边界:action 为闭合集合,共 8 个,其中第一个就是“安静”:
NO_ACTION、MICRO_START、SIMPLIFY、HINT、EXAMPLE、QUESTION、BREAK、RESUME。NO_ACTION不是占位——engine 在它上面 分支,UI 不显示卡片,outcome 不把它计入接受率分母:它就是“不打扰”这条产品的实现。 -
状态与证据:CI 绿 —
packages/intervention-policy。 - 已知限制:多数建议仍是文案层,未接到可执行动作(AG8)。
- 依赖:B1。
-
怎么验证:
intervention-policy单测(映射唯一性、冷却、优先级)。
- 定位:记下建议被展示、接受、拒绝还是导致完成,供后续评估。
- 用户怎么用:无感;结果出现在 Dashboard。
- 何时发生:由用户对建议的动作触发。
- 永不做什么:不把结果当成能力评价,不生成画像。
-
数据与边界:
InterventionOutcome事件落本机;保存 requestId 关联,不保存诊断性字段。 - 状态与证据:CI 绿 — engine 派发 + Dashboard 汇总。
- 已知限制:「成功」的定义在 Rescue 评估器里才统一(§4.C3、B5)。
- 依赖:B3。
- 怎么验证:engine 单测 + Dashboard 断言。
- 定位:把「换个说法」变成「下一步做什么」,并回答救援有没有起作用。
- 用户怎么用:接受建议后看到具体微步骤;Dashboard 看救援结果。
-
何时发生:确定性:
decideIntervention→buildRescuePlan→evaluateRescueSuccess(三者均已合并;后两者在ae1d690/PR #124)。 - 永不做什么:不复制一套 reason/action 参考表(eval 直接驱动生产纯函数)。
-
数据与边界:
shared-types/src/rescue.ts+intervention-policy/src/rescue.ts;事件落本机。 -
状态与证据:已合并 —
ae1d690(PR #124);engine 派发、Dashboard 汇总与 18 个 AG2 JSON 场景均在main。 -
已知限制:
MICRO_START已把当前任务缩成首步 + 2 分钟(#171),SIMPLIFY已把任务拆成 1–5 分钟的步骤(#172);其余动作要真正改写任务前需要 AG4/AG8 的动作契约;六类 E2E 仍缺(AG2.8)。 - 依赖:B2、B3、B4;完整六类 e2e 依赖 AG4/AG8 的动作契约。
- 怎么验证:18 个 AG2 JSON 场景(happy/edge/adversarial)重复运行结果一致。
- 定位:跨过中断保存「我在哪、下一步是什么」。
- 用户怎么用:无感;恢复时读到的就是它。
- 何时发生:检测到标签离开或 idle 超阈值时,由确定性规则创建。
- 永不做什么:不保存诊断性结论;同一 interruption 不重复建卡。
- 数据与边界:当前课程/概念/任务/步骤、已掌握、未解决、下一步;写本机 SQLite。
-
状态与证据:CI 绿 —
buildCheckpoint+ 幂等持久化 + 重启后可读。 - 已知限制:内容主要从任务进度推导,尚未纳入 Tutor/救援产生的具体卡点。
- 依赖:事件契约 + store。
-
怎么验证:
continuity单测(幂等、重启一致)。
- 定位:回来时不用重新想「我刚才在干什么」。
- 用户怎么用:返回后看到卡片 → 继续 或 忽略。
- 何时发生:中断结束后由确定性规则展示。
- 永不做什么:不显示未授权历史;不因离开就重讲一遍。
- 数据与边界:卡片内容来自 checkpoint;记录展示/接受/忽略时间与恢复延迟。
-
状态与证据:E2E 验证 —
packages/continuity/src/resume.ts+golden path。 - 已知限制:只有一档,不区分离开 1 分钟还是 1 天。
- 依赖:C1。
-
怎么验证:
continuity单测 +golden path。
- 定位:离开越久,回来的门槛就越高,需要不同的开场。
-
用户怎么用(
main,三档已上屏):Short 直接继续;Medium 看完整回顾;Long 先展示所在概念的关键想法(取自上下文,非生成,#193);短档 e2e9d2e55d(#196)、长档 e2ed9f1783(#203)。 -
何时发生(分支):确定性:
gapMs决定档位(15 分钟、24 小时两个边界)。 - 永不做什么:不新增事件类型、不复制聚合数据、不把 pending 当作失败。
-
数据与边界(
main):variant/gapMs/refresher由 gap 派生;阈值集中在ResumePolicyConfig(15 分钟 / 24 小时,类型在shared-types),classifyResumeGap的 spec 钉住三档与两条边界。 -
状态与证据:已合并 — 三档与阈值(
shared-types+continuity)、指标分列96ac295(#119)、短/长档 e2e9d2e55d(#196) 与d9f1783(#203)、长档关键想法78555af(#206);九个 AG5 评测场景在packages/agent-evals/src/scenarios/ag5/。 -
已知限制:未合并;且现有「成功率」口径过宽(求助也算成功),必须按
Resume 策略与指标 拆成
reengaged/progressed/stalledAgain。 - 依赖:C1、C2;adaptive 恢复依赖 AG4。
- 怎么验证:9 个 AG5 JSON 场景,直接驱动生产 continuity 纯函数。
- 定位:让学习者(和开发者)看到过程,而不是只看结果。
- 用户怎么用:查看 Session 时长、有记录时长、完成任务、中断次数、恢复延迟,以及恢复后再参与/恢复后进步;本周证据、干预与解困结果、扩展配对信息和事件日志在「更多数据」页(仪表盘上一键可达)。
- 何时发生:读取时从事件重算。
- 永不做什么:不把统计写成能力或人格评价;不把没观测到的时间写成「离开」。
- 数据与边界:全部来自本机事件与 Session,无远端分析服务。状态占比与「有记录时长」的分母都只包含有证据的时间(见 §D2 §5)。
-
状态与证据:CI 绿 —
dashboard.page.ts+ 重算逻辑单测。 - 已知限制:长间隔 refresher 之外无未交付项;长档的 "三十秒回忆" 措辞已按 #193 的决策 C 改为「点出关键想法」,epic 与代码一致。
- 依赖:事件契约。
- 怎么验证:desktop 单测(重算一致性)。
- 定位:把单次 Session 之外的趋势也看得到。
- 用户怎么用:当前 Session / 今天 / 近 7 天 / 全部时间四个窗口切换。
- 何时发生:读取时派生。
- 永不做什么:不做跨用户比较,不做能力排名。
-
数据与边界:状态时间分布、活动日历、课程占比;全部本机重算。学习时长是时间轴上的度量:重放 reducer 得到每个瞬间的状态,处于学习状态(
FOCUSED/RESUMING/CONFUSED/OVERLOADED)的区间完整计入,因此同一个学习区间不会因为中间多写了几条事件而改变;只有未结束会话的无人见证尾部受presenceTimeoutMs封顶,且离开/中断/未开始这类非学习状态在任何位置都封顶——因此「有记录时长」是能被证据支持、可当作学习时间的时长,不等于会话窗口的墙钟时间,也不等于一段离开的全长。 - 状态与证据:CI 绿 — insights 组件 + 派生函数单测。
-
已知限制:窗口固定,不可自定义。时长口径:对外显示的是「有记录时长」(有证据支持的学习时长),不是会话时长——一段被事件夹住的两小时专注完整计入,无人见证的尾部最多
presenceTimeoutMs。单次会话已改为同一条口径(#254 后续):progress.elapsedMs(专注页进度条、首页当前会话一行)与DashboardSummary.sessionDurationMs都读recordedSessionMs,与四个时间窗同源。起因是反过来的那半边:会话不因关掉应用而结束,startedAt → now会把中间关掉的整个周末算进去,于是专注页把一次二十分钟的学习显示成21219:30(而且那个字段按分钟计,任意长度都不成句,见format.ts)。尾部到哪里为止:未结束的会话,尾部是没有后续事件的无人见证区间,学习状态最多计presenceTimeoutMs,非学习状态最多计 idle 阈值;已结束的会话,结束事件本身就是一次见证,它把尾部之前的那段区间变成「被事件夹住」的已观察区间,因此完整计入。但重放读到的日志不是无限的:listEvents默认只取每个会话最早的 500 条事件,而getInsights不传上限,因此事件数超过 500 的会话只会重放到第 500 条,已结束会话的尾部就变成从第 500 条一路算到endedAt——中间那段墙钟时间会按当时的引擎状态计入,但尾部仍受presenceTimeoutMs(学习状态)或 idle 阈值(非学习状态)封顶,不会退回到「把周末算成学习」。库里没有任何按时间裁剪日志的策略,唯一的删除是整会话清空(clearSessionEpisodic),所以情况不会随时间变坏。同一上限现在也落在单次会话的数字上(recordedMs走的是同一个listEvents),实测 500 条事件时一次getCurrentSession约 1.9ms,代价可以接受。修法仍是那两条:让重放有界地读到会话结束,或给会话一个「多久没动静就算结束」的规则——都要先定下来再改。 - 依赖:D1。
-
怎么验证:desktop 单测 +
golden path。
- 定位:可追溯的事件记录,是其他一切派生结果的唯一事实源。
- 用户怎么用:在 Dashboard 查看任务、求助、中断、恢复等事件。
- 何时发生:每次领域动作产生一条。
- 永不做什么:事件不可变;派生视图不得成为第二事实源。
- 数据与边界:append-only,写本机 SQLite;相邻重复事件在展示层折叠。
- 状态与证据:CI 绿 — event log + 折叠逻辑单测。
- 已知限制:展示层折叠不改变底层事实,导出时仍是原始条数。
- 依赖:persistence migrations。
-
怎么验证:
persistence单测(append-only、重启后一致)。
- 定位:让「切走标签」这类真实分心信号进入桌面应用。
- 用户怎么用:可选安装扩展;不装也能用——应用自己就能感知窗口失焦与系统空闲(见 E2)。
- 何时发生:扩展侧检测活动标签与 idle,向本机发送元数据。
- 永不做什么:不申请页面访问权限,因此读不到 URL、标题、正文、输入框、Cookie、历史。
-
数据与边界:只发活动/离开/返回/时长/防重放事件 id;bridge 只监听
127.0.0.1,token 每次 启动重生成,并校验协议版本、消息大小、事件类型与 payload。 - 状态与证据:CI 绿 — 扩展目录 + bridge 单测。
- 已知限制:只覆盖 Chrome/Edge。
- 依赖:IPC bridge。
- 怎么验证:bridge 单测(拒绝未知协议/超大消息/伪造事件)。
-
定位:不装任何东西也能感知「离开」与「回来」。旧开发调试栏已整条删除(#254): 它是学习者绝不该看到的一层界面,而且在每个屏幕底下压了一排调试按钮。
-
用户怎么用:正常使用。切到浏览器/PDF/笔记应用超过阈值再切回来即为一次真实中断; 系统空闲超过阈值则记为
IDLE_STARTED/IDLE_ENDED(含实测时长)。 -
何时发生:窗口失焦/回焦、系统空闲采样(随 5 秒 tick)时自动发生。
-
永不做什么:不请求任何系统权限、不读取其他窗口的内容、不在打包版与开发版之间行为不一致。
-
数据与边界:写入与扩展同一套核心事件(
TAB_LEFT/TAB_RETURNED/IDLE_STARTED/IDLE_ENDED);FOCUSLOOP_DISTRACTION_SENSOR=0可关闭(e2e 的确定性开关); 在任何一次聚焦之前发生的失焦会被忽略,空闲报告记录的是「沉默开始」的时刻而非发现时刻。 -
状态与证据:E2E 验证 — 传感器开关两例(真实
win.blur()/win.focus()会被记录; 关闭后一条都不记)+ 13 个单测。 -
已知限制:只覆盖应用自身的窗口与系统空闲,标签页级别的细节仍需扩展。
-
依赖:事件契约。
-
怎么验证:
desktop单测(distraction-sensor.spec.ts)、golden path、apps/desktop-e2e/tests/distraction-sensor.spec.ts。仍然保留的
simulate命令:它作为内部接缝存在——浏览器扩展、端到端套件与界面截图脚本 都通过它把已建模的事件送进引擎,界面上没有任何东西渲染它。
- 定位:中英文都能用,且不会漏翻。
- 用户怎么用:设置里切换语言。
- 何时发生:渲染期查表;领域层不参与。
- 永不做什么:领域包不产生用户可见句子(架构硬规则)。
-
数据与边界:
messages.en.ts定义键集,messages.zh.ts是Record<MessageKey, string>,漏一个键即 typecheck 失败;占位符一致性有专门测试。 -
状态与证据:E2E 验证 — i18n 目录 + 占位符测试 +
golden path中文断言。 -
已知限制:AG3 的 fallback 已随
107a30f(#101) 改为闭合码,由渲染期查表翻译; 同类缺口仍在——AgentContextOmission.detail仍是领域层生成的英文句子(§4.F1),按同一规则待修(§4.F3)。 -
依赖:
shared-types的闭合键词汇表。 -
怎么验证:
pnpm typecheck(漏键即失败)+ 占位符测试。
- 定位:跟随系统或固定浅色/深色。
- 用户怎么用:设置里选择。
- 何时发生:读取时应用。
- 永不做什么:不在样式里写死颜色值。
- 数据与边界:设置存本机;样式只允许用设计 token(门禁校验)。
-
状态与证据:CI 绿 — token 门禁
verify:tokens。 - 已知限制:无自定义配色。
-
依赖:
styles.css的 token 定义。 -
怎么验证:
pnpm verify:tokens。
- 定位:没有网络、没有账号、没有 API Key,核心流程一样能走完。
- 用户怎么用:什么都不配置,直接用。
- 何时发生:始终;远端 Provider 是可选增强。
- 永不做什么:不在离线时伪装成有模型回答。
- 数据与边界:Mock Provider 只用于确定性离线路径;无中央业务服务器。
-
状态与证据:E2E 验证 —
golden path。注意一处尚未达成的封闭性:main的 e2e 启动不会清除FOCUSLOOP_DEEPSEEK_API_KEY(golden-path.spec.ts只传FOCUSLOOP_DEV),所以如果开发机导出了这个变量, 这条路径就在跑真实 Provider,而不是它声称的离线路径。 - 已知限制:离线时没有模型级问答。
- 依赖:llm-provider 的 provider 选择。
-
怎么验证:
pnpm e2e(即上条注明的封闭性问题修复后,才算验证了离线路径)。
- 定位:想用远端模型时才加载它,默认不存在。
-
用户怎么用:设置
FOCUSLOOP_DEEPSEEK_API_KEY等环境变量;界面显示当前运行模式。 - 何时发生:启动时根据环境变量决定。
-
永不做什么:不写 Key 到仓库或数据库;不在
main的 UI 流程里静默调用。 -
数据与边界:基础 URL 规范化和错误归类在
llm-provider;当前main的正常 UI 流程不会 发问给模型(Tutor 才需要,见 §4.F3)。 -
状态与证据:已合并 —
packages/llm-provider;b3822b5(#70) 修过 CodeQL ReDoS。 - 已知限制:无结构化输出、无 abort、无流式、无 token 预算(AG9)。
- 依赖:AG9 才能成为统一 Runtime。
-
怎么验证:
llm-provider单测(错误归类、URL 规范化)。
- 定位:曾经用于在开发模式查看「Agent 现在能看到什么」(Context)与「这一次实际发给 Provider 什么」(Outbound),#219 又在同一面板上加了第三个 Tab(工具审计)。
-
状态:三个 Tab 一起移除(面板
fl-agent-context-panel、core/inspector-visibility.ts、core/tool-call-view.ts、三个 IPC 通道getAgentContext/getOutboundRequest/listToolCalls、引擎里的 outbound 缓冲与全部agent.inspector.*文案,中英各一套)。 不是隐藏,是删除:没有任何调用方之后,留着通道与文案只是同一件事的半份。 -
为什么移除:它不是产品功能,而是开发期调试视图;AG1 的边界与 omission 已经有单测与
AG1 场景覆盖,出站字符数也已经由 Tutor 预算与
engine.spec的inputCharacters = system.length + prompt.length断言保证,因此这块界面没有它自己的读者。 -
保留了什么:
AgentContext与buildAgentContext一字节未动——那是 Agent 真正的输入, Tutor / Rescue / Resume / 工具契约都读它;engine.getAgentContext()也保留(工具契约内部使用)。 工具审计的数据与查询同样保留(tool_calls表、写前脱敏、store.listToolCalls的 join 与其 测试)——被删掉的是它的屏幕视图与那条只读通道,不是审计本身。 -
隐私影响:
docs/privacy.md已同步——「实际发出去的内容」不再有屏幕视图,验证方式回到 阅读deepseek-provider.ts的请求体。工作记忆(ADR 0001)从「transcript + 最后一个 outbound prompt」变为只有 transcript:该 ADR 的表格与失效表已更新,AGENT_MEMORY_SOURCES从九项减到 八项,面板上的source.outbound/impact.outbound文案一并删除。 - 依赖:无(移除后不阻塞任何能力)。
-
怎么验证:删除后
pnpm test、四道 gate、以及 desktop e2e 全绿即证明没有遗留读者。
-
定位:给 Agent 一个有界、可解释的「当前时刻」视图。
main上有界且做字段级剥离:事件按AgentContextEvent的逐类型 allowlist 投影,#188 起为穷举——新增事件类型而不写投影是编译错误,不再可能悄悄从每个上下文里消失。 - 用户怎么用:间接(Tutor / Rescue / Resume / 工具契约都读它)。没有屏幕视图——AG1 的调试面板(Context 与 Outbound 两个 tab)已整体移除,见 §E7。
-
何时发生:每次需要上下文时由同一个 builder 构建(
agent-core/src/agent-context.ts,对AgentContextSource纯函数)。 -
永不做什么:不带其他课程内容、完整日志、密钥、URL。事件投影后只保留
type/at/source/payload——id与sessionId不进上下文,TAB_LEFT的 payload 为空(origin 在内的所有字段丢弃),未知字段在边界被拒绝;反例由sensitive-content-adversarial.json在评测层钉住。 -
数据与边界:材料 1200 字符、最近 12 条事件、checkpoint 为有界摘要(
AgentContextCheckpoint:文本/条目/参数上限同在AGENT_CONTEXT_LIMITS),超限记为 omission;非法与超长输入被拒绝且有测试(#97、#188)。 -
状态与证据:已合并 — schema 与跨桥契约
63acc28(#99);逐类型投影穷举与敏感 payload 回归d938bb8(#188);shared-types/src/agent-context.ts+agent-core/src/agent-context.ts;评测层packages/agent-evals/src/scenarios/ag1/(含隐私类场景,#220)。 -
已知限制:原「两个 Inspector 视图」的验收已随面板移除而作废(见 §E7)——Context 显示 Agent 可访问的数据、Outbound 显示本次实际发送的内容,而 Tutor 会在 AG1 之上再裁剪一次,因此两者永不相同;现在这条断言落在引擎侧(
engine.spec:inputCharacters = system.length + prompt.length),不再有界面可核对。 - 依赖:事件契约、store、material parser、IPC。
- 定位:学习者说清卡点后,给一个能立刻做的动作,并记录结果。
- 用户怎么用:六选一 → 接受/忽略建议 → 继续任务。
- 何时发生:原因 + 状态 + 确定性策略。
- 永不做什么:不猜原因;不自动改计划;不静默升级打扰频率。
- 数据与边界:原因、建议、结果都作为事件落本机。
-
状态与证据:已合并 —
534bc1c(#100);Rescue 计划与成功评估器同样已合并(ae1d690,PR #124);MICRO_START接受后真正缩小任务(#171)、SIMPLIFY接受后真正拆成步骤(#172):确认 + 幂等提案,课程只在读时派生。HINT/EXAMPLE 的可选 provider 生成行(#205):卡面标注model-generated,无 key 不出机器,失败/超限回落 grounded quote,隐私句与数据路径同改。 - 已知限制:其余动作要真正改写任务前需要 AG4/AG8 的动作契约。
- 依赖:F1;可执行动作依赖 AG8。
-
怎么验证:
intervention-policy单测 + AG2 JSON 场景 12 个(rescue/rewrite/干预 ×3/grounding ×6,grounding 含生成行三态 #205,packages/agent-evals)+rescue-suggestion.spec(离线地板、预算单次、失败回落、零写入)+golden path。
- 定位:围绕当前这一步问六个具体问题,而不是「随便问」。
- 用户怎么用:Focus 页 → 打开 Tutor → 选模式(EXPLAIN / HINT / EXAMPLE / SOCRATIC / CHECK_MY_ANSWER / SUMMARIZE)→ 提问。
- 何时发生:用户主动提问;模型只生成内容,是否打断与是否记录学习事件由确定性规则决定 (提问不产生学习事件)。
-
永不做什么:渲染进程不能提供对话历史(只能发
sessionId+mode+question,避免把字塞进 模型嘴里);CHECK_MY_ANSWER不得只说 Yes/No;不伪造材料来源;不越权访问其他 session。 -
数据与边界:
TUTOR_LIMITS关闭集合——保留 8 轮、问题 2000 字符、答案保留 600 字符、每个 part 600 字符、上下文块每字段 800 字符,整个 prompt 以一个总量上界约束;transcript 只在主进程内 存续,endSession时遗忘。 -
状态与证据:已合并 —
107a30f(PR #101); 必需检查在main上通过。 -
已知限制:i18n 违规已修复 — 领域层只返回闭合码(
TutorFallbackReason),describeUnavailable/describeRejection已不存在,渲染端用TUTOR_FALLBACK_KEYS出句子, 中文界面不会再出现英文 fallback。同类缺口仍在:AgentContextOmission.detail仍然由agent-core拼成英文句子(agent-context.ts、tutor.ts、tutor-ask.ts、engine.ts多处), 并在Inspector 与tutor 报告里原样渲染——已开 issue 按同一规则修。 - 依赖:F1(上下文)、AG9(abort/流式),质量基线依赖 AG10。
-
怎么验证:
tutor.spec.ts、tutor-ask.spec.ts、tutor-view.spec.ts+golden path里的中文 tutor 断言(fallback 文案为中文)与 Escape / 跨步骤存的断言。
- 定位:任务太大或形式不合适时,提议一个更小的任务,而不是替学习者决定。
- 用户怎么用:看到前后对比(时长、内容、原因)→ 接受或保持原样。
- 何时发生:确定性 builder 提议;模型不直接执行。
- 永不做什么:未确认不写结构性变更;不生成无关内容;不破坏进度与位置语义。
-
数据与边界(计划):
AdaptiveTask、AdaptationProposal、SessionPlanRevision; 子任务 1–5 分钟且保留 parent 关系。 -
状态与证据:设计完成 — 方案页 AG4;
main上有MICRO_START/SIMPLIFY的读时派生改写(#171/#172),但没有持久化的AdaptiveTask/SessionPlanRevision。 -
已知限制:计划级改写完全没有实现(无持久化任务、无前后对比预览、无 plan revision)。依赖顺序已修正:AG4 只依赖 AG8 的
confirmation/idempotency primitive;原先「依赖 AG7 episodic schema」的写法会造成依赖倒置(AG7 排在
AG4 之后),已改为「如需 episodic 查询,拆出 AG7a 并提前」。该依赖已满足:信封
bf0844b(#126)、契约e59ea9b(#217)、生命周期工具#238与自适应任务工具(AG8.4,#227)——AG8 phase 2 落地后,AG4 的计划级改写不再有任何 AG8 侧前置。 - 依赖:AG8 确认/幂等;AG10 安全场景。
- 怎么验证:待实现;验收要求见方案页 AG4 测试矩阵。
- 定位:中断之后最短路径回到原来的任务。
- 用户怎么用:Resume Card 三档(见 §4.C3)。
- 何时发生:确定性(gap 分档 + interruption 检测)。
- 永不做什么:不重复讲解(短离开);不恢复到「下一个未完成任务」而不是 checkpoint 的位置。
-
数据与边界:
LearningCheckpoint、ResumeCardTiming、ResumePolicyConfig(均在main)——阈值集中在ResumePolicyConfig,15 分钟 / 24 小时两条边界由classifyResumeGap的 spec 钉住。 -
状态与证据:已合并 —
packages/continuity;三档在main,指标分列96ac295(#119)(reengaged / progressed / stalledAgain),DashboardresumeOutcomes,九个 AG5 评测场景。 - 已知限制:指标口径必须改名(§4.C3);adaptive 恢复与材料定位未做。
- 依赖:C1;adaptive 恢复依赖 AG4。
-
怎么验证:
continuity单测 + 9 个 AG5 场景(分支上)+golden path。
- 定位:一周之后回头看,哪些做法对自己有效——以证据说话。
- 用户怎么用:看复盘卡 → 每项建议带样本量与时间窗 → 「查看并确认」打开既有确认屏 (值 + 样本数 + 窗口两端分行可见)→ 确认入库,或婉拒——婉拒按候选身份持久,同一批证据 不再反复提议;随时可在数据面板忘记(AG7.6)。
- 何时发生:只从行为事实统计,不推断人格。
- 永不做什么:不输出诊断或能力标签;观察到的偏好不得自动成为长期存储。
-
数据与边界(
main):LearnerPreference(判别联合 + 词表门)、PREFERENCE_WINDOW_MS28 天、 样本下限 3;偏好只在显式确认后保存——确认前它们只是候选建议,不进learner_preferences。 -
状态与证据:AG6.1–6.7 已合并 — 价值词表
e81f034(#241)、三派生2453035(#242)、 每周反思2640719(#243)、建议清单与建议行 (#235/#247)、确认入库 (#236:候选 id → 主进程 重派生并冻结 value+evidence → 确认屏 → 信封事务内insertLearnerPreference;ADR 0003 同改补preference-write格;忘记偏好时事务内清掉 proposal 与事件里的快照副本)。 - 已知限制:建议行只在样本达标(≥3)时出现,样本不足是「没有建议」而不是空白行; 拒绝按候选身份持久——换了新证据的同 scope 会再次提议(设计如此);效果对照 (建议应用后能否测量)未做。
- 依赖:AG7。
-
怎么验证:
preference-candidates.spec(run-twice 等值、id 跨读取时刻稳定、样本线、只读断言)-
preference-confirmation.spec(冻结快照、仅执行入库一次、拒绝/过期/状态变化零写入、篡改回滚、 忘记清除快照)+memory-view.spec建议行 + golden-path E2E(确认入库 / 旧哈希拒绝 / 婉拒后不再出现)。
-
- 定位:记忆分层且可检查、可删除,不是黑箱画像。
-
用户怎么用:「Your data」区列出各来源的 scope、数量、最新时间与删除影响(措辞取 ADR 的术语,绝不是内容本身);清除走自己的两段式确认框;单条偏好可「忘记」。来源为 transcript 等八项(
outbound随 #225 移除)。 - 何时发生:Working 从当前 session 派生;Episodic 是已有事实的查询;Preference 走 AG6 确认。
- 永不做什么:不复制完整日志或材料;不存诊断/智力/人格/心理健康推断。
-
数据与边界(
main):getMemorySummary(九/八来源计数 + 不透明审计行)、listMemory(有界时间窗读取,MEMORY_QUERY_MAX上限与截断标记)、cleanupOldEpisodicMemory(保留期AGENT_MEMORY_RETENTION_MS= 90 天,运行中会话被按 id 排除)、listPreferences/deletePreference(幂等、按 session 拒绝他人行)、clearAgentMemory;全部结果只含元数据,面板侧有键白名单扫描测试。 -
状态与证据:已合并 — 删除语义 ADR 0001(#110,
6a4a0cf);检查面板与 IPC5e3d764(#221);偏好存储与单项删除(含证据必填与不透明删除审计)cb2d33a(#222);时间窗有界读取与跨 session 批量清理d40ba0a(#223)。测试:memory-summary.spec(含无内容键扫描)、preference.spec、episodic-memory.spec、memory-clear.spec(write→clear→query 三路回归)、store 层裸列扫描。 -
已知限制:删除语义已按 ADR 0001 冻结(物理删除;Dashboard 不得使用被清除行;
审计仅 opaque id + 时间 + actor)。仍开放:preference 的产生链路属 AG6(确认后才写入,#91);
时间窗清理目前只有 IPC 面、产品内尚无触发点(见调度页);working 记忆只剩 transcript 轮次
(
outbound缓冲随 #225 的面板移除一并删除)。 - 依赖:ADR 0001、persistence migrations。
-
怎么验证:
agent-core/src/memory-clear.spec.ts(每类写→清→查空,含 dashboard/context/transcript)-
persistencestore 单测。
-
- 定位:让模型能请求动作,但永远不能直接动数据。
-
用户怎么用:结构性变更从确认屏读起——待确认参数、等级、发起方与拒绝原因(过期 / 状态已变 / 哈希不符)都上屏(
b870e00#218,e2e 两条:propose→confirm→execute 与等过期→拒绝可见);reversible 级已落地(#238–240),各格回头路依 ADR 0003 §3——rewrite 读时派生随任务结束、偏好可忘记(AG7.6)、计时器两格 learner-only 无模型入口(#237)。 - 何时发生:LLM 结构化 tool call → 校验 → 领域命令 → 学习事件。
- 永不做什么:LLM 永不直写 SQLite;不能传 SQL 或任意 IPC channel。
-
数据与边界(
main):AgentTool/ToolCall(shared-types/tool.ts)、ToolRegistry(main 内校验 schema/权限/session,直路只跑 safe-read)、三级权限与逐格理由见 ADR 0003;写前脱敏redactToolArgs;tool_calls表 + 单查询 join(d08790f#219,屏幕视图随后被 #225 移除,表/脱敏/查询保留);四类读工具读的是AgentContext切片。 -
状态与证据:已合并 — 确认信封
bf0844b(#126)、权限矩阵b624064(#216)、契约与四个读工具e59ea9b(#217)、确认屏b870e00(#218)、工具审计d08790f(#219);写工具 phase 2 — lifecycle99f38f9(#238)、adaptive5614a94(#239)、session-pland1ab7b4(#240);计时器 learner-only 决定 + registry 钉死(e439254#250,ADR 0003 §3b)。测试:tool-registry.spec(对抗:未知工具 / 坏 schema / 跨会话 / 越权 / 原型污染)、proposal.spec(TOCTOU、幂等、过期)、golden-path 两条确认屏 e2e。 -
已知限制:模型侧工具调用解析还没有入口——
executeToolCall有契约与审计但没有 skill 调它(#246);pauseTask/extendTask按 #237 的产品决定永不注册(模型点名 →unknown-tool,tool-registry.spec钉死,将来注册即 CI 红);原「confirmation/idempotency 是 AG4 的硬门槛」已满足(#126)。 -
依赖:AG9 结构化输出(已合并;
executeStructured尚无 skill 调用者)。 -
怎么验证:越权 / 重放 / 坏 schema / 原型污染在
tool-registry.spec,TOCTOU 与幂等在proposal.spec,确认屏两条在 golden path;写工具对抗场景九条已由 #212 按矩阵补(AG8 ×9);learner-only 钉死在tool-registry.spec(#250)。
- 定位:把「用哪个模型、超时怎么办、降级成什么」收进一层,业务不再关心 Provider。
- 用户怎么用(计划):Runtime Info 显示 provider / model / offline / degraded。
- 何时发生:skill 只依赖 runtime 接口。
- 永不做什么:日志不记 prompt 原文;Provider 不接收未授权字段;abort 后不提交迟到结果。
-
数据与边界(计划):
RuntimeResult { status, output, provider, usage, latency, degraded, failure }、ProviderHealth。 -
状态与证据:已合并 —
AgentRuntime(llm-provider/src/runtime.ts):请求/信号拆分 #111、取消与总截止 #142→#147、预算 #143→#156、流式 #144→#161、重试与回退 #145→#162、AG9 一致性与 provider-failure 场景dc6b0de(#165);conformance 证据记于docs/ag9-conformance.md,ADR 见 ADR 0002。 -
已知限制:数据模型按分析(原 #10)拆为可序列化的
RuntimeRequestData与仅进程内的RuntimeExecutionOptions { signal }(#111,已合并);「流式文本」与「最终结构化结果」分别定义(executeStructured/executeStructuredViaStream)。尚无 skill 调用结构化门——ag9-conformance.md如实记为 outstanding,是 AG8 工具调用要进的门。 - 依赖:共享 provider 契约;AG10 一致性测试。
- 怎么验证:待实现;需要 conformance suite(成功/超时/401/限流/坏 JSON → fallback)。
- 定位:把「这次改得好不好」变成可重放、可在 CI 阻断合并的证据。
- 用户怎么用:无感(开发者与 CI 使用)。
- 何时发生:开发/CI 时运行固定场景。
- 永不做什么:不从生产应用上报评测数据;场景不得含真实用户数据。
-
数据与边界(
main):packages/agent-evals——版本化场景、受限路径解析、确定性 runner、结果与隐私 断言。JSON 场景按能力分目录,共 42 个:AG1 ×8(含隐私类 3)、AG2 ×12(含 grounding 类 6、干预恰当性类 3)、 AG3 ×3(follow-up)、AG5 ×9、AG8 ×9(工具调用安全:只读直通、越权、畸形参数、会话错配、确认绕过、 伪造幂等键、重放)、AG9 ×1;每类 ≥3 个场景,覆盖正常 / 边界 / 失败或越权。 -
状态与证据:已合并 — runner 与 AG1 投影场景
656bb70(#118)、AG9 provider-failuredc6b0de(#165)、 rewrite/grounding cases3bbcdae(#186);follow-up、干预恰当性、grounding、隐私四类场景补齐(#211); grounding 生成行三态(#205); AG8 工具调用安全九场景(越权 / 畸形 / 伪造 / 会话错配 / 确认绕过 / 重放,#212)。 -
已知限制:仍是 deterministic、同步、JSON-only runner,不含真实模型评测。
遥测口径已选定 (A):评测报告仅在开发者本机或 CI 中生成;生产应用不做遥测、
分析或崩溃上报(见
docs/privacy.md决策节与 #115)。选项 (B) 已否决,除非先改隐私文档。 - 依赖:横切全阶段。
-
怎么验证:
pnpm test(agent-evals项目)+ 仓库级 required checks;场景数 = 各能力目录的 JSON 文件数。
| 能力 | 状态 | 说明与证据 |
|---|---|---|
| Monorepo / pnpm / Nx | 已合并 |
pnpm-workspace.yaml、nx.json;包边界由 eslint 约束 |
| CI 必需检查 | CI 绿 |
quality ×3 OS、golden path ×2、package (smoke);运行链接见 §1.1 |
| 分支保护 | 已合并 | (仓库设置,无法从 checkout 校验) strict、“不允许绕过上述设置”、无 auto-merge |
| IPC 信任边界 | CI 绿 | Electron sandbox + contextIsolation + 白名单 channel + 二次校验;main 检查同 §1.1 |
| 持久化迁移 | CI 绿 | append-only migrations + 空库/旧库测试;main 检查同 §1.1 |
| i18n 编译期强制 | CI 绿 | 漏键即 typecheck 失败;占位符一致性测试;main 检查同 §1.1 |
| 主题 token 门禁 | CI 绿 |
verify:tokens 禁止字面色值;main 检查同 §1.1 |
| 文档与工作流门禁 | CI 绿 |
verify:docs、verify:workflows、verify:scaffolding;main 检查同 §1.1 |
| Release 流程 | 已合并 |
release.yml;当前只有一个 Draft v0.1.0-demo,未正式发布 |
G 区(工程与质量护栏)是基线能力:没有“引入 monorepo”这样的单一 merge commit 可引,所以这几行的 证据指向实现它的文件,并统一引用 §1.1 里
main的必需检查;门禁行同时给出实现它的脚本名。 AG1–AG10 的每一行则必须给出 commit 或 PR,不适用本节的放宽。唯一的例外是“分支保护”:它是 仓库设置,任何 checkout 都无法校验,已在行内标明。
以下不得被描述为当前产品功能:
- PDF / Word / 网页材料导入、移动端、多人协作、云端账号与同步;
- 自动诊断 ADHD 或其他心理/认知状态;摄像头、麦克风、眼动、屏幕录制;
- Agent 自动或静默改写学习计划;长期学习者画像;
- 模型直接访问数据库、文件系统或任意 Electron IPC;
- 已发布的 Contextual Tutor、Task Adaptation、Reflection、完整 Agent Tool System、 已合并的 Agent Eval 门禁;
- 任何形式的遥测、分析或崩溃上报(见 §4.F10)。
- 本页与 实施进度 的状态只允许使用 §1.1 的七级阶梯,不得越级。
- 每次功能合并同步更新:状态、证据链接、已知限制、验收结果。
- 未合并分支的成果只能标「分支完成」,并在“已知限制”里写明分支名与 commit。
- 分支被合并、关闭或重写后,本页必须同步更新;否则本页不再具备台账资格。