# agent-smart-screen

**Repository Path**: madalin/agent-smart-screen

## Basic Information

- **Project Name**: agent-smart-screen
- **Description**: 智能体用来投送内容的屏幕
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-23
- **Last Updated**: 2026-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent 智慧屏

智能体通过远程 MCP 发布图片、Markdown、受控 HTML、PDF 和文件，
个人电脑或会议室通过浏览器打开同一服务器的 Web 智慧屏，无需安装展示客户端。
Web 智慧屏支持内容展示、个人屏幕连接、会议室扫码绑定和演示控制。
可选 Windows 客户端提供桌面常驻、本机程序联动，以及个人设备的业务 Sidebar，
包含提醒、一客一档、名单、进度、账目和其它六类栏目，业务数据由智能体维护。

- [Web 智慧屏使用](docs/guides/WEB_SCREEN.md)
- [Windows 展示端](docs/guides/WINDOWS.md)
- [真实用户账号与管理](docs/guides/ACCOUNTS.md)
- [启动与测试](docs/guides/QUICKSTART.md)
- [远程 MCP 接入](docs/guides/REMOTE_MCP.md)
- [Linux 原生部署与安全](docs/guides/DEPLOYMENT.md)
- [实机验收](docs/guides/ACCEPTANCE.md)
- [API 协议](docs/design/API_V2.md)
- [设计方案](docs/design/AGENT_SMART_SCREEN_DESIGN.md)
- [实施记录](docs/implementation/PLAN.md)
- [验证报告](docs/implementation/VERIFICATION.md)

## 真实用户入口

使用 `SMART_SCREEN_AUTH_MODE=local` 启用用户名密码与邀请码注册。
管理员首次运行 `python -m smart_screen.cli create-admin admin`，在终端隐藏输入密码，
随后通过 `/account` 发邀请码、管理用户与空间配额。
普通用户注册登录后自主创建 API Key，连接 `/mcp`，查看自己的历史记录。
生产采用 HTTPS、PostgreSQL、ClamAV，具体初始化步骤见账号与部署指南。
Windows 0.3.3 包已支持默认 HTML 脚本、离线图表与精简展示界面；Linux 服务按部署指南使用当前源码更新。

## Windows 端连接远端

Windows 客户端可直接连接远端服务，无需在本机启动服务端：

1. 按部署指南准备远端服务，并注册或开通用户账号。
2. 运行 Windows 0.3.3 包中的 `AgentSmartScreen/AgentSmartScreen.exe`。
3. 在“连接设置”填写 `https://你的域名`，选择“个人设备”，
   用“账号登录”填写用户名密码后自动绑定，无需预先取得 device-key；
   外部 OIDC 账号仍用“浏览器绑定”。
4. 已有设备凭证时，也可填写设备 Key 连接；不能使用智能体 API Key。

个人设备支持智慧屏内容展示和业务 Sidebar；共享会议室模式不显示私人 Sidebar。
智能体连接同一服务器的 `/mcp`，使用用户 API Key，查询并选择已绑定的 Windows 设备投送内容。
正式连接要求 HTTPS。只有 IP 的多人测试可按[部署指南](docs/guides/DEPLOYMENT.md#仅有-ip-的多人-http-测试)
启用 `SMART_SCREEN_INSECURE_HTTP_TEST=true`，Windows 端勾选“允许 IP HTTP 测试”；
无需 SSH 转发，但密码、密钥和内容明文传输，只用于限制访问来源的测试环境。
HTTP 测试也可直接用“账号登录”，无需浏览器回传凭据。旧 0.3.0 EXE 不含最新功能。

## Windows 发布包

最新发布目录：`release/AgentSmartScreen-0.3.3`。
压缩包：`release/AgentSmartScreen-0.3.3-Windows.zip`。
只包含 Windows 展示客户端，不附带测试服务器。保留 `_internal`，不能只复制 EXE。

名称与图标统一为 Agent智慧屏和 ARC Logo。默认内容布局与 Web 一致，
保留 Windows 的 Sidebar、托盘、显示器选择和本机程序联动。
原有加密连接配置仍兼容；服务独立部署，不因客户端更新重建数据库或账号。
HTML 默认允许脚本和内置 ECharts/Chart.js 离线图表；支持上传 `.js` 资源，
显式 `interactive=false` 保留静态模式。旧内容不会自动改为交互，请重新发布新内容。

## 源码运行

Python 3.11+；Windows 10/11 展示端，服务端也可部署于 Linux：

Linux 使用 Python 虚拟环境与 systemd，不使用 Docker；PostgreSQL、
ClamAV、Nginx 原生安装，配置模板位于 `deploy/`。详见部署指南。

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[smart]"
$env:SMART_SCREEN_AUTH_MODE = "local"
.\.venv\Scripts\python.exe -m smart_screen.cli --dev create-admin admin
.\.venv\Scripts\python.exe -m smart_screen.cli --dev serve
```

管理员只创建一次；打开 `http://127.0.0.1:8766/auth/login?next=/account` 登录。
`--dev` 在此只用于回环网络和结构检查，local 模式仍要求真实密码，不开放自动登录。
远程部署不得使用 `--dev`，按部署指南配置 HTTPS、PostgreSQL 与 ClamAV。

打开 `/screen` 即可展示，不需要 Qt。要运行 Windows 增强端，
另行安装 `.[screen]` 并执行 `python -m smart_screen.desktop_main`。
所有入口归入 `smart_screen`；侧栏模块位于 `smart_screen/panel`，
业务模型位于 `smart_screen/sidebar_models.py`。
个人配置、加密缓存位于 `%LOCALAPPDATA%\AgentSmartScreen`，
使用 Windows DPAPI，不以明文降级。

## 验证与构建

```powershell
.\.venv\Scripts\python.exe -m pip install -e ".[smart,screen,test,browser,build]"
$env:SMART_SCREEN_BROWSER_CHANNEL = "msedge"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m ruff check --no-cache smart_screen tests tools
.\.venv\Scripts\python.exe tools/build_smart_release.py
.\.venv\Scripts\python.exe tools/verify_smart_release.py --storage-parent D:\projects
.\.venv\Scripts\python.exe tools/verify_web_release.py
```

浏览器测试使用本机 Edge；其他环境可设置 `chromium` 并先运行
`python -m playwright install chromium`。未配置浏览器时跳过可选浏览器测试。
测试使用独立临时库，不修改运行数据；跨盘验证的临时存储父目录必须实际存在。
构建产物位于 `release/`，不提交 Git。第三方许可见
[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)。
生产本地账号或可选 OIDC、PostgreSQL、ClamAV、可选 S3、实体大屏与签名仍需目标环境验收，
本机自动化通过不等于商业上线验收。