# miao-desk

**Repository Path**: ling1314/miao-desk

## Basic Information

- **Project Name**: miao-desk
- **Description**: miao-desk
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-11-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# miao-desk

桌面客户端程序：参考dsh界面 + 系统托盘 + 大肥鱼桌宠，三合一。

基于 **Wails v3**（Go + WebView2），桌宠素材来自开源项目
[dsh-chatting-pet](https://www.npmjs.com/package/dsh-chatting-pet)（MIT 许可），
即 DeepSeek Harness 的蓝发女仆鲸鱼"大肥鱼"。

## 三大能力

| 能力 | 说明 |
|---|---|
| 主界面 | 元宝式布局：左侧会话栏 + 消息流 + 底部输入区，流式渲染、工具调用卡片、授权确认卡片 |
| 托盘 | 常驻入口：显隐主窗口/桌宠、状态展示、退出 |
| 桌宠 | 透明置顶鲸鱼：空闲随机动作、拖拽抛掷物理、气泡文案、工作状态六档联动 |

## 当前状态

P0 技术验证 ✅（2026-10-30）：wails v3 透明窗 + webm alpha + 动态穿透 + 托盘全部走通，
结论与避坑指南见 [docs/design.md](docs/design.md) §9.1。验证 demo：`cmd/p0/`。

P1 桌宠完整体 ✅（2026-10-31 收口，[docs/design-p1.md](docs/design-p1.md)）：
**M1 骨架** ✅：随机链 + 穿透 + 托盘 + 点击回应 + 六档联动（StatusSource 接口 + Mock 源）。
**M2 物理** ✅（当日对齐 dsh-whale-pet 重写为惯性模型）：硬跟手（GetCursorPos 轮询，禁 WebView 坐标）、惯性滑行、边界反弹、撞击 Q 弹、弹弓。
**M3 移动转身** ✅：随机链移动动画伴随真实窗口位移（多屏并集校验）、跨屏漫游。
**M4 气泡事件** ✅：气泡优先级/驻留语义完整、终态 10s 收起、碎碎念通道。

P2 主界面 ✅（2026-11-01 全部里程碑收口，[docs/design-p2.md](docs/design-p2.md)）：
**M1 外壳** ✅：三段式布局（顶部操作栏+宽侧栏+内容区整体切换）+ 侧栏折叠 +
历史会话抽屉 + 六档状态联动 + 关窗到托盘。技术栈 React 19 + Vite + Tailwind v4 + zustand
（[前端导读](docs/design-p2-frontend.md)）。DPI/WebView2 表层溢出避坑见 design-p2.md §6。
**M2 消息流** ✅：AI SDK 子集协议（[spec](docs/design-p2-chat.md)）+ MockBackend 剧本 +
呈现节奏（三档发布+3×rAF）+ 回合级过程折叠（实时标题）+ 工具行/授权卡 +
桌宠六档联动（含 2.5s 最小驻留调速器）。
**M4 会话** ✅：内存态多会话（新建/切换/DSH fork 分支）。
**学习文档**：[聊天功能手册](docs/guide-chat.md)（每功能的效果/用法/设计意图）。
**P3 本地 Agent · Phase 0-3 ✅（2026-11-01，[docs/design-p3.md](docs/design-p3.md)）**：
Go 进程内嵌 ReAct loop：四级权限 + 三档信任 + 工作区模型。
已落地：单根配置（config.yaml + .env 随 exe，desk.yaml 已并入）、`authz`/`llm`/`tool`/`agent`
四包（表格驱动权限测试 + httptest LLM 测试 + Fake 端到端）、BackendClient 本地实现
（未启用自动回退 MockBackend）、`go run ./cmd/agent-smoke -fake` 冒烟。
**Phase 4 首批 ✅**：授权卡（拒绝/同意 + 本地化标题 + 高危红色 + 应答撤卡）、输入框
三档选择器（SetTier 真值）、suspend 继续/停止卡、logrus（logLevel 配置 + logs/ 文件）、
miao-home F5 调试目录；实机反馈修复桌面路径幻觉/输出质量/schema 校验等。
**Phase 5-6 ✅（修订 10）**：skills 加载（CLI 型 + 知识型渐进披露 + load_skill 工具）、
MCP client（stdio，mcp/<name>.yaml 注册表，dangling 跳过）、记忆持久化（messages.db，
重启历史可续聊）、fork 快照复制、会话三绑定（SendToSession/LoadSessions/LoadMessages）。
**实机修复链 ✅（修订 8-13）**：授权闭环/卡片本地化、输出质量、execute_command、
steer 待定区、事件乱序（单发射器）、fork 含目标回复、**重启恢复上次会话**
（meta kv + hydrate 门控 + **wailsReady 桥时序**——启动早期绑定调用的根治）。
**打磨批 ✅（修订 14）**：上下文统计真值、出厂 skill miao-manual、反馈本地落库
（synced=0 待服务端同步）、blocked 提示条。
**DSH 式统计面板 ✅（修订 15）**：模型/工具用时、TTFT、TPS、缓存命中率
（DeepSeek 字段）、上下文构成（首轮实测校准 + 估算拆分）、步数 N/M 显示
（config maxIterations）。
待办：~~上下文压缩~~ ✅（修订 16）、~~MCP http transport~~ ✅（修订 17）、
~~附件/图片输入~~ ✅、~~retry 事件~~ ✅、~~OpenAI 风格缓存字段解析~~ ✅（修订 18 一并落地）。
**修订 18 ✅（2026-11-02）**：缓存字段三态解析（DeepSeek/OpenAI/Anthropic 求和）+ retry 事件
（SetRetryHook 回调透传，前端琥珀色"正在自动重试"提示条，宠物保持思考档）+ 附件/图片输入
（📎 图片压 1568px、文本文件内联、DB v5 attachments 列、fork 复制、重载重建 Parts）。
剩余待办：~~真实第三方 MCP 接入实测~~ ✅（修订 20，browser-core 全链路通）。
**上下文压缩 ✅（修订 16）**：window×0.8 自动触发、保留最近 3 轮、LLM 摘要、
原文 DB 标记可审计、compact 事件 + 分隔线可见、摘要失败不阻断。
**MCP http transport ✅（修订 17）**：Streamable HTTP（2025-03-26）——
manifest `transport: http` + `url`，JSON/SSE 双响应模式，Mcp-Session-Id 会话头。
**真实服务端接入实测 ✅（修订 20）**：miao-browser-core 全链路通（含通知规范修复）。
待办：~~附件/图片输入~~ ✅、~~retry 事件~~ ✅、~~OpenAI 缓存字段~~ ✅（修订 18）；~~真实第三方 MCP 接入实测~~ ✅（修订 20）。
前端开发：`cd web/main && npm run dev`；产物 `npm run build` 后由 Go 磁盘直读。

P4 配套（2026-11-02，修订 19-20 + 实机修复批）：
**配置三层收拢** ✅：app（logLevel/modules/visualHosting）/ pet（physics/statusLink/opaque +
size/hitbox/animations/statusTexts）/ agent；原顶层 modules/animations/workStatusTexts 并入 pet，
manifest 键 workStatusTexts→statusTexts；`physics`/`statusLink` 缺省开并真实接线。
**LLM 双线路 ✅（修订 19）**：`llm.mode: direct|zxjt`；direct 支持 `${VAR}` 展开（.env 优先）；
zxjt（新文件 `internal/agent/llm/zxjt.go`）collectKey+csc 头双凭证同发、网关 errcode 解析、
断流校验；`multimodal` 开关（false 剥图片 part）；模型名**透传不校验**（报错直达对话页提示条）。
配置瘦身：customPrompt/runtimeDir/extendIterations 移除。
**MCP 真实服务端实测 ✅（修订 20）**：browser-core 全链路通；修 notifications/initialized
带 id 的规范 bug（通知必须省略 id）。
**实机修复批**：跨屏白化根治（wails WM_DPICHANGED = setPhysicalBounds 同款路径，
WndProcInterceptor 吞桌宠消息）；打包 GUI 子系统（-H=windowsgui，无黑窗口）；
error 事件前端提示条（不再吞错误）；零信任沙箱白框定性（Electron vs WebView2 透明实现差异，
不修复，沙箱内隐藏宠物；逃生开关 visualHosting/opaque 保留在案）。
**一键打包** ✅：`build/package.ps1`（-Profile hcy|idp -Version x.y.z [-SkipNpm]），
产出自包含目录 `build/out/miao-desk-<版本>/`；profile 机制 = 资源目录叠加（config 覆盖）。
待实测（隔离网段）：zxjt 线路端到端（stream_options 网关接受度）。
**下一步（P4 方向）**：传统软件功能起步（文件管理/音乐播放器模块，`app.modules` 扩展位已留），
或设置页；详见 docs/design.md §10 待决事项。

## 开发

```powershell
# 首次：导入素材（约 56MB，来自 dsh-chatting-pet，可用 -Source 指向其他素材包替换）
powershell scripts/import-assets.ps1

# 构建并运行（F5 调试安装目录 = miao-home/）
# VSCode F5：preLaunchTask 自动构建到 miao-home/ 并以它为 cwd 启动
# 首次使用把 config.yaml 与 .env 拷进 miao-home/（首启也会自动生成默认）
go build -o miao-home/miao-desk.exe ./cmd/miao-desk
miao-home\miao-desk.exe

# 冒烟演示：自动循环六档（验证打断-恢复与气泡）
$env:MIAO_DESK_MOCK_DEMO='1'; miao-home\miao-desk.exe

# Agent 冒烟（不启动 GUI；fake 无需 key，真实模式需 .env 配 LLM_API_KEY）
go build -o miao-home/agent-smoke.exe ./cmd/agent-smoke
miao-home\agent-smoke.exe -fake

# 一键打包（产出完全自包含的便携目录 build/out/miao-desk-<版本>/，资源不嵌二进制）
powershell build/package.ps1                     # 默认 profile=hcy 版本=0.1.0
powershell build/package.ps1 -Profile idp -Version 0.2.0
powershell build/package.ps1 -SkipNpm            # 复用现有 web/main/dist
# profile（build/hcy、build/idp）内容在基础集之后整体叠加到产出，
# 目前各放一份 config.yaml 替换默认版；agent-smoke 默认不打包（-Smoke 可选）

# 配置：首启自动生成 <根>/config.yaml（唯一配置）与 <根>/.env（LLM_API_KEY）
# 安装根推导：MIAO_DESK_HOME > exe 目录 > 当前目录（开发态）
# 日志：stderr + <根>/logs/miao-desk.log，级别 = app.logLevel（默认 info）
#   排查时改 debug：终端与文件同时输出 [chat] 逐事件与 [agent] 每轮消息/完整回复
```

## 许可

- 本项目代码：待定
- 桌宠素材（`assets/`）：来自 dsh-chatting-pet，MIT 许可，详见 [docs/design.md](docs/design.md) 第 8 节