Skip to content

Commit 56de095

Browse files
study8677study8677
committed
feat: bilingual README, one-command setup, LLM-powered briefs, Dashboard UI
- Rename README.md → agent.md (full design spec for AI agents) - New README.md (Chinese) and README_EN.md (English) with Dashboard screenshots - Add make start: one-command interactive setup (no Docker required) - Default to SQLite (zero-config), support env var API Key fallback - Add LLM-powered natural language brief summaries - Fix Dashboard loading: async brief, non-blocking snapshot - Add quickstart.sh with 6 LLM provider presets - Full project source: API, connectors, services, UI, tests (30 passing)
1 parent 070f0c3 commit 56de095

117 files changed

Lines changed: 11508 additions & 2 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.env.example‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# 应用基础配置
2+
STEWARD_APP_NAME=Steward
3+
STEWARD_ENV=dev
4+
STEWARD_TIMEZONE=Asia/Shanghai
5+
STEWARD_LOG_LEVEL=INFO
6+
7+
# 数据库连接（默认指向 docker-compose 中的 postgres）
8+
STEWARD_DATABASE_URL=postgresql+asyncpg://steward:steward@127.0.0.1:5432/steward
9+
10+
# 模型配置文件路径（必须存在，且需填写真实模型配置）
11+
STEWARD_MODEL_CONFIG_FILE=config/model.yaml
12+
STEWARD_INTEGRATION_RUNTIME_FILE=config/integrations.runtime.json
13+
14+
# GitHub 连接器配置
15+
STEWARD_GITHUB_TOKEN=
16+
STEWARD_GITHUB_WEBHOOK_SECRET=
17+
STEWARD_SLACK_SIGNING_SECRET=
18+
STEWARD_GMAIL_PUBSUB_VERIFICATION_TOKEN=
19+
STEWARD_GMAIL_PUBSUB_TOPIC=
20+
STEWARD_GOOGLE_CALENDAR_CHANNEL_TOKEN=
21+
STEWARD_GOOGLE_CALENDAR_CHANNEL_IDS=
22+
STEWARD_EMAIL_WEBHOOK_SECRET=
23+
STEWARD_CHAT_WEBHOOK_SECRET=
24+
STEWARD_CALENDAR_WEBHOOK_SECRET=
25+
STEWARD_SCREEN_WEBHOOK_SECRET=
26+
STEWARD_WEBHOOK_SHARED_SECRET=
27+
28+
STEWARD_EMAIL_OUTBOUND_ENABLED=false
29+
STEWARD_CHAT_OUTBOUND_ENABLED=false
30+
31+
STEWARD_MCP_GATEWAY_BASE_URL=
32+
STEWARD_MCP_GATEWAY_API_KEY=
33+
34+
# macOS 屏幕传感器（可选）
35+
STEWARD_SCREEN_SENSOR_BASE_URL=http://127.0.0.1:8000
36+
STEWARD_SCREEN_SENSOR_INTERVAL_SECONDS=8
37+
STEWARD_SCREEN_SENSOR_HTTP_TIMEOUT_SECONDS=35
38+
STEWARD_SCREEN_WEBHOOK_TOKEN=
39+
40+
# 运行策略
41+
STEWARD_BRIEF_WINDOW_HOURS=4
42+
STEWARD_FALLBACK_POLLING_MINUTES=5
43+
STEWARD_INTERRUPTION_BUDGET_PER_DAY=10
44+
STEWARD_WAITING_TIMEOUT_SCAN_SECONDS=60
45+
STEWARD_ENABLE_SCHEDULER=true
46+
STEWARD_WEBHOOK_BACKPRESSURE_MAX_INFLIGHT=12
47+
STEWARD_WEBHOOK_BACKPRESSURE_MAX_EVENTS_PER_WINDOW=120
48+
STEWARD_WEBHOOK_BACKPRESSURE_WINDOW_SECONDS=10
49+
STEWARD_WEBHOOK_BACKPRESSURE_DEDUP_TTL_SECONDS=120

‎.gitignore‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Python 缓存与构建产物
2+
__pycache__/
3+
*.py[cod]
4+
*.so
5+
*.egg-info/
6+
.pytest_cache/
7+
.mypy_cache/
8+
.ruff_cache/
9+
.coverage
10+
htmlcov/
11+
12+
# 虚拟环境
13+
.venv/
14+
15+
# 环境变量
16+
.env
17+
config/model.yaml
18+
config/integrations.runtime.json
19+
20+
# 本地数据库与日志
21+
*.db
22+
*.db-shm
23+
*.db-wal
24+
logs/
25+
26+
# 前端依赖
27+
node_modules/
28+
29+
# IDE 与系统文件
30+
.DS_Store
31+
.vscode/
32+
.idea/
33+
34+
# Alembic 运行时文件
35+
migrations/__pycache__/

‎.pre-commit-config.yaml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
repos:
2+
- repo: https://github.com/astral-sh/ruff-pre-commit
3+
rev: v0.15.4
4+
hooks:
5+
- id: ruff-check
6+
- id: ruff-format
7+
- repo: local
8+
hooks:
9+
- id: check-module-comments
10+
name: check-module-comments
11+
entry: python scripts/check_module_comments.py
12+
language: system
13+
pass_filenames: false

‎.python-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
3.14

‎Makefile‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Steward 项目常用命令集合。
2+
3+
VENV := .venv
4+
PYTHON := $(VENV)/bin/python
5+
UV := $(VENV)/bin/uv
6+
7+
.PHONY: start bootstrap doctor lint test format run migrate upgrade downgrade
8+
9+
# 一键启动（新用户推荐入口）
10+
start:
11+
@bash scripts/quickstart.sh
12+
13+
bootstrap:
14+
bash scripts/bootstrap_macos.sh
15+
16+
doctor:
17+
@echo "[doctor] 检查 Python 与虚拟环境"
18+
@test -x "$(PYTHON)" || (echo "[doctor] 缺少 $(PYTHON)，请先运行 make bootstrap" && exit 1)
19+
@$(PYTHON) --version
20+
@test -x "$(UV)" || (echo "[doctor] 缺少 $(UV)，请先运行 make bootstrap" && exit 1)
21+
@$(UV) --version
22+
@echo "[doctor] 检查 Docker Desktop"
23+
@if command -v docker >/dev/null 2>&1; then docker --version; else echo "[doctor] 警告：未检测到 docker，数据库相关命令将不可用"; fi
24+
@echo "[doctor] 检查完成"
25+
26+
lint:
27+
$(UV) run ruff check .
28+
$(UV) run mypy src tests
29+
$(UV) run python scripts/check_module_comments.py
30+
31+
test:
32+
$(UV) run pytest
33+
34+
format:
35+
$(UV) run ruff format .
36+
37+
run:
38+
$(UV) run uvicorn steward.main:app --host 127.0.0.1 --port 8000 --reload
39+
40+
migrate:
41+
$(UV) run alembic revision --autogenerate -m "auto migration"
42+
43+
upgrade:
44+
$(UV) run alembic upgrade head
45+
46+
downgrade:
47+
$(UV) run alembic downgrade -1

‎README.md‎

Lines changed: 159 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,159 @@
1-
# Steward
2-
一个无感感知上下文、主动推进事务、只在关键决策点打扰用户的协作 Agent。An ambient proactive agent that handles low-risk work automatically and briefs users only when their judgment is needed.
1+
<p align="center">
2+
<h1 align="center">🤖 Steward</h1>
3+
<p align="center">
4+
<strong>一个无感常驻、主动推进事务的协作 Agent。</strong><br>
5+
把高频噪音交给系统，把决策时间留给你。
6+
</p>
7+
<p align="center">
8+
<a href="./README_EN.md">English</a> · <a href="./agent.md">Agent Spec</a> · <a href="http://127.0.0.1:8000/dashboard">Dashboard</a>
9+
</p>
10+
</p>
11+
12+
---
13+
14+
## 💡 为什么做 Steward
15+
16+
想象你在玩一款策略游戏——《钢铁雄心》或《文明》。你不想亲自管理"第一军团少了一支枪"，你想做的是**制定战略**，然后让系统根据战场态势自行执行。
17+
18+
现实工作中的你也是如此：
19+
20+
> **80% 的事务是低风险、可自动化的噪音。**
21+
> 你的注意力应该只花在那 **20% 真正需要你判断的决策**上。
22+
23+
Steward 就是你的数字管家——它静默感知邮件、GitHub、日历、聊天等多源信号，主动识别并推进待办事项，**低风险的事情自动做完，只在关键决策时才打扰你**。
24+
25+
## ✨ 核心特性
26+
27+
| 特性 | 描述 |
28+
|-----|------|
29+
| 🔇 **无感常驻** | 7×24 后台运行，默认不弹窗，只在关键时刻打扰 |
30+
| 🧠 **多源感知** | GitHub、邮件、日历、聊天、屏幕信号——统一接入的一等信号源 |
31+
| ⚡ **自主执行** | 低风险任务自动完成，带审计记录和回滚能力 |
32+
| 🛡️ **策略门禁** | 高风险/不可逆动作必须人工确认，安全底线不可配置绕过 |
33+
| 📋 **定时简报** | 每 4 小时汇总一次，用自然语言告诉你"做了什么、等什么、需要你决定什么" |
34+
| 🔌 **可插拔连接器** | Slack、Gmail、Google Calendar、MCP——通过统一 Connector 协议接入 |
35+
| 🧩 **冲突仲裁** | 多任务竞争同一资源时，自动合并/串行/升级处理 |
36+
37+
## 📸 Dashboard 预览
38+
39+
<p align="center">
40+
<img src="docs/images/dashboard_overview.png" width="100%" alt="Dashboard 概览 — KPI 卡片、待确认计划、冲突工单">
41+
</p>
42+
43+
<p align="center">
44+
<img src="docs/images/dashboard_connectors.png" width="100%" alt="连接器健康状态 & 自然语言输入">
45+
</p>
46+
47+
<p align="center">
48+
<img src="docs/images/dashboard_brief.png" width="100%" alt="LLM 驱动的自然语言简报 & 运行日志">
49+
</p>
50+
51+
## 🚀 快速开始
52+
53+
**只需要一行命令。**
54+
55+
```bash
56+
git clone https://github.com/user/Steward.git
57+
cd Steward
58+
make start
59+
```
60+
61+
终端会交互式引导你完成配置：
62+
63+
```
64+
╔══════════════════════════════════════╗
65+
║ 🤖 Steward 一键启动向导 ║
66+
╚══════════════════════════════════════╝
67+
68+
✅ Python: Python 3.14.2
69+
✅ 虚拟环境已创建
70+
✅ 依赖安装完成
71+
72+
📋 配置大模型 API（必填项）
73+
请选择大模型供应商：
74+
1) OpenAI 2) DeepSeek 3) NVIDIA NIM
75+
4) 智谱 GLM 5) Moonshot 6) 自定义 URL
76+
77+
请输入 API Key: ▎
78+
79+
🚀 一切就绪！正在启动 Steward...
80+
Dashboard: http://127.0.0.1:8000/dashboard
81+
```
82+
83+
仅需填入一个 **API Key**，无需 Docker，无需手工编辑配置文件。
84+
85+
> 💡 **进阶用户**：如需使用 Postgres，设置环境变量 `STEWARD_DATABASE_URL` 并运行 `docker compose up -d && make upgrade`。
86+
87+
## 🏗️ 架构概览
88+
89+
```
90+
信号源 (GitHub / 邮件 / 日历 / 屏幕 / MCP)
91+
│
92+
▼
93+
┌─────────────┐
94+
│ 感知入口 │ ← Webhook / 轮询 / 屏幕传感器
95+
└──────┬──────┘
96+
│
97+
▼
98+
┌─────────────┐
99+
│ Context Space│ ← 跨源信号聚合、实体解析
100+
└──────┬──────┘
101+
│
102+
▼
103+
┌─────────────┐
104+
│ 策略门禁 │ ← 风险评估、置信度、打扰预算
105+
└──────┬──────┘
106+
│
107+
┌────┴────┐
108+
▼ ▼
109+
自动执行 请求确认
110+
│ │
111+
▼ ▼
112+
┌─────────────┐
113+
│ 简报 & 审计 │ ← 自然语言总结、完整决策轨迹
114+
└─────────────┘
115+
```
116+
117+
## 🛠️ 技术栈
118+
119+
| 层 | 技术 |
120+
|---|------|
121+
| 语言 | Python 3.14 + asyncio |
122+
| 服务层 | FastAPI + Uvicorn |
123+
| 数据层 | SQLite（默认）/ PostgreSQL + SQLAlchemy + Alembic |
124+
| 调度 | APScheduler（事件驱动优先，轮询兜底） |
125+
| 模型 | OpenAI 兼容 API（任意供应商） |
126+
| 可观测性 | structlog + OpenTelemetry + Prometheus |
127+
128+
## 📁 项目结构
129+
130+
```
131+
steward/
132+
├── api/ # FastAPI 路由（REST + Webhook）
133+
├── core/ # 配置、日志、模型层
134+
├── domain/ # 枚举、Schema、领域模型
135+
├── infra/ # 数据库、迁移
136+
├── connectors/ # GitHub / Email / Calendar / MCP 连接器
137+
├── services/ # 核心业务逻辑（门禁、简报、冲突仲裁）
138+
├── runtime/ # 调度器、状态机
139+
├── macos/ # macOS 托盘 & 屏幕传感器
140+
└── ui/ # Dashboard 前端
141+
```
142+
143+
## 📖 深入了解
144+
145+
- **[agent.md](./agent.md)**：完整的设计规范（800+ 行），涵盖 Context Space、策略门禁、冲突仲裁、状态机、个性化学习等所有机制的第一性原理推导。
146+
147+
## 🤝 贡献
148+
149+
欢迎提交 Issue 和 PR。请先阅读 [agent.md](./agent.md) 了解设计理念。
150+
151+
```bash
152+
make lint # 代码检查
153+
make test # 运行测试
154+
make format # 代码格式化
155+
```
156+
157+
## 📄 License
158+
159+
[MIT](./LICENSE)

0 commit comments

Comments
 (0)