Repository navigation
Delivery Roadmap
状态:实施基线;基于 2026-09-21 仓库静态审查,2026-09-22 复核。本文不把“已有同名 UI/类型”自动视为能力完成,而按端到端闭环判定。
事实基线:默认分支
main@e596d6f。本节第 2 节的证据包含了当时可见的功能分支,所以 「已形成」未必意味着代码在main上:逐项准确状态以 功能清单 的七级阶梯为准, 两份文档不一致时以功能清单为准。
建议将 docs/wiki/ 作为“当前产品与工程事实”,现有 docs/architecture.md、docs/testing.md 等继续作为稳定基线文档。Wiki 首页按以下结构导航:
Home
├─ 00 Product
│ ├─ Product Positioning(不是聊天机器人;学习连续性 Agent)
│ ├─ Core Loop(Context → Trigger → Policy → Skill → Tool → Memory → Eval)
│ ├─ UX Principles(低打扰、行为语言、确认后写入、local-first)
│ └─ Demo Journeys(卡住恢复、当前步骤辅导、中断续接)
├─ 10 Domain
│ ├─ Learning State & Events
│ ├─ Course / Concept / Micro Task / Material
│ ├─ Checkpoint & Resume
│ └─ Intervention & Outcome
├─ 20 Agent Capabilities
│ ├─ AG1 Learning Context
│ ├─ AG2 Stuck Rescue
│ ├─ AG3 Contextual Tutor
│ ├─ AG4 Task Adaptation
│ ├─ AG5 Cognitive Resume
│ └─ AG6 Learning Reflection
├─ 30 Agent Infrastructure
│ ├─ AG7 Memory
│ ├─ AG8 Tools & Actions
│ ├─ AG9 Model Runtime
│ └─ AG10 Evaluation & Guardrails
├─ 40 Architecture & Contracts
│ ├─ Package Boundaries
│ ├─ Context / Prompt Data Flow
│ ├─ Tool Permission Model
│ ├─ Persistence & Migrations
│ └─ IPC / Extension Trust Boundaries
├─ 50 Delivery
│ ├─ Capability Matrix(本文第 2 节)
│ ├─ Roadmap & Dependency Graph
│ ├─ ADR Index
│ ├─ Release Readiness
│ └─ Known Risks / Debt
└─ 60 Quality & Operations
├─ Test Strategy
├─ Agent Eval Scenarios
├─ Privacy & Data Inventory
├─ Observability / Audit
└─ Runbooks(provider failure、migration、release)
每个 AG 页面统一使用六段模板:目标与非目标、用户旅程、契约/数据、当前证据、验收场景、开放问题。这样 Wiki 是可验收的事实库,不是另一份愿景文档。
状态含义:本节标题现在使用 功能清单 §1.1 的七级阶梯,以便与台账逐字对照。原先的
“已形成 / 部分形成 / 未形成”只按“主链路是否存在”判断,不区分 main 与分支,正是本次要修掉的模糊。
- 当前证据(
main):shared-types/agent-context.ts定义边界和 omission;agent-core/agent-context.ts构建当前 session/concept/task/material/state/events/checkpoint;材料 1200 字符、事件 12 条;有单元、engine 测试。开发模式的 Inspector 面板与它的两个只读 IPC 通道已整体移除(见project-features.md§E7);AgentContext与engine.getAgentContext()本身不变——工具契约、Tutor、Rescue、Resume 都读它。 - 当前证据(投影,已合并):
AgentContextEvent的逐类型投影与穷举断言d938bb8(#188);评测层敏感 payload 场景packages/agent-evals/src/scenarios/ag1/(含隐私类,#220)。 - 差距:已闭合——字段级 allowlist 即
AgentContextEvent联合与projectEvent(穷举,新增类型不写投影是编译错误);恶意/敏感 payload 的固定回归语料在agent-context.spec与scenarios/ag1/。 -
原「两个 Inspector」的验收已作废:那两个视图(Agent 可访问的数据,与这一次实际发给 Provider 的内容)都已移除。它们的区分曾经成立——Tutor 会在 AG1 上下文之上再次裁剪并拼装 system / preamble / question——但视图本身没了,所以“两者都有视图、差异可被解释”不再是可验收的条目。取而代之的断言是引擎侧的一条:
inputCharacters = system.length + prompt.length(engine.spec),出站字符数由 Tutor 预算保证。 - 验收标准:任意 session 只包含当前课程路径所需数据;材料、事件、总 prompt 均在声明上限内;所有裁剪都有 omission;不得出现其他课程内容、完整日志、密钥、URL path/query、表单内容;无 session 返回显式空上下文。
- 依赖:现有 domain types、store、material parser。
- 风险:事件 payload 将来扩展后绕过过滤;字符预算与真实 token 预算偏差。
- 实施步骤:写 Context Data Contract → 建字段 allowlist/denylist → 加敏感 payload fixtures → 加预算与跨课程隔离回归测试。
- 当前证据:六类
StuckReason;UI picker;reason→action 确定性映射;HINT/EXAMPLE 的可选 provider 生成行(#205:卡面标model-generated、离线地板、失败回落、隐私数据路径同改);MICRO_START/SIMPLIFY/HINT/EXAMPLE/BREAK等 intervention;cooldown、预算、升级规则与 outcome 记录均有测试;MICRO_START与SIMPLIFY已真正改写任务(#171、#172,确认 + 幂等提案,课程只在读时派生)。 - 差距:
HINT/EXAMPLE/BREAK/RESUME仍是 intervention descriptor/文案,未生成可执行临时步骤;救援成功的定义未形成统一窗口指标;“换一种解释/例子”与 AG3 Tutor 的复用边界需固定。 - 验收标准:六类原因逐一触发预期 action;主动打断只能由 deterministic policy 决定;所有展示均可接受/拒绝并记录;接受后能进入具体下一步;在规定窗口内以“开始/完成下一微步、无重复求助”计算 outcome;离线仍可完成每类基础救援。
- 依赖:AG1;AG8 的动作合同(对可执行救援);AG10 scenario harness。
- 风险:同一求助重复消费;干预过频;把“疲劳”固化为长期画像;任务改写被当作对课程的写操作而不是读时派生。
- 实施步骤:定义 RescueResult 与成功窗口 → 固定 AG2/AG3 路由 → 完成 outcome evaluator(已合并,PR #124) → 将 MICRO_START/SIMPLIFY 接到任务改写(AG2.3 #171、AG2.4 #172,均已合并) → 做六类 E2E(AG2.8)。
- 当前证据(
main的107a30f,PR #101):六种 TutorMode 全部建模;当前步骤入口;主进程保存有界 transcript;结构化 parts 校验;格式失败可重试;回答与用户原话引用校验;材料 section grounding 与 source 展示;provider 失败有本地 fallback(闭合码,渲染期查表);大量边界测试。 - 差距:真实 provider 下的质量基线与双语场景数据不足;当前“source”是所给 excerpt,不是细粒度引用定位;流式/取消属于 AG9 未完成;会话 transcript 未持久化且缺少用户可清除入口(需明确这是隐私选择还是缺口)。
- 验收标准:六模式只产生允许的 parts;问题自动绑定当前 task;切换 task/session 不串答;follow-up 不越过上下文预算;无材料依据时不伪造来源;错误格式、provider failure、offline 均有可理解降级;中英文核心场景通过固定 eval。
- 依赖:AG1、AG9;AG10 grounding/quality eval。
- 风险:结构正确但教学质量差;引用标题匹配不等于事实支持;多轮对话造成 prompt injection/成本增长。
- 实施步骤:冻结 Tutor contract → 建中英场景集 → 增加精确 section anchor → 接 runtime abort/stream → 明确 transcript 生命周期与清除策略 → E2E 覆盖六模式中的关键三模式。
- 当前证据:课程导入时有 micro-task generator;policy 能选择
SIMPLIFY;#171/#172 已把MICRO_START/SIMPLIFY接到读时派生的任务改写(确认 + 幂等提案,课程不被写入);既有 session plan UI/任务生命周期可作为接入点。 - 差距:没有
AdaptiveTaskschema、持久化的 SHRINK/SPLIT/CHANGE_MODALITY 服务、plan reorder proposal、adaptive practice persistence;MICRO_START/SIMPLIFY不等于计划的持久化修订。 - 验收标准:生成的 adaptive task 绑定来源 task/concept/reason,单步 1–5 分钟且可恢复;结构性变更必须先展示 diff 并由用户确认;拒绝不改变 plan;接受后持久化并发出事件;重复提交幂等;离线至少能模板化 shrink/split。
- 依赖:先完成 AG8 工具/权限(硬依赖);AG10 safety tests。
- 依赖倒置修正:本文原先写“AG4 依赖 AG7 episodic schema”,而 Phase 3 (AG4) 排在 Phase 4 (AG7) 之前, 构成依赖倒置。实际 AG4 需要的是“确认 + 幂等”这组原始能力,它属于 AG8。因此改为: AG4 只依赖 AG8 的 confirmation/idempotency;若确实需要按时间窗回溯历史,就拆出 AG7a (有界 episodic 查询) 并提前,而完整的 Memory 检查/删除仍留在 AG7。
- 风险:破坏 progress 语义和 task position;生成重复/循环任务;模型越权静默改计划;迁移后旧 session 不兼容。
- 实施步骤:ADR 定义 temporary step vs persistent adaptive task → schema/migration → 纯函数 proposal builder → confirmation UI → command/event/persistence → restore/resume → eval/E2E。
- 当前证据(
main):checkpoint builder、幂等持久化、interruption detection、接受/拒绝、latency 均已存在。 - 当前证据(
main,已合并):ResumeCard 按 15 分钟/24 小时边界分为 Short/Medium/Long(短档 e2e9d2e55d#196、长档 e2ed9f1783#203),Long 展示概念关键想法(取自上下文,非生成,78555af#206);指标已按 重新参与指标 分列为reengaged/progressed/stalledAgain(96ac295#119),Dashboard 读resumeOutcomes;AG10 用生产 continuity 纯函数覆盖固定场景(9 个 AG5 场景在main)。 - 差距:checkpoint 内容主要由任务进度推导,尚未捕获 Tutor/救援产生的“具体卡点”;adaptive task 状态无法恢复;恢复后尚不能直接定位 material section;真实用户阈值仍需产品数据校准。
- 验收标准:按离开时长确定三档且边界可配置、确定性可测;卡点来自最新有效学习证据;同一 interruption 只生成一 checkpoint/card;adaptive 子步骤可恢复;记录 latency,并在恢复后的窗口内记录 success/failure;跨日返回提供概念关键想法 refresher(取自上下文)而非直接开长任务。
- 依赖:AG2 outcome、AG4 adaptive state、AG7 episodic query、AG10 resume eval。
- 风险:过时 checkpoint;时区/系统时钟异常;resume card 太长反而增加重启成本;长期卡点包含不必要敏感文本。
- 实施步骤:已完成 gap bands → 三档纯策略 → refresher → success evaluator;后续为 checkpoint 纳入有界 Tutor/Rescue evidence → material 定位 → adaptive restore → 完整三档 E2E。
- 当前证据(
main):偏好模型(词表e81f034#241)、三派生(2453035#242)、每周反思 (2640719#243)、建议清单与建议行(#235/#247)、确认入库(#236:冻结快照经确认屏入信封事务, ADR 0003 同改补preference-write格)已在产品里;dashboard/insights、events、outcomes 是统计输入。 - 差距:效果对照(建议应用后能否测量)未做。
- 验收标准:只从最小样本量以上的行为事实形成建议;展示证据窗口和不确定性;永不输出诊断/能力标签;偏好只有用户确认后才存;可编辑、撤销、删除;建议应用后能测量效果且不自动无限强化。
- 依赖:AG7 preference store、AG8 confirmed preference tool、AG10 fairness/privacy scenarios。
- 风险:小样本伪规律;把情境行为当人格;确认疲劳;反馈循环;跨课程偏好错误泛化。
- 实施步骤:先写伦理/语言规范 → 定义统计特征和最小样本 → reflection proposal(只读)→ confirmation → preference store/UI → 效果对照 → weekly summary。
- 当前证据(
main):当前 session/context 是 working-memory 等价物;events/checkpoints/interventions/outcomes 是 episodic 数据;SQLite local-first 且有迁移与 round-trip 测试。三类边界由AGENT_MEMORY_SCOPES与聚合读取固定(5e3d764,#221);偏好有表、有单项删除与不透明审计(cb2d33a,#222);episodic 有按时间窗的有界读取与跨 session 批量清理(d40ba0a,#223)。 - 差距:
AgentContextOmission.detail仍是英文句子(§4.F3);preference 的产生路径属于 AG6(尚无确认链路),当前 API 只负责存放、读回与删除;时间窗清理目前只由 IPC 暴露,产品里还没有触发点。 - 验收标准:Working/Episodic/Preference 三类边界清晰;每类有 purpose、来源、保留期、读取者;偏好显式、可编辑、可单项删/全清;清除后上下文与反思不再引用;禁止存储诊断、智力、人格、心理健康推断;所有 query 有数量/时间窗上限。
-
删除语义已冻结 — 见 ADR 0001(#110):
- Working / Episodic / Preference 均为物理删除(Preference 待 AG6/AG7 实现时同规则)。
- Dashboard/Insights 不得再使用被清除的 episodic 行;派生路径由删表自然清空。
- 审计仅保留
session_id+cleared_at+actor(agent_memory_clears)。 - 无长驻缓存;失效 = 删读取面(transcript Map + episodic 表),回归测试覆盖 dashboard / context / transcript。
- 依赖:privacy ADR、persistence migrations;AG6/AG4 消费其能力。
- 风险:删除不彻底(派生表/缓存);scope creep;长期日志增长;同步功能未来破坏 local-first 假设。
- 实施步骤:
删除语义冻结(已完成,ADR 0001)→ Data Inventory → MemoryPolicy/Query contract → episodic bounded queries → preference migration/repository → inspection & delete UI → cache invalidation tests → privacy regression。
- 当前证据(
main):engine、IPC 已有 start/pause/resume/complete、事件分发等应用命令;输入验证和事件日志可复用。AgentToolcontract 与注册表、四个读工具在主进程校验(e59ea9b,#217);安全读/可逆写/结构写三级权限冻结为 ADR 0003(b624064,#216);每次尝试都有tool_calls审计行,参数落库前脱敏、事件一条查询回解(d08790f,#219);结构写有确认屏(b870e00,#218)。 - 差距:写工具(AG8.3–8.5)未实现;provider 侧还没有工具调用解析,所以
executeToolCall目前没有模型入口;批量/计划级工具与撤销语义未定。 - 验收标准:LLM 永不直接访问 store;每个 tool 有 typed input/output、权限、idempotency、precondition;safe reads 可自动执行,reversible writes 明示反馈,structural writes 必须逐次确认;确认绑定精确 proposal hash/版本且过期失效;执行产生 domain event 和 audit;未知/畸形/越权 tool call 被拒绝。
- 依赖:AG9 structured output;现有 engine/IPC;AG10 tool safety harness。
- 风险:prompt injection 越权;确认后状态已变化(TOCTOU);重试导致重复写;把 IPC 方法直接暴露为模型工具造成攻击面过大。
- 实施步骤:Tool ADR/权限矩阵 → read-only registry → proposal envelope → confirmation UI → reversible commands → structural commands → audit log → adversarial tests。
- 当前证据:
AgentRuntime(llm-provider/src/runtime.ts)——请求/信号拆分 #111、取消与总截止 #142→#147、预算 #143→#156、流式 #144→#161、重试与可配置回退 #145→#162、provider 一致性与 provider-failure 场景dc6b0de(#165);conformance 证据docs/ag9-conformance.md,ADR ADR 0002;Tutor 的结构化 reader 已随 #101 合并。 - 差距(已闭合):structured output 在
executeStructured/executeStructuredViaStream于边界校验;streaming、abort、retry/backoff、预算、fallback 链均已合并。尚无 skill 调用结构化门——conformance 文档如实记为 outstanding,是 AG8 工具调用要进的门。 - 验收标准:统一 runtime 请求支持 schema、timeout、abort、stream events、retry policy、provider chain、预算;一次请求可追踪 provider/model/耗时/重试/降级但不记录敏感 prompt;超时或断网在 UX 时限内转 rule fallback;abort 后不得提交迟到结果;结构化结果在边界验证。
- 依赖:shared provider contracts;AG10 runtime conformance tests。
- 风险:多 provider 行为不一致;streaming 与 schema 校验冲突;重试放大成本;本地模型能力不足导致隐藏降级。
- 实施步骤:ADR 分离 Provider 与 AgentRuntime → runtime contract → abort/timeout → structured adapter → retry/backoff → provider chain → token estimator/budget → optional adapters → conformance suite。
- 当前证据:本次静态审查时(2026-09-21,含当时可见的功能分支)共 703 项 Vitest 测试;state/policy/continuity/persistence/engine/IPC 测试较完善,并有 Electron + Playwright golden path;Tutor 有格式、模式、引用、grounding、预算 guardrail;隐私边界已有文档和若干测试。
-
测试数量的警告:本页的 703、实施进度页的 737/764 互相不一致,而且都无法从
main复现 (大数字来自分支)。测试条数只能证明“跑过”,不能作为证据。可复现的证据是main上必需检查的结果:quality×3 OS、golden path×2(17 个测试)、coverage、package (smoke)、CodeQL、analyze。 - 差距:版本化 scenario dataset、统一 evaluator 与 expected/allowed/forbidden 断言已在
main(39 个场景,含 #212 的 tool safety 九场景);仍缺真实模型抽样评测、质量趋势报告,以及跨语言、干扰度与 resume quality 套件。 - 验收标准:每个 AG 至少有 happy/edge/adversarial 场景;deterministic gates 100% 稳定;LLM eval 固定模型/参数并报告通过率与方差;发布门槛含 grounding、tool correctness、privacy zero-tolerance、concision、continuity;场景不得含真实用户数据;失败能定位到 capability/runtime/provider。
- 依赖:应横切全阶段,不能等功能全部完成。
- 风险:用字符串匹配冒充质量;eval 数据泄漏进 prompt;在线模型漂移导致 CI 抖动;只测英文。
- 实施步骤:定义 JSON scenario schema/runner → 迁移现有 fixtures → 先建 AG1/2/3/5 deterministic suite → tool safety suite → 中英 model eval(非阻塞起步)→ 基线报告 → 逐步设 release gate。
- 建 Capability Matrix、Data Inventory、术语表。
- 写 4 个 ADR:Memory scopes、AdaptiveTask 身份/生命周期、Tool permission/confirmation、AgentRuntime。
- 建 AG10 scenario schema 与最小 runner,不接真实模型也可开始。
可 fan-out:四个 ADR 可并行起草;Data Inventory 与 scenario schema 可并行。不可拆散:术语表与 shared-types 命名最终由单一 owner 收口,避免 CognitiveCheckpoint/LearningCheckpoint、temporary step/adaptive task 双词漂移。
- AG1 字段 allowlist、敏感 payload 回归。
- AG2 outcome 成功窗口与六类 E2E。
- AG3 中英场景、section anchor、transcript 生命周期。
- AG5 gap-band 与 resume success(先不依赖 adaptive restore)。
- 每一项同步进入 scenario dataset。
可 fan-out:AG1 privacy fixtures、AG2 outcome evaluator、AG3 bilingual eval、AG5 gap policy 是四个互不改同一业务核心的工作包。集成点集中在 shared-types/engine 时必须串行合并;E2E 文件由单 owner 维护,避免并发改同一 golden path。
- 先落 AgentRuntime 最小合同(structured + timeout + abort + fallback)。
- 再落 read-only tools 和 registry。
- 再落 proposal/confirmation envelope、权限与 audit。
- 最后才开放 reversible/structural write。
可 fan-out:runtime conformance tests、read tool definitions、confirmation UI 原型、adversarial scenarios 可并行;但“写工具启用”必须等待 runtime validator、permission checks、confirmation binding 三项全部 green。
- AdaptiveTask schema/migration。
- SHRINK/SPLIT/CHANGE_MODALITY 纯 proposal builder。
- confirmation→command→event→persistence。
- adaptive practice、reorder proposal。
- 与 AG5 restore 集成。
可 fan-out:三种 adaptation strategy 可在共同 schema 冻结后并行;migration/repository 与 UI diff 可并行。不可并行落地:plan ordering/progress invariants 需由同一集成 owner 负责。
前置:ADR 0001 — Agent memory deletion 已接受(#110), 删除语义按该 ADR 执行;AG7 实现不得另行发明清除规则。
- 有界 episodic queries 与 retention/delete(物理删除,见 ADR 0001)。
- preference store 仅建基础 CRUD,不启用自动推断。
- checkpoint 纳入有界 Tutor/Rescue evidence。
- adaptive state restore、long-gap refresher。
可 fan-out:memory repository、inspection/delete UI、checkpoint evidence summarizer、resume eval 可并行;删除语义需做一次跨库/缓存集成审计。
按 task-size → intervention → explanation → weekly reflection 的顺序逐个开放。每一类都经过“统计建议 → 展示证据 → 用户确认 → 存储 → 可撤销”,不要一次上线全画像。
可 fan-out:各 preference 的离线统计研究可以并行;写入模型、文案伦理审查和产品确认流必须统一。
Contracts + Eval Harness
→ AgentRuntime structured/abort
→ Tool registry + permission + confirmation
→ AdaptiveTask persistence/actions
→ Adaptive resume
→ Memory preference
→ Reflection
AG1/2/3/基础 AG5 的收口不必等关键路径,可并行交付并尽快形成更可信 Demo。
建议第一批只交付 6 份,先建立决策护栏再写实现 issue。2026-10-09 进展:第 1、2、4 项已交付;第 3、5、6 项仍未开始。
-
✅ 已由docs/wiki/index.md:Wiki 导航、owner、状态定义、事实更新时间。docs/wiki/README.md(导航 + 事实基线 + 七级状态定义)承担。 -
✅ 已由docs/wiki/agent-capability-matrix.md:把本文第 2 节拆成唯一能力台账,链接实现与测试。docs/wiki/project-features.md承担(逐功能九点台账;本文第 2 节降级为方案描述)。 -
docs/wiki/adr/0001-agent-memory-scopes.md:三层 memory、保留/删除/禁止数据。 -
✅ 已由docs/wiki/adr/0002-agent-tool-permissions.md:权限、proposal hash、确认、幂等、audit。docs/wiki/adr/0003-tool-permission-matrix.md承担(三个权限级别 + 十四个工具的矩阵)。 -
docs/wiki/adr/0003-adaptive-task-lifecycle.md:临时步骤与持久任务、position/progress/resume 语义。 -
docs/wiki/evaluation-scenarios.md:scenario schema、指标、release gates;先录入 AG1/2/3/5 的 20–30 个固定场景。
第二批再交付 agent-runtime-contract.md、privacy-data-inventory.md、resume-quality-metrics.md 和按 AG 拆分的页面。避免先建 10 份空壳能力页。
如果下一轮只安排一个可交付切片,选择:“Resume 三档 + success metric,但不引入新 LLM 能力”。它复用现有 checkpoint/resume 强项、风险低、可 deterministic 测试,且直接增强最有辨识度的 Demo。并行补 AG10 scenario harness 与 AG1 privacy fixtures。
进入 AG4 前的硬门槛:AG8 的 structural-write confirmation 与 idempotency 测试已通过 (已满足:确认信封 + 幂等 + 审计 + 四条 DoD 测试,见 #114)。进入 AG6 前的硬门槛:AG7 的 preference inspection/delete 已交付。