- Python ≥ 3.10(本地开发用 CPython 3.14.3)
- uv(包管理器)——安装 uv
- 克隆本仓库(或直接使用当前目录)
git clone https://github.com/El1mir/Elixir.git cd elixir - 创建虚拟环境并安装依赖(uv 会自动按
pyproject.toml/uv.lock复现)uv sync
- 验证安装
uv run python -c "import elixir; print(elixir.__version__)"
Message 兼容 OpenAI Chat Completions 的文本和图片输入。纯文本调用保持不变;图片可以使用 SDK 类型,也可以直接使用 OpenAI part 字典:
from elixir import ImagePart, TextPart
user_content = [
TextPart("请描述这张图"),
ImagePart("https://example.com/photo.png", detail="high"),
]
async for sentence in session.start_turn(user_content):
print(sentence)图片 URL 支持 http(s) 和 base64 data:image/...。当前输入会在每次分析步骤中附带,最近历史轮中的图片也会随重水合恢复;rounds 记录同时保留 user_content,而 user 字段仍是用于展示的纯文本。
模型能力需要通过真实请求探测,而不是依据模型名猜测:
result = await llm.test_vision()
# result.supported / result.response / result.errorcheck_vision_capability() 是同一接口的语义化别名。探测使用内置最小图片,也可以传入自己的图片 URL 和提示词。
无外部服务依赖(LLM 用确定性 fake;真实 Provider 用 httpx.MockTransport 拦截)。一条命令跑全部:
uv run python -m unittest discover -s tests -t .贡献使开源社区成为一个学习、激励和创造的绝佳场所。你所做的任何贡献都非常感谢。
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
该项目使用 Git + uv 进行版本管理(pyproject.toml 的 version 为当前版本,当前 0.1.1)。
树形图已按
.gitignore排除忽略目录(.venv、docs、.scratch、.idea、elixir.egg-info) 及运行时生成目录(demo/data、demo/logs、__pycache__、dist)。 每行#后为该文件/目录的一句话用途。
elixir/ # 项目根
│
├── .github/ # GitHub Actions CI
│ └── workflows/
│ └── release.yml # push 到 main:测试 → uv build → 以 v<版本>-<短提交id> 为 tag 发 Release
│
├── elixir/ # SDK 源码包(主代码)
│ ├── __init__.py # 包出口:new_session / Session / Settings / 类型 / OpenAIProvider
│ ├── session.py # Session 运行时 + 装配:单 active 轮、打断令牌、轮初注入、三层工具合并、轮序落盘
│ ├── context.py # Live 会话上下文 SessionContext:K 轮窗口、round_id 分配、淘汰、重水合 restore
│ ├── driver.py # 双人设 function-calling 驱动循环:四控制函数 + 步数/自循环预算
│ ├── synthesizer.py # 第四者回复合成:分句符切流(字面转义容错)、逐句 yield
│ ├── roles.py # 心核 / 智核 / 合成默认提示词(宿主可经 role_prompt_overrides 整段覆盖)
│ ├── memory.py # 记忆器抽象 + LongTermMemory(日记/压缩/检索) + EmotionMemory(情绪流水)
│ ├── store.py # Store:内存真源 + 领域读写 + 定时/退出 flush + 重水合
│ ├── datasource.py # DataSourceProvider 持久后端抽象
│ ├── datasources/ # 数据源后端实现
│ │ ├── __init__.py # 数据源包标记
│ │ └── jsonl.py # jsonl 默认后端(每 session 一个追加文件)
│ ├── llm.py # LLMProvider 抽象:complete + stream_text
│ ├── providers/ # 真实厂商 Provider 适配器(OpenAI 官方 SDK)
│ │ ├── __init__.py # 适配器包标记
│ │ └── openai.py # OpenAI 兼容(官方 SDK:tools + 流式;disable_thinking 关推理思考)
│ ├── settings.py # Settings 全字段默认值(K/M/预算/情绪/打字节奏/分句/日志等)
│ ├── tools.py # 用户扩展 Tool 基类(schema + allowed_in 门控)
│ ├── logger.py # Logger 运行日志抽象 + StdLogger(stdlib 按天 .txt)
│ ├── types.py # 公共类型(Round/ToolSchema/ToolCall/AssistantMessage/Message 等)
│ └── exceptions.py # 会话级异常(ActiveTurnError / DuplicateToolError …)
│
├── demo/ # 最小行式 TUI 对话演示(独立于 SDK 打包;运行方式见 demo/README)
│ ├── chat.py # 入口:读环境变量 → 注入 demo 人设 → 建 Provider/Session → 逐句对话 → 退出 flush/close
│ ├── personas.py # demo 专属精简双核人设(经 Settings.role_prompt_overrides 注入,不写进框架)
│ ├── README.md # demo 的配置与运行说明
│ ├── run.ps1 # Windows 一键运行模板(密钥为占位,按需自填)
│ └── .env.example # 环境变量模板(密钥等,demo 不自动读取)
│
├── tests/ # 标准库 unittest 测试(无 pytest / 外部服务,LLM 用确定性 fake)
│ ├── __init__.py # 测试包标记
│ ├── fake_llm.py # 测试用 ScriptedLLM(脚本队列 + 逐次流文本)
│ ├── test_foundation.py # 01 工程地基:类型/Settings/Logger/Tool/异常
│ ├── test_store.py # 02 持久化:Store + jsonl 往返
│ ├── test_session_turn.py # 03 最小会话轮:驱动/合成/打字/预算/单 active
│ ├── test_interrupts.py # 04 打断语义:interject / force_stop
│ ├── test_memory.py # 05 记忆器框架 + EmotionMemory
│ ├── test_longterm.py # 07 LongTermMemory:压缩/日记/检索
│ ├── test_rehydration.py # 08 重水合与多会话隔离
│ ├── test_user_tools.py # 06 用户 Tool 三层合并与门控
│ ├── test_providers.py # 12 OpenAI Provider(官方 SDK + MockTransport,含 thinking 开关)
│ ├── test_demo.py # 13 demo 最小 TUI 离线冒烟(含运行日志落盘)
│ └── test_e2e.py # 09 端到端聚合回归网
│
├── pyproject.toml # 构建与依赖清单(uv 管理)
├── uv.lock # uv 锁定的依赖版本
├── README.md # 本文件
└── LICENSE # Apache-2.0 许可证全文
当前版本:0.1.1(与 pyproject.toml 的 version 一致;升版时同步修改)。
uv build # 产出 dist/elixir-0.1.1-py3-none-any.whl 与 .tar.gz
uv publish # 发布到 PyPI(需 UV_PUBLISH_TOKEN / PYPI_TOKEN,或按提示登录).github/workflows/release.yml:每次 push 到 main 自动执行:
uv run跑全部测试;uv build构建 PyPI 包(sdist + wheel);- 以
v<版本>-<短提交id>(如v0.1.1-689722c)为 tag 创建 GitHub Release,附件 =dist/*。
不能直接用完整
github.sha作 tag:GitHub 禁止纯 40/64 位十六进制的 tag 名。
CI 只把包发到 GitHub Release;发布到 PyPI 仍为手动
uv publish(如需 CI 自动推 PyPI:在仓库 Secrets 配好 token,并在工作流末尾加一步发布)。
升版步骤:改 pyproject.toml 的 version → uv lock 刷新 → 同步 elixir/__init__.py 与本 README 版本号 → push main 触发新 Release。
El1mir @ 2247335689@qq.com · GitHub
本项目采用 Apache License 2.0(见 LICENSE)。