# LocalWeekend

**Repository Path**: SapientialM/local-weekend

## Basic Information

- **Project Name**: LocalWeekend
- **Description**: LocalWeekend · 周末搭子

懂你的周末管家 —— 基于世界模型简化沙盒 + 用户画像的本地闲时活动规划 Agent。周末搭子不只是一次性的出行搜索工具，而是一个持续学习你的偏好、主动为你推荐、越用越懂你的本地生活 Agent。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-11
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LocalWeekend · 周末搭子

> **懂你的周末管家** —— 基于世界模型简化沙盒 + 用户画像的本地闲时活动规划 Agent
>
> 美团 AI Hackathon 2026 · 赛题 06（本地探索） · 交付日期 2026-06-06（CLI 主交付）/ 2026-06-08（CLI 优先 / WebUI 测试中重构）

周末搭子不只是一次性的出行搜索工具，而是一个**持续学习你的偏好、主动为你推荐、越用越懂你**的本地生活 Agent。给一句自然语言需求（"周六下午带孩子和老婆出去"），Agent 在几分钟内完成方案规划、信息核实、偏好学习、预订执行的全流程。

> **提交文档**：[docs/submission.md](docs/submission.md) — 评审请从这里开始。
>
> **主交付**：可执行 jar `target/jacecli-1.0-SNAPSHOT.jar`（CLI 流式交互，**本轮主形态**）；Web 端（`/` → `/chat` Vue 卡片流、`/cli` Xterm.js 虚拟终端）作为同源补充形态，**仍标"测试中"**——CLI jar 已是完整交付。
>
> **本项目基础**：基于 JaceCLI 主线（v12.0.0）构建。所有能力均跑在单个可执行 jar 上。

---

## ✨ 核心能力

| 能力 | 说明 | 验证文档 |
|------|------|---------|
| 🗣️ 一句自然语言输入 | ReAct 流式推理 + Plan-and-Execute | [smoke-test.md](docs/smoke-test.md) §2 |
| 🏖️ 4-6 小时综合方案 | 活动 + 餐厅 + 时间线（含交通） | smoke-test.md §2 |
| 👨‍👩‍👧 4 场景端到端 | 家庭 / 朋友 / 情侣 / Solo | smoke-test.md §2 |
| 🎁 蛋糕鲜花送到餐厅 | `extras` 字段 | smoke-test.md §1 M6 |
| 📅 接受 → 自动记录 → 反馈画像 | 隐私优先 | smoke-test.md §4.5 |
| ⚡ 主动推荐 | 8-10ms（远低于 5s 预算） | smoke-test.md §4.5 |
| 🛡️ 异常自动降级 | 无座/无票/冲突 | smoke-test.md §4.6 |
| 🚦 Token 限流 | 默认 5000 万 token/小时，超限 HTTP 429 + Retry-After | [architecture.md](docs/architecture.md) §3 |
| 📊 实时余量面板 | Web 右侧进度环 + 重置倒计时（30s 自动刷新） | — |
| 💻 Web CLI 虚拟终端 | Xterm.js + SSE/POST，**两套入口同一套内核** | [AGENTS.md](AGENTS.md) 决定 11 |
| 🔒 工具/命令双层黑名单 | CLI 模式禁用 3 个危险工具 + 拦截 23 个危险 slash command | [architecture.md](docs/architecture.md) §3 |
| 📱 响应式 LandingView | 4 档断点（< 480 / ≥ 480 / ≥ 768 / ≥ 1024），mobile 一屏可见 | [AGENTS.md](AGENTS.md) 决定 12 |

---

## 🚀 5 步启动（15 分钟内可跑通）

### 第 1 步：环境准备

- Java 17+（本仓库用 Java 23 验证）
- Maven 3.9+
- DeepSeek / GLM API Key（其他兼容 OpenAI 的 LLM 也可）

```bash
# 克隆 & 进入
cd /path/to/localweekend
```

### 第 2 步：配置 API Key

```bash
cp .env.example .env
# 编辑 .env，填入 DEEPSEEK_API_KEY=sk-...
```

`.env` 关键配置（其余项可保持默认）：

```bash
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-your-key-here
DEEPSEEK_MODEL=deepseek-v4-flash   # 默认 flash 模型，响应更快
```

### 第 3 步：准备沙盒数据（成都 500 餐厅 / 200 活动）

```bash
mkdir -p ~/.jacecli/sandbox
cp origin-mock-data/chengdu/restaurants.json ~/.jacecli/sandbox/
cp origin-mock-data/chengdu/activities.json ~/.jacecli/sandbox/
```

### 第 4 步：编译

```bash
mvn clean package -DskipTests
# 产物：target/jacecli-1.0-SNAPSHOT.jar
```

### 第 5 步：启动

```bash
java -jar target/jacecli-1.0-SNAPSHOT.jar
```

看到下面的 Banner 就说明启动成功：

```
╔══════════════════════════════════════════════════════════╗
║                                                          ║
║  🎯  LocalWeekend · 周末搭子                              ║
║      美团 AI Hackathon 2026 · 赛题06 本地探索              ║
║      你的智能周末闲时活动规划 AI 助手                       ║
║                                                          ║
║  💡 直接说出你的需求，例如：                                ║
║     「周末想吃火锅」「带孩子去博物馆」                       ║
║     输入 /help 查看可用命令                                ║
║                                                          ║
╚══════════════════════════════════════════════════════════╝

✅ Model loaded: deepseek-v4-flash (deepseek)
🏖️  Sandbox mode: embedded
🌐 Web API: http://localhost:8080
```

直接打字就开始，比如：

```
下午带孩子和老婆出去，孩子5岁，老婆在减肥。帮我规划4-6小时。
```

---

## 📺 演示流程（10 分钟）

完整的演示脚本见 [**docs/demo-script.md**](docs/demo-script.md)，6 个用例覆盖：

1. 家庭场景（CLI 主路径，2 min）
2. 反馈闭环（接受 + /history + /recommend，2 min）
3. 异常处理（无座自动替代，1 min）
4. 主动推荐（/recommend + /surprise，1 min）
5. 分享 + 日历（/share + /calendar，1 min）
6. **Web CLI 虚拟终端**（Xterm.js 敲命令 / 体验工具黑名单 / 翻看 /help，1 min）

**两套入口，同一套内核**：首页有两个 CTA — "WebUI 试用 →" 跳 /chat 走 SSE 卡片流，"💻 CLI 终端" 跳 /cli 走 Xterm.js + 同源 ReAct，输出都来自 `reactAgent` 同一份 LLM/工具/Memory。

---

## 🛠️ 技术栈

- **后端**：Java 17 + Maven + Gson/OkHttp/Logback/JLine
- **LLM**：DeepSeek-v4-flash（默认）/ GLM-5.1 / Kimi / 任何 OpenAI 兼容 API
- **沙盒**：Java 内存嵌入式（500 餐厅 / 200 活动的成都本地数据）
- **Web API**：JDK 内置 HttpServer（端口 8088，**27 个 REST/SSE 端点**，含 3 个 CLI 端点）
- **Web 前端**（可选）：Vue 3 + Vite + SSE 事件流 + Xterm.js（CLI 视图）

**基础**：本分支基于 JaceCLI 主线（v12.0.0）构建，继承了 12 期核心能力（ReAct / Plan-and-Execute / Memory / RAG / Multi-Agent / HITL / 长上下文工程 / MCP）。详见 [AGENTS.md](AGENTS.md)。

---

## 📁 项目结构

```
localweekend/
├── README.md                              ← 本文件
├── AGENTS.md                              ← 协作规则 + 主线能力快照 + 2026-06-08 修复记录
├── ROADMAP-proj-localweekend.md           ← 本次交付的迭代路径
├── CLAUDE.md                              ← legacy 入口
├── DEBT.md                                ← 已知小问题记录
├── LICENSE
│
├── docs/                                  ← 全部交付文档（10 个）
│   ├── submission.md                      ← ★ 官方提交包封面 + 全量索引
│   ├── mission.md                         ← 赛题原始交付定义
│   ├── design.md                          ← ≤2 页设计（+ Web API 契约附录）
│   ├── architecture.md                    ← ★ 技术架构（模块 / 数据流 / 关键设计）
│   ├── smoke-test.md                      ← ★ 4 场景端到端 + 11 异常 + 性能实测
│   ├── test-report.md                     ← ★ 测试报告（566 cases + 已知边界）
│   ├── demo-script.md                     ← ★ 10 分钟演示脚本
│   ├── cli-commands.md                    ← CLI 命令清单 + 状态
│   └── DEPLOY.md                          ← 部署手册
│
├── origin-mock-data/
│   └── chengdu/                           ← 500 餐厅 + 200 活动（成都数据 seed）
│
├── frontend/                              ← Vue 3 前端（Web API 已通）
├── src/main/java/com/jacecli/             ← Java 源码
│   ├── cli/                               ← Main 入口
│   ├── localweekend/                      ← ★ 本分支的场景层
│   │   ├── sandbox/  tool/  planner/  profile/  recommend/
│   │   ├── history/  prompt/  ui/  output/  data/
│   │   └── share/  demo/  reviewer/      （空目录：算法未实装的占位符）
│   └── agent/  llm/  memory/  rag/  mcp/  hitl/  policy/  web/  tool/  util/
├── src/test/java/                         ← 566 个单元测试（566/566 全绿）
│
├── pom.xml
├── .env.example
└── target/jacecli-1.0-SNAPSHOT.jar        ← 主交付：可执行 jar（27 MB shaded）
```

---

## 🛠️ CLI 命令（常用）

### 终端 CLI（本地 jar 跑）

| 命令 | 用途 | 状态 |
|------|------|------|
| `/help` | 列出可用命令 | ✅ |
| `/sandbox` | 查看沙盒状态（500 餐厅 / 200 活动） | ✅ |
| `/model` | 切换 LLM（glm / deepseek） | ✅ |
| `/hitl on` | 开启危险操作人工审批 | ✅ |
| `/history` | 查看接受过的方案 | ✅ |
| `/calendar` | 终端 emoji 月历 | ✅ |
| `/recommend` | 主动推荐（8-10ms） | ✅ |
| `/share` | 生成分享文案（微信可发） | ✅ |
| `/clear` | 清空当前会话 | ✅ |
| `/exit` | 退出 | ✅ |

### Web 虚拟 CLI（Xterm.js，Web 端 `/cli` 路由）

Web 端 CLI 模式有**双层安全护栏**：

- **工具黑名单（硬禁用，物理卸载）**：`write_file` / `execute_command` / `create_project` 通过 `-Djacecli.tools.disabled=...` 物理卸载，LLM 看不到；执行时直接抛"未知工具"
- **命令双层过滤**：
  - 白名单（直接放行）：`/help /calendar /history /memory /clear /exit /sandbox /whoami`
  - 别名（看起来命令丰富，实际转自然语言 ReAct）：`/match /recommend /profile /location /theme /prompts`
  - 黑名单（直接拒）：`/bash /exec /write /mcp /plan /team /hitl /policy /audit /session /index /search /compress /fork /cancel /context` + 任何 `!` shell escape + 未知 `/xxx`

会话管理：前端 sessionStorage 持久化 sessionId（最多 10 分钟 idle 自动清理），最多 20 个并发 session（防 OOM）。Header 展示 "会话: N/20"（绿/橙/红三色阈值）。

完整命令清单（11+ 个，含 `/match` `/surprise` 等命令入口存在但算法未实装）：见 [**docs/cli-commands.md**](docs/cli-commands.md)。

---

## ⚠️ 已知边界（透明披露）

详见 [**docs/smoke-test.md**](docs/smoke-test.md) §5 / §6。摘要：

1. **方案生成 30s 预算超出**（实测 42-87s）— LLM 在 500/200 大数据集上过度推理。**预热后会快**。
2. **`plans` SSE 事件跨场景同 top combo** — 后端 backstop 重组是 generic，**LLM 的 answer 文本是个性化的**。
3. **一键安排走 HITL 协同** — 用户 `y` 确认后批量放行同类（`a` 键），不是字面"一键"。**为安全设计**。
4. **包名 `com.jacecli` 暂未改名** — 用户感知层已全部是 LocalWeekend 品牌；jar 名同。详见 [AGENTS.md](AGENTS.md) 2026-06-06 收尾决定段。
5. **Web CLI 边界**：Xterm.js 不支持真实 readline（方向键历史 / Tab 补全 / Ctrl+C 中断 LLM 调用留给后续），命令黑名单是字符串集合不防 `!!rm` / `echo /bash` 变形。
6. **`/match` `/surprise` `/demo generate` 是命令入口** — 算法层（多算法推荐 / 惊喜注入 / Demo 数据生成器）未实装，见 [ROADMAP-proj-localweekend.md](ROADMAP-proj-localweekend.md) §3 明确放弃。

---

## 📚 文档索引

| 入口 | 看什么 |
|------|------|
| **提交** | **[docs/submission.md](docs/submission.md)** ★★★ 评审起点（全量索引 + 主交付说明） |
| **从这里开始** | 本文件 |
| [AGENTS.md](AGENTS.md) | 协作规则 + 主线能力 + 2026-06-06 收尾决定 + 2026-06-08 修复记录 |
| [ROADMAP-proj-localweekend.md](ROADMAP-proj-localweekend.md) | 本次交付的 7 个迭代（4 P0 + 2 P1 + 1 P2） |
| [docs/mission.md](docs/mission.md) | 赛题原始交付定义 |
| [docs/design.md](docs/design.md) | ≤2 页设计 + Web API 契约附录（24 端点） |
| [docs/architecture.md](docs/architecture.md) | ★ **技术架构**（模块 / 数据流 / 关键设计） |
| [docs/test-report.md](docs/test-report.md) | ★ **测试报告**（566 cases + 4 场景冒烟 + 已知边界） |
| [docs/smoke-test.md](docs/smoke-test.md) | ★ 4 场景端到端冒烟 + 性能实测 |
| [docs/demo-script.md](docs/demo-script.md) | ★ 10 分钟演示脚本 |
| [docs/cli-commands.md](docs/cli-commands.md) | CLI 命令清单 + 状态 |

---

## 🧪 验证清单

```text
□ mvn test                                          → 566 tests 全绿（537 基线 + 19 CLI 新增）
□ mvn clean package -DskipTests                     → 27 MB shaded jar
□ java -jar ...jar                                  → Banner 是 LocalWeekend
□ 复制成都数据到 ~/.jacecli/sandbox/                → 500/200 数据加载
□ /api/health 返回 restaurantCount:500              → 数据正确
□ /api/recommend 耗时 < 1s                          → 推荐引擎性能
□ /api/chat 4 场景端到端                            → 家庭/朋友/情侣/Solo
□ /api/cli/stream 推送 event:session + 欢迎横幅   → Web CLI 虚拟终端
□ /api/cli/exec 4 个本地命令 4 个 answer（不重复）  → 流式折叠正确
□ /api/cli/stats → {active:N, max:20, idleMinutes:10} → 会话占用统计
□ /api/cli/exec 4 个黑名单命令 → 4 个 error        → 工具/命令黑名单
□ LandingView 4 档断点（mobile/tablet/desktop）     → 响应式
□ docs/architecture.md 反映最终架构                 → 技术架构清晰
□ docs/test-report.md（566 cases + 4 场景 + 边界）  → 测试透明披露
□ docs/demo-script.md 10 分钟可跑                   → 演示流程完整
□ 提交包 unzip + java -jar ≤ 5 分钟可启动           → 即开即用
```

---

## 📄 License

Apache 2.0 © 2026 SapientialM