{"id":46282971,"url":"https://github.com/study8677/steward","last_synced_at":"2026-03-07T09:01:09.288Z","repository":{"id":341374284,"uuid":"1169212219","full_name":"study8677/Steward","owner":"study8677","description":"一个无感感知上下文、主动推进事务、只在关键决策点打扰用户的协作 Agent。An ambient proactive agent that handles low-risk work automatically and briefs users only when their judgment is needed.","archived":false,"fork":false,"pushed_at":"2026-03-03T12:08:33.000Z","size":7637,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T09:46:07.470Z","etag":null,"topics":["agent","agentic-ai","assistant","automation","llm"],"latest_commit_sha":null,"homepage":"https://github.com/study8677/Steward","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/study8677.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-28T10:45:27.000Z","updated_at":"2026-03-03T12:08:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/study8677/Steward","commit_stats":null,"previous_names":["study8677/steward"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/study8677/Steward","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/study8677%2FSteward","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/study8677%2FSteward/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/study8677%2FSteward/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/study8677%2FSteward/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/study8677","download_url":"https://codeload.github.com/study8677/Steward/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/study8677%2FSteward/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30113108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T03:40:26.266Z","status":"ssl_error","status_checked_at":"2026-03-05T03:39:15.902Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agentic-ai","assistant","automation","llm"],"created_at":"2026-03-04T06:17:57.899Z","updated_at":"2026-03-05T07:00:58.498Z","avatar_url":"https://github.com/study8677.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003e🤖 Steward\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cstrong\u003eAn ambient, proactive agent that handles low-risk work automatically\u003cbr\u003eand briefs you only when your judgment is needed.\u003c/strong\u003e\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"./README_CN.md\"\u003e中文\u003c/a\u003e · \u003ca href=\"./agent.md\"\u003eAgent Spec\u003c/a\u003e · \u003ca href=\"http://127.0.0.1:8000/dashboard\"\u003eDashboard\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n---\n\n## 💡 Why Steward\n\nPicture yourself playing a grand strategy game — *Hearts of Iron* or *Civilization*. You don't want to manage \"the 1st Corps is missing a rifle.\" You want to **set the strategy** and let the system adapt and execute based on the situation.\n\nYour real work life is the same:\n\n\u003e **80% of your tasks are low-risk, automatable noise.**\n\u003e Your attention should be reserved for the **20% that truly require your judgment**.\n\nSteward is your digital chief of staff — it silently monitors emails, GitHub, calendars, chat, and more, proactively identifies and advances your to-dos. **Low-risk tasks get done automatically. You're only interrupted for decisions that matter.**\n\n## ✨ Key Features\n\n| Feature | Description |\n|---------|-------------|\n| 🔇 **Ambient** | Runs 24/7 in the background, zero popups by default |\n| 🧠 **Multi-Source Perception** | GitHub, email, calendar, chat, screen — all first-class signal sources |\n| ⚡ **Autonomous Execution** | Low-risk tasks auto-completed with full audit trail and rollback capability |\n| 🛡️ **Policy Gate** | High-risk / irreversible actions require explicit human approval — no override possible |\n| 📋 **Periodic Briefs** | Every 4 hours: natural language summary of \"what was done, what's pending, what needs your call\" |\n| 🔌 **Capability Hub (MCP + Skills)** | Community-first capability model with unified enable/disable/configure flow in Dashboard |\n| 🧩 **Conflict Arbiter** | When multiple plans compete for the same resource: auto merge / serialize / escalate |\n\n## 📸 Dashboard Preview\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/dashboard.png\" width=\"100%\" alt=\"Dashboard — Pending plans, connector health, natural language input, briefs \u0026 logs\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/integrations.png\" width=\"100%\" alt=\"Capability Hub — MCP Servers \u0026 Skills management with NL config\"\u003e\n\u003c/p\u003e\n\n## 🚀 Quick Start\n\n### 1) API/UI quick start (no Docker required)\n\n```bash\ngit clone https://github.com/user/Steward.git\ncd Steward\nmake start\n```\n\nAn interactive wizard walks you through setup:\n\n```\n╔══════════════════════════════════════╗\n║     🤖  Steward Quick Start         ║\n╚══════════════════════════════════════╝\n\n✅ Python: Python 3.14.2\n✅ Virtual environment created\n✅ Dependencies installed\n\n📋 Configure LLM API (required)\n  Select your LLM provider:\n  1) OpenAI   2) DeepSeek   3) NVIDIA NIM\n  4) GLM      5) Moonshot   6) Custom URL\n\n  Enter API Key: ▎\n\n🚀 All set! Starting Steward...\n   Dashboard:  http://127.0.0.1:8000/dashboard\n```\n\nQuick Start also includes an optional capability step:\n- `GitHub Agent Bundle` (recommended): enables GitHub MCP + detected local skills (`gh-address-comments`, `gh-fix-ci`, `playwright`, `gog`, `self-improving-agent`, `github-api-gateway`).\n- If a skill is not installed locally, the wizard reports it and you can enable it later in `/dashboard/integrations`.\n- You can also link project-local skills to Codex with `make install-skills`.\n\nThis mode is great for local exploration of API/UI and manual confirmation flows.\n\n### 2) Full real execution mode (recommended)\n\nTo run **real asynchronous execution** (`gate_result=auto` dispatches to queue), Steward needs:\n\n- a Redis broker\n- a running worker process (`steward-worker`)\n\nDocker is **not mandatory**. It is only the easiest way to boot Postgres + Redis locally.\n\n```bash\n# terminal A\ndocker compose up -d        # starts postgres + redis\nmake upgrade\nmake run\n\n# terminal B\nmake worker\n```\n\nIf you don't want Docker, use your local Postgres/Redis instead and set env vars accordingly.\n\n### 3) API/UI only with execution disabled (optional)\n\n```bash\nexport STEWARD_EXECUTION_ENABLED=false\nmake run\n```\n\n## 🔌 Capability Management (First Principles)\n\n- Single capability model: `MCP Server + Skill` is the primary integration abstraction.\n- Community-first reuse: prefer existing MCP servers and local/community skills before custom providers.\n- Dashboard entry: `http://127.0.0.1:8000/dashboard/integrations`.\n- Core API:\n  - `GET /api/v1/integrations`\n  - `POST /api/v1/integrations/nl`\n  - `POST /api/v1/integrations/mcp/{server}/configure|enable|disable`\n  - `POST /api/v1/integrations/skills/{skill}/configure|enable|disable`\n- GitHub issue sensing:\n  - Webhook callback: `POST /api/v1/webhooks/providers/github`\n  - Configure webhook secret via `STEWARD_GITHUB_WEBHOOK_SECRET` (or integrations API/NL)\n  - In GitHub Webhook events, enable `issues`, `issue_comment`, `pull_request`\n  - Low-risk GitHub issues/comments can be silently auto-replied (no manual confirm) through `plan -\u003e gate(auto) -\u003e worker execute`\n  - GitHub auto reply is now agentic: uses issue content + local repo context to generate bilingual replies\n  - `issue_comment` loop protection: self-authored bot comments are skipped; user comments can still trigger follow-up\n  - Status: currently under active prompt/policy tuning for reply quality and false-positive control\n- Runtime persistence: `config/integrations.runtime.json` (`config`, `custom_providers`, `mcp_servers`, `skills`).\n- Compatibility note: `/api/v1/skills` remains as a compatibility facade, backed by the same integration state.\n\n### Security Notes (Secrets)\n\n- Do not commit `.env` or real tokens/secrets.\n- Keep only placeholders in `.env.example`.\n- `config/integrations.runtime.json` is runtime state; if it contains real secrets, rotate them and keep them out of Git history.\n\n## 📊 Execution Results Page\n\n- Dashboard entries:\n  - `http://127.0.0.1:8000/dashboard` (main)\n  - `http://127.0.0.1:8000/dashboard/executions` (execution results)\n- `Executions` view now includes:\n  - human-readable summaries for dispatch status/trigger/step outcomes\n  - bilingual rendering (`zh/en`) based on current UI language\n  - direct link to open saved manual notes (`record_note`) from the page\n- Core APIs:\n  - `GET /api/v1/dashboard/executions?limit=50\u0026lang=zh|en`\n  - `GET /api/v1/dashboard/records/{filename}` (safe markdown record read for journal notes)\n\n## 🏗️ Architecture\n\n```\nSignal Sources (GitHub / Email / Calendar / Screen / MCP / Skill)\n         │\n         ▼\n   ┌─────────────┐\n   │  Perception  │  ← Webhooks / Polling / Screen Sensor\n   └──────┬──────┘\n          │\n          ▼\n   ┌─────────────┐\n   │ Context Space│  ← Cross-source aggregation \u0026 entity resolution\n   └──────┬──────┘\n          │\n          ▼\n   ┌─────────────┐\n   │  Planner     │  ← Intent inference → single agent_execute step\n   └──────┬──────┘\n          │\n          ▼\n   ┌─────────────┐\n   │ Policy Gate  │  ← Risk assessment, confidence, interruption budget\n   └──────┬──────┘\n          │\n          ▼\n   ┌────────────────┐\n   │ ExecutionAgent  │  ← LiteLLM acompletion() ReAct Loop\n   │  (Tool Calling) │     Think → Tool Call → Result → Think ...\n   └──────┬─────────┘\n          │\n    ┌─────┴──────┐\n    ▼            ▼\n  ToolRegistry  Ask User\n  (MCP/Skill)     │\n    │              ▼\n    ▼         ┌─────────────┐\n  Execute     │ Brief \u0026 Audit│  ← NL summaries + execution logs\n              └─────────────┘\n```\n\n## 🛠️ Tech Stack\n\n| Layer | Technology |\n|-------|-----------|\n| Language | Python 3.14 + asyncio |\n| API | FastAPI + Uvicorn |\n| Data | SQLite (default) / PostgreSQL + SQLAlchemy + Alembic |\n| Scheduling | APScheduler (event-driven first, polling as fallback) |\n| Execution Runtime | Celery + Redis |\n| Agent Engine | LiteLLM + OpenAI Tool Calling (ReAct loop) |\n| Models | Any LLM via LiteLLM (DeepSeek / Claude / GPT / NVIDIA NIM / Moonshot etc.) |\n| Observability | structlog + OpenTelemetry + Prometheus |\n\n## 📁 Project Structure\n\n```\nsteward/\n├── api/              # FastAPI routes (REST + Webhooks)\n├── planning/         # Superpowers-guided plan compilation and policy checks\n├── core/             # Config, logging, model layer\n├── domain/           # Enums, schemas, domain models\n├── infra/            # Database, migrations\n├── connectors/       # GitHub / Email / Calendar / MCP / Skill connectors\n├── connectors_runtime/# Declarative connector specs + runtime validation\n├── services/         # Core logic (policy gate, briefs, conflict arbiter)\n├── runtime/          # Scheduler + async execution worker runtime\n├── macos/            # macOS menu bar shell\n├── screen_sensor/    # Cross-platform screen sensor (macOS / Windows / Linux)\n└── ui/               # Dashboard frontend\n```\n\n## 📖 Learn More\n\n- **[agent.md](./agent.md)**: The full design specification (800+ lines) — first-principles derivation of Context Space, Policy Gate, Conflict Arbiter, State Machine, personalized learning, and every other mechanism.\n\n## 🤝 Contributing\n\nIssues and PRs welcome. Please read [agent.md](./agent.md) first to understand the design philosophy.\n\n```bash\nmake lint    # Code linting\nmake test    # Run tests\nmake format  # Code formatting\n```\n\n## 📄 License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstudy8677%2Fsteward","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstudy8677%2Fsteward","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstudy8677%2Fsteward/lists"}