LocalWeb

CLI agent 的本地 Web 可视化与上下文交互层

本地 HTML 伴生界面，为 CLI agent 提供可视化投影层。CLI 保持主控制面、权限面和会话上下文，Web 提供高带宽可视化输出和可选的上下文交互。

✨ 特性

• 🎨 富文本 HTML 面板 - 代码解释、图表、学习材料
• 🔄 上下文交互 - 可选方向建议、标注、筛选、排序或小表单返回 CLI
• 📁 文件协议解耦 - 独立、可审计、项目级
• 🔒 默认安全 - localhost 绑定、无自动执行
• 🧹 自动维护 - choice ID 重用安全、inbox 可清理
• 🧭 Session 隔离 - 多开端口时可用 --session 隔离 state/events/inbox

🚀 快速开始

# 初始化项目
uv run scripts/localweb.py init

# 启动服务
uv run scripts/localweb.py serve --port 8765

# 在浏览器打开 http://127.0.0.1:8765

多开端口或并行任务时，为每条 CLI 工作流指定 session：

uv run scripts/localweb.py init --session review-auth
uv run scripts/localweb.py serve --session review-auth --port 8765
uv run scripts/localweb.py choice --session review-auth --id next --option risks="看风险点"
uv run scripts/localweb.py wait --session review-auth --id next

📖 使用场景

• 教学复杂概念 - 可视化图解 + 可选学习路径
• 代码审查 - 带注解的 diff + 点击关注风险点
• 交互式调试 - 可视化状态 + 标记卡住步骤
• 多步骤规划 - 可视化上下文 + 进度追踪
• 需求澄清 - 用卡片、滑块或表单收集难以在 CLI 中表达的约束

📋 核心命令

命令	用途
init	初始化 .localweb 目录结构；--shell-only 只刷新浏览器 shell
serve	启动 HTTP 服务器
panel	注册 HTML panel
learn	从结构化 lesson JSON 生成学习面板（概念卡/结构图/问答）
code	渲染代码展示与讲解面板（纯展示，不编译不执行）
game-study	自适应学习面板（逐题+错题本+间隔重复复习）
quant	渲染因子回测仪表盘
ml	渲染 ML 数据可视化面板
status	更新状态和上下文
choice	发布可选的建议型选择或上下文输入
wait	显式等待 Web 输入返回 CLI，可启用 CLI 文字兜底
clean	清理已消费和已作废事件
doctor	环境检查
emit	追加自定义事件

所有命令都支持 --project <path>；涉及状态、输入或服务的命令还支持 --session <id>。默认 session 是 cli-main，兼容旧的 .localweb/state.json、.localweb/events.jsonl 和 .localweb/inbox/events.jsonl 路径；非默认 session 写入 .localweb/sessions/<id>/。

📂 项目结构

localweb/
├── SKILL.md            # Skill 主文档
├── scripts/
│   └── localweb.py     # CLI 工具
├── assets/
│   └── shell/          # Web UI 模板
├── references/         # 协议和模式文档
├── code/               # 代码展示与讲解面板
├── learn/              # 结构化学习面板
├── game-study/         # 自适应学习系统面板
├── quant/              # 因子回测仪表盘
├── ml/                 # ML 可视化面板
├── agents/             # Agent 配置
├── pyproject.toml      # 依赖声明（FastAPI + uvicorn）
├── design.md           # 设计文档
└── README.md

🔧 工作流程示例

# 1. 生成可视化 panel
uv run scripts/localweb.py panel --id main --file explanation.html

# 或生成学习模式 panel；有 questions 时默认等待浏览器回答
uv run scripts/localweb.py learn --file learn/examples/epsilon-delta.json --id epsilon-delta
uv run scripts/localweb.py wait --id learn-epsilon-delta --type panel

# 2. 更新状态和上下文
uv run scripts/localweb.py status \
  --state learning \
  --context "任务=理解 React Fiber" \
  --context "阶段=核心概念"

# 3. 需要用户方向时，提供可选上下文输入；纯展示时可省略
uv run scripts/localweb.py choice --id next \
  --option overview="看整体流程" \
  --option source_path="看源码路径" \
  --option exercise="做练习"

# 4. 发布可回传输入后必须立刻 wait，保持 CLI 回合打开
uv run scripts/localweb.py wait --id next
# 输出: source_path

# panel 内嵌交互显式发送 Markdown 时，发布 panel 时声明 wait id
uv run scripts/localweb.py panel --id review --file review.html --wait-id review-context --wait-type panel
uv run scripts/localweb.py wait --id review-context --type panel
# 输出: ## 用户补充 ...

# 如果用户不想点选，也允许在交互式 CLI 中直接输入文字
uv run scripts/localweb.py wait --id next --cli-fallback

💡 核心理念

• CLI 为主上下文 - 终端是唯一的会话和权限控制面
• Web 为投影层 - 浏览器做可视化和低风险上下文输入，不处理权限
• 文件协议解耦 - CLI/Server/Browser 通过文件通信
• 显式控制流 - 发布可回传 Web 输入后，命令输出 next_command 指向对应 wait
• Session 为身份边界 - 端口只是服务入口；多开时用 session 隔离上下文和 inbox

📚 文档

• SKILL.md - 完整使用指南
• design.md - 设计文档和架构
• references/protocol.md - 文件协议规范
• references/html-patterns.md - Panel 模式
• references/visual-style.md - 视觉风格指南

🛠️ 依赖

• Python 3.10+
• FastAPI
• uvicorn

# 使用 uv (推荐)
uv run scripts/localweb.py serve

# 或手动安装依赖
pip install fastapi uvicorn
python scripts/localweb.py serve

📝 License

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！