Vibelution

本地优先的 AI Agent 工作台。把编码对话、Agent 管理、Git、Teams 科研流程、自进化、监督评测和运行日志收在同一套本机 runtime 里（Python / FastAPI + React 界面 + launcher）。

不是托管聊天壳，也不打算把你的仓库默认送上云端。配置和密钥放在用户目录的外部 config.toml，不进这个 git 仓库。

当前版本 1.1.2（见 VERSION · CHANGELOG.md）。

文档入口：快速开始 · Windows 安装（最终用户） · 当前能力 · CONTRIBUTING.md · docs/product · LICENSE

界面预览

当前能力

面	做什么
Chat	多会话编码协作，群聊入口、消息流、停/续、工具与 Prompt 装配侧栏
Agent	注册表、提示词、工具与技能边界、模型槽位、权限
Teams	科研团队壳 + 运行态工作流画布（知识搜集 → 实验设计 → 执行迭代；Agent / 人工门禁 / 系统 / 决策节点；条件分支与 Inspector）
Memory	知识库、图谱与治理入口
Git	顶栏状态、diff、选文件提交、commit message 草稿
Self Evolution	有边界的自检 / 自改，带审计和回滚记录
Supervised Evolution	dataset / bundle 对比、run、提案和建议基线
Runtime Scenes	按次打包前后端、浏览器、生命周期日志，方便查卡住或失败
Config / Reset / Pet	模型与运行配置、白名单清理、陪伴体状态

默认按本机 workbench 用。Windows 最终用户见下方快速开始 · 最终用户；开发者见开发者路径。没有零安装的在线 SaaS 形态。Phase 2 规划便携包（内嵌运行时），见 docs/product/2026-08-06-windows-end-user-install.md。

运行模式

模式	作用	常用入口
`chat`	日常对话式编码协作、文件阅读、会话状态管理	Web `/chat` 或 `python agent.py --mode chat`
`self_evolution`	在当前仓库内执行有界自检、自修改、验证和回滚记录	Web `/self-evolution` 或 headless 模式
`supervised_evolution`	用 dataset / bundle 比较 baseline 与 candidate，生成决策、lineage 和 proposal	Web `/supervised-evolution` 或 CLI 参数

模式定义与策略入口位于 core/orchestration/agent_modes.py。

项目结构

Vibelution/
├── agent.py                    # Agent 主入口与主循环编排
├── config/                     # 配置模型库、provider、runtime defaults 与 public config 同步
├── core/
│   ├── chat/                   # Chat session、结果格式与任务状态
│   ├── evaluation/             # 监督进化、dataset registry、dashboard、chat case review
│   ├── gym/                    # proposal lifecycle、advisory baseline、promotion 记录
│   ├── infrastructure/         # session、tool executor、git memory、security、workspace
│   ├── orchestration/          # 模式策略、委托、输出边界、回合收束
│   ├── prompt_manager/         # prompt 组装、任务分析、代码库地图
│   ├── runtime_manager/        # Web workbench 与运行进程生命周期
│   ├── web/                    # FastAPI app、routes、services
│   └── logging/                # transcript、tool tracker、runtime scene 日志
├── tools/                      # Agent 可见工具与内部工具封装
├── docs/                       # 文档地图：standards / product / ops / adr / archive
├── web/                        # React + Vite 前端工程
├── workspace/                  # 本地运行态产物、evaluation 数据和日志
├── tests/                      # Python 测试套件
├── scripts/web_workbench.py    # 本地 Web workbench 启动脚本
└── .docs/project-memory/       # 项目记忆与多页 HTML 状态面

快速开始

最终用户（Windows，推荐）

目标：尽量少步骤打开本机工作台并开始对话配置。详细步骤见 docs/guides/install-windows.md。

Phase 1 前提（本机需已安装）：Python 3.11+、Node.js 18+（含 npm）、Git、Edge 推荐。 Phase 2 将提供尽量不要求预装 Python/Node 的便携包。

# 在仓库根目录（或发布包解压目录）
powershell -ExecutionPolicy Bypass -File scripts/install_windows.ps1
# 可选：装完直接启动
powershell -ExecutionPolicy Bypass -File scripts/install_windows.ps1 -Start

然后：

在 %USERPROFILE%\Documents\Vibelution\config\config.toml 配置模型与密钥（首次 Launcher 启动常会创建 starter 文件）
双击桌面 Vibelution Launcher，或：

powershell -ExecutionPolicy Bypass -File scripts/vibelution_launcher.ps1 -Action start

密钥只放外部配置或环境变量，不要提交进 git。

发布方可用 scripts/package_windows_release.ps1 打出 dist/release/windows/ 快照包（仍属 Phase 1：需本机 Python/Node）。

开发者路径

依赖：Python 3.11+（建议 3.12）、Node.js 18+（npm）、Git。Windows 若走桌面窗口，建议本机有 Edge。

git clone https://github.com/CCDawn/Vibelution.git
cd Vibelution

1. 用 launcher（推荐）

# Windows
powershell -ExecutionPolicy Bypass -File scripts/vibelution_launcher.ps1 -Action start

# macOS / Linux（不自动开浏览器）
python scripts/vibelution_launcher.py --action start --no-browser
# 本机打开 http://127.0.0.1:8000（以日志为准）

首次会检查系统依赖，缺 .venv / 前端依赖 / web/dist 时在项目内装齐或构建。缺 Python、Node 会直接报错停住。过程日志在 .runtime/launcher/launcher-control.log 和 logs/runtime_scenes/。之后启动只做指纹检查，能复用就复用。

正式路径以 npm / package-lock 为准；Bun 只是本地辅助，别为了它改锁文件策略。

2. 手动装 Python 依赖

python -m venv .venv
# Windows: .\.venv\Scripts\activate
# macOS / Linux: source .venv/bin/activate
pip install -r requirements.txt

3. 手动装前端依赖

cd web
npm install

如果本机已安装 Bun，可以在依赖已就绪后使用辅助脚本加快本地开发循环：

cd web
bun run bun:dev
bun run bun:test
bun run bun:build

4. 配置 LLM

运行配置统一存放在用户级外部路径（默认：%USERPROFILE%\Documents\Vibelution\config\config.toml）。新环境通过 Launcher 首次启动时会自动创建该目录和 starter 文件；也可以设置 VIBELUTION_CONFIG_HOME 或 VIBELUTION_CONFIG_PATH 指向其他外部配置位置。

[runtime]
profile = "safe_remote"
preflight_doctor = true
require_venv = true

[llm.model_library.openai_gpt_4_1]
model = "gpt-4.1"
label = "OpenAI GPT-4.1"
api_key_env = "VIBELUTION_LLM_MODEL_OPENAI_GPT_4_1_API_KEY"
transport = "chat_completions"
contract = "tool_chat"
temperature = 0.7
max_output_tokens = 8192
timeout = 120
streaming = true

[llm.model_library.openai_gpt_4_1.provider]
kind = "openai"
api_key_env = "OPENAI_API_KEY"
base_url = "https://api.openai.com/v1"
compat_mode = "openai"
requires_api_key = true

示例环境变量：

$env:OPENAI_API_KEY="your-api-key"
$env:DEEPSEEK_API_KEY="your-api-key"
$env:MINIMAX_API_KEY="your-api-key"

外部 config.toml 不在仓库里，别提交真实密钥。上面示例只有环境变量名。

问题与讨论：Issues · Discussions · 贡献见 CONTRIBUTING.md · 版本 CHANGELOG.md / VERSION

Agent 开发

给 coding agent / 维护者看的路由说明（最终用户可跳过；细则在 docs/standards/）：

docs/guides/README.md — 加载顺序
docs/guides/route.md — 任务类型 → READ / EDIT / TEST
docs/guides/ownership.md — 写入落点
docs/guides/loop.md — 分级 / 命令 / 完成报告块

全局红线：AGENTS.md。

本地任务闭环

首次在本仓库开发时配置 tracked pre-commit hook。scripts/doctor.ps1 只读检查环境与 core.hooksPath；如果配置不匹配，它只在输出中提示下面的修复命令，不会静默改写 Git 配置。

日常提交时，hook 自动调用 local_quality_gate.py commit，以 staged paths 驱动快速检查：diff check 与 Python Ruff 读取 Git index 中的 staged 内容。它不是对 unstaged worktree 的完全隔离；gate-definition 文件会额外检查同一路径是否同时存在 staged 与 unstaged 改动，且 gate-definition staged 时会在当前 worktree 运行 focused self-test，因此未 stage 的测试或 conftest.py 也可能影响结果。任务内容全部提交、task worktree clean 后，在该 task worktree 运行 closeout 和 manifest 复核：

git config core.hooksPath .githooks
$claimId = $env:VIBELUTION_CLAIM_ID
if ([string]::IsNullOrWhiteSpace($claimId)) { throw "Set VIBELUTION_CLAIM_ID first." }
powershell -ExecutionPolicy Bypass -File scripts/doctor.ps1 -Json
& .\.venv\Scripts\python.exe scripts/local_quality_gate.py closeout --base main --claim-id $claimId
$taskId = (git branch --show-current).Replace("codex/", "")
& .\.venv\Scripts\python.exe scripts/local_quality_gate.py verify-manifest --manifest ".runtime/quality_gates/$taskId.json" --base main

closeout 绑定本任务 claim、当前本地 main SHA、task HEAD SHA、影响面 selector 命令、fast-forward ancestry 与 merge preflight。verify-manifest 会在合并前重查 branch/worktree/HEAD/changed files、active claim、clean 状态、checks 与 commands，而不只复核 schema 和 SHA。manifest 的 outcome=passed 只表示这些当前授权证据通过，不代表任务已经 merge；进入 root local main 前仍须确认 root clean，并只用 git merge --ff-only <task-branch>。如果得到 stale_main、claim_conflict、dirty_worktree 或合并冲突，按 tests/README.md 的 outcome matrix 回 task worktree 修复并重新运行 closeout。

质量门不会执行 merge、release 或删除。fast-forward 后在 root main 做最小 post-merge verification，再由任务拥有者只释放本任务 claim，并只移除本任务创建的 junction（如有）、worktree 与 branch；不得清理其他未完成任务。远端 push、PR 和 CI workflow_dispatch 是可选发布/远端验证步骤，不属于默认本地闭环。

启动方式

Web Workbench

统一 launcher 入口：

# Windows
powershell -ExecutionPolicy Bypass -File scripts/vibelution_launcher.ps1 -Action start

# macOS/Linux headless adapter
python scripts/vibelution_launcher.py --action start --no-browser

后端与静态前端入口：

python scripts/web_workbench.py --reload

默认监听 http://127.0.0.1:8000，并保持无浏览器窗口；桌面入口和 launcher 负责打开托管窗口。调试时如果确实要打开系统默认浏览器，可显式追加 --open-browser。如果只跑前端开发服务器：

cd web
npm run dev

Vite 默认监听 http://127.0.0.1:5173，并把 /api 代理到本地后端。

本地前端调试也可以使用 bun run bun:dev，但不要因此提交 bun.lock/bun.lockb，除非本轮明确迁移包管理器。

统一 Agent 入口

python agent.py

常用 headless / 单轮执行：

python agent.py --auto
python agent.py --mode chat --prompt "分析当前仓库结构" --single-turn
python agent.py --mode self_evolution --prompt "检查最近变更的回归风险"

监督进化 CLI

python agent.py --list-datasets
python agent.py --choose-dataset
python agent.py --supervised-evolution --bundle supervised_evolution_dry_run_v1
python agent.py --dataset custom_prompt_jsonl --dataset-limit 20
python agent.py --supervised-dashboard

Web 工作台页面

路由	作用
`/chat`	对话式编码工作台：会话列表、消息流、运行侧栏与输入区。
`/teams`	团队与科研流程：挑战杯单页运行态画布、人工门禁与 Inspector。
`/agents`	Agent 管理：注册表、配置、工具与技能边界。
`/memory`	知识库与记忆治理入口（含图谱等子视图）。
`/git`	仓库局势页：变化文件、diff、最近提交、手动提交和 AI commit message。
`/self-evolution`	自进化现场：readiness、事务历史、fitness、审计与回滚。
`/supervised-evolution`	监督进化控制台：dataset / bundle 运行与进度。
`/supervised-evolution/runs`	监督运行记录。
`/supervised-evolution/library`	Proposal library 与待推进建议。
`/supervised-evolution/review`	对话样本审核面。
`/logs`	Runtime scene 与日志观察。
`/config`	模型库、全局运行项与高级配置检查。
`/kernel`	Kernel 任务中心。
`/reset`	受保护的本地清理入口。
`/pet`	长期陪伴体状态入口。

自进化与监督进化边界

Self Evolution

自进化负责在当前仓库中执行一轮有界改进。它关注：

当前目标和 readiness
Git working tree 信号
演化事务与 fitness 摘要
工具调用、验证、审计尾迹
回滚 manifest 与冲突说明

自进化不是无限后台任务。每轮都应有目标、证据、验证和停止条件。

Supervised Evolution

监督进化负责用评测样本比较 baseline 与 candidate，并把结果沉淀成可审核的 proposal / advisory baseline。它关注：

dataset / bundle materialization
baseline / candidate 对比
decision record 与 lineage
proposal lifecycle
active advisory baseline
chat case review

active advisory baseline 是建议和治理语义，不代表系统会自动把新能力重写进 runtime。

测试与验证

Python：

pytest tests -q

常用局部验证：

pytest tests/test_web_app.py -q
pytest tests/test_git_status_service.py -q
pytest tests/test_supervised_evolution.py -q

前端：

cd web
npm run test
npm run build

Bun 辅助验证：

cd web
bun run bun:test
bun run bun:build

CI 通常覆盖：

Windows Python 3.11 / 3.12
Python compile 与 pytest
变更文件 ruff check
前端 npm ci、npm run test、npm run build

隐私与安全

默认当本地 workbench 用；写接口有本机 control token 和来源校验。
截图是脱敏演示，不是某台机器的真实状态。
外部 config.toml 里的密钥、私有 provider 地址、个人绝对路径不要提交。
Git 页只提交你勾选的文件；还有未选中的 staged 改动时后端会拒提。
Reset 走白名单，不能乱清任意路径。
Runtime scene 包里可能有敏感信息，外传前自己过一遍。
安全漏洞按 SECURITY.md 私下报，别在公开 issue 里贴利用细节。

许可证

MIT。贡献见 CONTRIBUTING.md。可选第三方组件说明见 THIRD_PARTY_COMPONENTS.md（默认不启用）。

进一步阅读

文档	作用
docs/product/README.md	产品定位
docs/README.md	文档地图
docs/standards/README.md	开发规范入口
INDEX.md	项目索引
docs/agents/domain.md	领域词
core/core_prompt/SOUL.md	行为边界
docs/standards/development-standard.md	交付标准

根目录若有 AGENTS.md，本仓库协作按它来。

Navigation Menu

Repository files navigation

Vibelution

界面预览

当前能力

运行模式

项目结构

快速开始

最终用户（Windows，推荐）

开发者路径

1. 用 launcher（推荐）

2. 手动装 Python 依赖

3. 手动装前端依赖

4. 配置 LLM

Agent 开发

本地任务闭环

启动方式

Web Workbench

统一 Agent 入口

监督进化 CLI

Web 工作台页面

自进化与监督进化边界

Self Evolution

Supervised Evolution

测试与验证

隐私与安全

许可证

进一步阅读

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 5,618 Commits
.githooks		.githooks
.github		.github
assets		assets
config		config
core		core
crates		crates
desktop/electron		desktop/electron
docs		docs
prompts/research		prompts/research
schemas		schemas
scripts		scripts
tests		tests
tools		tools
web		web
.coveragerc		.coveragerc
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DESIGN.md		DESIGN.md
INDEX.md		INDEX.md
LICENSE		LICENSE
PRODUCT.md		PRODUCT.md
README.md		README.md
SECURITY.md		SECURITY.md
THIRD_PARTY_COMPONENTS.md		THIRD_PARTY_COMPONENTS.md
VERSION		VERSION
agent.py		agent.py
opencode.jsonc		opencode.jsonc
pytest.ini		pytest.ini
requirements-research.txt		requirements-research.txt
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

Vibelution

界面预览

当前能力

运行模式

项目结构

快速开始

最终用户（Windows，推荐）

开发者路径

1. 用 launcher（推荐）

2. 手动装 Python 依赖

3. 手动装前端依赖

4. 配置 LLM

Agent 开发

本地任务闭环

启动方式

Web Workbench

统一 Agent 入口

监督进化 CLI

Web 工作台页面

自进化与监督进化边界

Self Evolution

Supervised Evolution

测试与验证

隐私与安全

许可证

进一步阅读

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages