NowHow · 上手

现在要用，现在学会。

NowHow 是一个开源的即时互动学习 Agent。用户带着眼前不会完成的真实任务进入学习项目，Sage Agent 通过短对话、视觉材料与互动练习，带用户从“不会”走到能够独立完成。

它不是课程平台，也不会替用户完成任务。核心闭环是：

明确目标 → 快速诊断 → 展示与解释 → 用户动手 → 现场反馈 → 变式验证

产品界面

• 左侧：学习项目，隔离不同主题的对话、材料和互动状态。
• 中间：Sage Agent 对话，负责理解目标、解释、提问与反馈。
• 右侧：互动学习场，把讲解、图片、对比、代码与多种互动融合在同一学习表面；任一部分都能直接追问 Agent。

界面复用 Yiii 的 Flutter 桌面壳与 Liquid Glass 体系，支持 macOS、Windows、Linux，以及浅色和深色模式。Sage 通过 sidecar/MCP 边界接入，本仓库不修改 Sage 源码。

当前能力

• 新建、重命名、切换和删除学习项目。
• 每个项目拥有独立 Sage 会话与上传材料。
• 一个面向用户的 Sage Single Agent，不提供模式切换。
• 设置只提供 Agent、图片生成、搜索三类模型，以及 Sage 路径、语言与外观。
• Agent 通过专用工具生成并更新 Learning Studio 内持久化的 *.learning.yaml Item。
• 用户在互动学习场的操作会以结构化事件回传给 Sage。
• 内置任务优先的学习教练 Prompt 和唯一的互动学习 Skill；不提供个性化 Skills。
• 底层保留 Project/Item/Run 机制，支持可靠的材料登记与历史状态。

完整产品定义见 docs/product-plan.zh-CN.md，互动活动协议见 activity-schema.md。

快速开始

依赖

• Flutter（与 pubspec.yaml 中 Dart SDK 约束兼容）
• Python 3.11+
• 本地 Sage 仓库或可用 Sage 服务

默认会查找同级目录 ../Sage。也可以在 NowHow 设置中指定 Sage 路径和 Python，或使用环境变量：

export SAGE_RUNTIME_PATH="$PWD/../Sage"
export SAGE_PYTHON="$SAGE_RUNTIME_PATH/.venv/bin/python"

启动桌面应用

flutter pub get
flutter run -d macos

Windows 或 Linux 请把设备名替换为对应桌面平台。

验证

flutter analyze
flutter test
PYTHONPATH=python python3 -m pytest python/tests

创建 Learning Studio

NowHow Agent 调用 nowhow_learning_studio_update，由工具写入、登记并刷新学习内容：

item_id: first-check
title: 排出第一轮检查顺序
paths:
  - materials/site-photo.png
  - materials/first-check.md

调用方只传文件路径，不传 sections、Item URI 或物理 Run 参数。工具会把每个文件自动登记为 Project Item、按内容变化复制不可变版本，再生成供 Studio 显示的索引。图片与文本直接显示，其他文件以可打开的文件卡呈现。右侧只有一个 Learning Studio，并自动打开其中最近更新的学习 Item。

数据与配置

• 软件设置：~/.nowhow/settings/app-settings.yaml
• Agent 工作区：~/.nowhow/agents/nowhow/
• 学习项目：~/.nowhow/agents/nowhow/projects/<project-id>/
• Sage 会话映射：~/.nowhow/settings/project-sessions.yaml

API Key 保存在本机软件设置中。不要把真实密钥提交到仓库。

架构

Flutter desktop UI
  ├─ Learning Projects
  ├─ Sage conversation
  └─ Learning Studio
       └─ learning Items (*.learning.yaml)
           │ interaction event
           ▼
Python sidecar / MCP boundary
           │
           ▼
Sage Agent + NowHow learning skill

底层只保留 Learning Studio 需要的 Project/Item/Run 存储兼容和对话媒体预览；旧 Yiii Canvas 与 Timeline UI 不再随应用编译。

参与贡献

欢迎贡献新的互动组件、职业学习场景、教学方法、可访问性改进和 Sage 适配。请先阅读 CONTRIBUTING.md。

License

Apache License 2.0，见 LICENSE。