Superstar

Superstar 是一个本地、单用户、无鉴权的「干活型」Agent：后端使用 FastAPI， 前端使用 React + Vite，通过流式对话、工具调用、审批恢复、JSONL 会话、记忆、 RAG、Skill、MCP、飞书接入和 Telemetry 把 Agent 的执行过程呈现为可检查的工作流。 它目前只面向本机可信用户，不是多租户或公网服务。

环境要求

• Python 3.11+ 和 uv
• Node.js 24+ 和 npm
• Docker（双模式 Compose、真实 Qdrant/RAG 或容器验证需要）

本地运行

后端

cd backend
uv sync --dev
cp config.example.json data/config.json
cp .env.example .env                 # 可选；不复制也使用安全默认值
uv run python run.py                 # 开发入口：http://127.0.0.1:8000

run.py 是带 reload 的开发入口。业务配置位于 backend/data/config.json， 可由设置页热更新；启动配置位于 backend/.env。DATA_DIR、HOST、PORT 和 QDRANT_URL 都可以用环境变量覆盖。API key、飞书凭证等密钥只在运行时提供， 不得提交到仓库。

前端

cd frontend
npm ci
npm run dev                          # http://127.0.0.1:5173

开发服务器把相对路径 /api 代理到 http://127.0.0.1:8000。需要真实知识库时， 另行启动 Qdrant，并让后端的 QDRANT_URL 指向它。

Docker Compose 双模式

Compose 已提供两套独立拓扑。先把 Agent 可访问的一个窄目录设为绝对路径；开发 token 必须按 docs/runbooks/compose.md 生成，不能复制示例占位值直接使用。

export SUPERSTAR_WORKSPACE=/absolute/path/to/one/workspace

# 开发：Vite HMR + Uvicorn reload + Qdrant
docker compose -f compose.dev.yml up --build
docker compose -f compose.dev.yml down

# 正式：FastAPI 直接提供 API + built SPA，并连接 Qdrant
docker compose -f compose.yml up --build
docker compose -f compose.yml down

两种模式共享持久卷，必须先停止当前模式再切换，不能同时运行。宿主入口只绑定 127.0.0.1；这是本机单用户边界，不是鉴权，不能直接改成 LAN/公网服务。完整的 token 生成、数据备份/恢复、安全边界和验证状态见 docs/runbooks/compose.md，验收合同见 docs/runbooks/compose-readiness.md。

自动验证

以下当前入口使用确定性数据，不需要真实 LLM、Qdrant、MCP 或飞书凭证。 是否可交付以最近一次完整执行结果为准，不能用单个构建或测试子集代替全套门禁。

# 后端完整回归（在 backend/）
.venv/bin/python -m pytest -q

# 确定性 Agent Eval（在 backend/）
.venv/bin/python -m app.evals validate evals/suites/offline-core-v1.json
.venv/bin/python -m pytest tests/evals -q
.venv/bin/python -m app.evals run evals/suites/offline-core-v1.json --output /private/tmp/superstar-evals

# 前端单测、静态检查和生产构建（在 frontend/）
npm test
npm run lint
npm run build

自动验证覆盖会话与审批状态、工具安全边界、记忆与 Skill、MCP 管理、Telemetry、 离线 Eval、前端指标逻辑和浏览器级关键流程。以下命令已经是当前门禁：

# Task 7：覆盖率非回归门禁（在 backend/）
.venv/bin/python -m pytest --cov=app --cov-branch --cov-report=term-missing --cov-fail-under=87

# Task 8：Playwright 浏览器关键流程（在 frontend/）
npm run test:e2e

需要真实环境验证

LLM 与 Tool Calling、记忆蒸馏、Qdrant/RAG、MCP 传输和飞书消息均受账号、网络、 模型及目标环境影响。统一 smoke 入口也不能替代操作者对目标和授权的确认；未运行的真实能力保持 未验证状态，默认跳过不等于通过，某次通过也不代表其他环境或未来时刻仍然可用。

当前已提供统一 Smoke CLI 和隐私安全报告入口：

cd backend
.venv/bin/python scripts/smoke.py --probe llm
.venv/bin/python scripts/smoke.py --probe distill

# 会创建远端临时数据的 probe 还必须显式允许副作用，
# 并确认使用专门的测试目标。
.venv/bin/python scripts/smoke.py --probe qdrant --allow-side-effects --dedicated-target

统一 CLI 把隐私收敛后的 JSON 与 Markdown 证据写到 DATA_DIR/smoke/。报告只说明 所选 probe 是 passed、failed 还是 skipped，不保存 prompt、回答、工具参数/结果、完整 URL、凭证或原始异常。授权边界和操作步骤见 docs/runbooks/live-smoke.md。真实 LLM、 distill gateway、Qdrant、MCP server 以及飞书消息/审批仍未在本轮执行，接线或 skipped 不能算 live pass。

明确暂缓

• 多用户鉴权、公网暴露、多 FastAPI worker 与分布式 session lease 暂缓。
• OS/容器级 Agent workspace 沙箱、集中式可观测平台和生产流量评测暂缓。
• 飞书继续由 backend 管理的子进程承载，不拆成独立服务。

配置与数据边界

• backend/config.example.json 是无凭证的完整业务配置模板；工作区使用 security.default_cwd 和 security.allowed_dirs。
• backend/.env.example 是启动配置模板；容器阶段必须显式设置持久化 DATA_DIR 与服务内 QDRANT_URL。
• backend/data/ 当前保存配置、会话、记忆、Telemetry、Eval 和 Smoke 报告等本地状态； 该目录已被 Git 忽略。用户 workspace 必须 独立挂载，不能隐式暴露宿主目录。

后端细节见 backend/README.md，前端细节见 frontend/README.md。历史蓝图与交接记录 保留在 DEVELOPMENT_PLAN.md 和 HANDOFF.md，当前交付边界以本文件和 docs/superpowers/specs/2026-08-12-delivery-readiness-design.md 为准。