magi

MAGI

中文 | English

MAGI 是一个 agent-native 的科研工作环境：人是驾驶员，LLM agent 是机体，确定性的 magi CLI 是拘束具——三者同步率越高，科研越快。它把学术论文（PDF/LaTeX）摄入、编译为 Obsidian 兼容的概念卡片项目，并用三核架构管理完整的科研状态：

核	状态	由谁承载	回答的问题
MELCHIOR	认知状态（知识）	概念/文献卡片 + SQLite 知识图谱 + claim/证据溯源	我们知道什么？为什么可信？
BALTHASAR	意图状态（研究）	threads/ 里的命题、问题、研究线 + decisions.md（机械任务另有 Beads）	我们在做什么？下一步是什么？
CASPER	检索状态	本地混合检索（FTS5 BM25 + sqlite-vec 向量 + RRF）	此刻该读什么？

进入任意项目先跑 magi sync——它输出同步率、三核状态和逐条可执行的修复提示。magi radar 是文献雷达：定时发现相关新论文，并侦察"知识上应引用我方论文却未引用"的候选。同一份 skills 通吃 Claude Code / Codex / Antigravity / opencode 等 CLI agent 宿主——magi install 会把它们放到各家各自找的地方。

任何命令的完整语法：magi <command> --help；全景：magi --help。

---

先跑起来

pipx upgrade --install magi-research           # 装或升级，重复跑没副作用
mkdir my-topic ; cd my-topic ; magi init
magi ingest url 2609.14858 --go                # 可选：带一篇种子论文进来（arXiv 号或 DOI），一条命令落进 raw/

装完了。magi init 一步做完：建项目，并把技能、协议和会话钩子装进你机器上每一个它探测到的 agent CLI（不问你，因为它们互不冲突）。之后装了新的 agent CLI，再跑一次 magi install 即可。

然后在那个目录里打开你的 agent，把你想做的事说出来——「摄入 inbox 里的论文」「把待编译的都编译了」「我接下来该做什么」。技能会按描述自己加载，你不用记住任何一个。

在终端里，magi next 问的是同一个问题，但它从 note 里派生答案而不是问模型。magi guide 是完整手册。其余的——摄入、检索、图谱、WebUI——都在下面第 3 节，而 magi --help 一屏放得下。

---

每天就这几件事

整套系统是一个环。终端和浏览器都能走完，任何一步都不必换到另一边。

你要做的	终端	浏览器（magi ui）
我现在该干嘛	magi next	首页顶部
开一条命题 / 问题 / 研究线	magi thread new <slug> --kind proposition --title … --purpose …	笔记页「开一条新的」
有进展了	magi thread post <slug> --text …	笔记面板的输入框
结论变了	magi thread status <slug> supported --text …	面板上的状态按钮
这是我拍的板	magi decide --about <slug> --text …	「记下这是我的决定」
让别人复核	magi review <slug>	「找人复核这条」
收一篇论文	丢进 inbox/，再 magi ingest auto	摄入页「收下这些」
找东西	magi search "…"	检索页
这条线做完了	magi close <line> --text …	「结束这条线」
写完了，发表	magi publish <稿子> --line <line>	「发表并归档」
收工	magi sync --close	面板底部「收工检查」

只有两条是必须记住的：magi next 问下一步，magi sync --close 收工。 其余的它会在你需要的时候告诉你——包括完整的命令行。

装了 skills 之后更省事：在 agent 里直接说「我接下来该做什么」「把这篇收进来」 「这条我觉得站不住」，它会自己去调上面这些。

复核会花钱（一次外部模型调用）。magi review 事前会说要问谁、用哪个模型、 哪一档，事后报本周次数；浏览器里按之前也会弹出同样的信息。没有周预算—— 调用只记在 output/llm-ledger.jsonl 里，唯一会拒绝的是总开关 research.llm_calls: false。

---

🌟 项目展示

MAGI MODE —— WebUI 战术主题

magi ui 打开本地网页控制台（默认 http://127.0.0.1:8737），自带三套主题：Institute 浅色 / 深色，以及压轴的 EVA「MAGI MODE」——一整套 NERV 驾驶舱视觉系统，分红·战斗配置与蓝·静默值守两个警戒态：

红·战斗配置：三贤者 HUD、全屏 EVA 背景画、液态玻璃面板、视口边缘琥珀呼吸光。

蓝·静默值守：同一套 HUD 的真·浅色模式——白霜玻璃、深青墨水、青色边缘光。

iOS 材质液态玻璃：背景画透过每一块面板仍保持文字可读；右下角 ◐ 校准器实时调节模糊 / 不透明度 / CRT 扫描线。

Obsidian 式力导向知识图谱：拖拽布局、滚轮缩放、悬停邻域聚焦、点击节点直接读卡片，未解析的 wikilink 渲染为幽灵节点。

点图谱里的任一节点，或检索结果里的任一条，卡片就地展开：公式由 KaTeX 排版、[[链接]] 可点、插图与 mermaid 图跟着一起画，左边正文右边目录与出入链。检索命中会直接滚到匹配的那一段。

◐ 校准器：模糊、不透明度、CRT 扫描线三个滑杆当场生效；下半是背景画选择器——点缩略图钉住你要的那几张，不选就按窗口比例自动轮换。

• 深浅切换与 MAGI MODE 独立作用：浅色基底 → 蓝态，深色基底 → 红态，模式内 ☀︎/☽ 直接切换警戒态
• 背景画默认按屏幕宽高比选图、切页随机轮换、平滑交叉淡入；也可以在 ◐ 面板的缩略图里钉住某一张或几张；把自己的图放进 ~/.config/magi/ui-backgrounds/{blue,red}/ 即可替换整套艺术
• 全部动画尊重 prefers-reduced-motion；界面中英双语一键切换

项目成品

自动生成的密集语义图谱，展示物理与数学概念。

从排版混乱的 PDF 编译出的整洁文献卡片。

从 LaTeX 源码提取并格式化的数学证明与引理。

---

1. 架构：CLI、Skills 与宿主的分工

你（驾驶员）
  └─ Claude Code / Codex / Antigravity / opencode（机体：负责推理、写作、判断）
       ├─ skills（随 CLI 分发）—— 教 agent「何时、为何」执行各条流水线
       └─ magi CLI（拘束具）  —— 所有确定性操作：摄入、图谱、检索、校验、任务、雷达
            └─ 持久状态在文件与数据库里：raw/ wiki/ output/ .beads/

• CLI 负责语法且自描述（--help）；skills 只讲方法论，不复制参数清单。
• 持久状态永远落盘；agent 的上下文是一次性的（fresh-context worker 模式）。
• JSON 输出（--json）的形状即未来 magi mcp 的工具契约。

---

2. 安装

2.1 一键安装（推荐）

Windows（PowerShell）：

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/Misaka16384/magi/main/install.ps1 | iex"

macOS / Linux：

curl -LsSf https://raw.githubusercontent.com/Misaka16384/magi/main/install.sh | sh

脚本会自动完成：装 uv（如缺）→ 从 PyPI 安装 magi-research（自带 Python，无需预装）→ 执行 magi setup：安装 Beads（bd）、拉取 Ollama 嵌入模型（如 Ollama 在场）、注册 Claude Code plugin（如 claude 在场）、报告检测到的 agent CLI、检测旧版 Wikify 残留 → 输出环境体检表。幂等，重跑即升级。

随时体检环境：

magi setup --check

magi setup 的可选开关：--no-beads / --no-models / --no-plugin / --no-skills（不报告 agent CLI）/ --remove-legacy（删除检测到的旧版拷贝）。

体检表最后四行是你机器上的 agent CLI（claude / codex / agy / opencode）：装没装、当前项目各装了几个技能。magi setup 不会替你安装技能——技能是按项目装的，见 §2.4。

只想要经典 Wikify 体验（纯知识库，不要任务管理）？ 用 magi setup --kb-only：跳过 Beads 安装，magi sync 不再提示任务相关内容（BALTHASAR 核显示 disabled 且不计入同步率）。随时 magi setup --full 恢复完整体验。雷达等其余功能均为按需调用，不用即无感。

2.2 手动安装（备选）

CLI（pipx 优先；没有 Python 3.10+ 就用 uv，它自带一个。装完之后 MAGI 再也不会调用它们）：

# 一条命令管装和升级，幂等——已经是最新就什么都不做
pipx upgrade --install magi-research    # 需要机器上已有 Python 3.10+
                                        # （--install 需要 pipx ≥ 1.5；更老的版本用
                                        #   pipx install magi-research 首装、
                                        #   pipx upgrade magi-research 升级）

# 备选：uv，自带 Python 3.12，同样一条命令管装和升级
uv tool install --force magi-research

# 尝鲜未发布的改动: uv tool install --force git+https://github.com/Misaka16384/magi
# 本地开发: git clone … && cd magi && uv tool install .

Beads：Windows 用 irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex，macOS/Linux 见官方文档。没有 bd 时 MAGI 优雅降级。

Ollama 模型：ollama pull qwen3-embedding:0.6b（向量检索）；ollama pull glm-ocr:q8_0（本地 OCR，可选）。不用自己 ollama serve——本机 Ollama 只是没启动的话，MAGI 第一次用到它时会拉起来（每进程试一次；config.yaml 的 ollama.autostart 默认开，环境变量 MAGI_NO_OLLAMA_AUTOSTART 可关）。真没装、或配的是连不上的远端地址，检索才降级成 BM25-only。

2.3 可选外部工具

一个都不装，MAGI 也能跑。 每个只解锁一项具体功能，缺了不是故障——magi setup --check 不会把它们标红。

直接运行 magi setup，它会逐个问你要不要，并给出官网地址；说「不要」的以后就不再提。想重新选：magi setup --optionals。

工具	解锁什么	官网
Ollama	语义（向量）检索、本地离线 OCR	https://ollama.com/download
Pandoc	LaTeX 与 arXiv-HTML 摄入路线（保真度最高的两条）	https://pandoc.org/installing.html
Poppler（pdftoppm）	本地 OCR 渲染 PDF 页面（配合 Ollama）	https://poppler.freedesktop.org/
pdflatex	公式深度校验（真去编译一遍）；缺失时回退 pylatexenc 轻量校验	https://www.tug.org/texlive/
MinerU（云服务，非本地程序）	云端 PDF 转换，版面与公式识别强	https://mineru.net/

pandoc-crossref 是可选的（缺了只是交叉引用降级，不影响转换）。从源码仓库装的话，Windows 版已放在 vendor/windows/——加入 PATH，或在 config.yaml 的 tools.pandoc_crossref_path 指定。用 pipx / uv 装的话它不在包里（一个 19MB 的 Windows 二进制不该发给所有平台），需要时从 https://github.com/lierdakil/pandoc-crossref/releases 自取。MinerU 的 token 填在项目 config.yaml 的 ocr.mineru_api_token。

（历史依赖 ripgrep 已不再需要。）

2.4 Skills 安装（教 agent 用 MAGI）

12 个 skill 随 CLI 一起分发（magi/skills/*/SKILL.md，在 wheel 里），在项目里一条命令装进你机器上所有 agent CLI，不需要 clone 仓库：

cd <你的项目>
magi skills install                   # 默认装进当前项目（推荐），会列出检测到的 CLI 让你选
magi skills install --host codex      # 指定一个，跳过询问
magi skills install --host auto       # 检测到的全装
magi skills where                     # 每个 CLI 从哪读、装了几个、怎么触发
magi skills install --scope global    # 全机可用（技能只在项目里有意义，慎用）

默认不装全局：这些技能是围着某个研究项目转的，装进项目还能随仓库分发给同事。

宿主	全局位置	项目位置	怎么触发
Claude Code	~/.claude/skills/	.claude/skills/	/技能名（插件方式为 /magi:技能名），也按描述自动触发
Codex	~/.agents/skills/（外加 ~/.codex/skills/）	<仓库根>/.agents/skills/	$技能名，或按描述自选
Antigravity（agy）	~/.gemini/config/skills/	<仓库根>/.agents/skills/	按描述自动触发；/skills 浏览
opencode	~/.config/opencode/{commands,skills}/	.opencode/{commands,skills}/	/技能名（commands）+ 按描述自动触发（skills），两者都装

不是每个 CLI 都有斜杠命令（Codex 用 $，agy 只按描述触发）。到哪都好使的用法是直接说需求：「摄入 inbox 里的论文」。.agents/skills/ 是 Codex 和 agy 共读的跨 agent 约定，装一份两家都认；opencode 走自己的 .opencode/{commands,skills}/，安装器会另外给它写。

Claude Code 插件路线（一键脚本已自动执行，与上面的安装可共存）：

claude plugin marketplace add Misaka16384/magi && claude plugin install magi

---

3. 快速上手（5 分钟）

mkdir quantum-toys ; cd quantum-toys
magi init --name "Quantum Toys" --scope "玩具模型中的量子现象"
# ↑ 生成 raw/ wiki/ threads/ drafts/ decisions.md、AGENTS.md（托管块）、config.yaml，
#   并把技能 + 协议块 + 收工闸门装进它探测到的每个 CLI（不问）
magi next                    # 从这里开始，它告诉你下一步：inbox/ 里有文件、队列里有链接，它都看得见

# 可选：任务追踪。`magi pm init` 把这个目录交给 bd —— 会 git-init、并用你自己的
# git 身份提交；跑之前它会说清楚并问你。不装也不影响其余任何功能。

MAGI SYSTEM ONLINE — sync ratio 59.2%
|- MELCHIOR  (knowledge)  0 concepts · 0 refs · graph empty-wiki · backlog 1
|- BALTHASAR (intent)     2 lines · 1 open · 1 waiting on you · 1 unrecorded
`- CASPER    (retrieval)  index missing · 0 chunks · vectors 0/0
  -> 1 source(s) in raw/ are not compiled yet — run the compile skill
  -> magi index   # build the retrieval index

BALTHASAR 报的是研究状态，不是杂活。 1 waiting on you 是只有人能做的决定；1 unrecorded 是发生了但没人记下来的事——那是记账债，它下面每一个数字都是从当前错误的 note 算出来的，所以 magi next 把它排在第一。这个分数量的是记账干净度不是进度：六条开着的命题、零欠账，完全健康。

同步率随三核就绪程度浮动。照着 hints 逐条执行即可；新项目数字低不是配置错了。

然后把 PDF / LaTeX / 笔记丢进 inbox/，在你的 agent 里说一句"摄入 inbox 里的论文"（或直接 /magi:ingest），流水线就开始了。

📖 完整使用指南随 CLI 分发，三个入口读同一份内容：

magi guide                                # 列出十二章
magi guide ingest                         # 读某一章
magi guide --search "no project found"    # 把报错原文贴进去
magi guide --symptoms                     # 全书「症状 → 原因 → 修法」索引

或 magi ui → 文档与指引 → 使用指南（带章节导航），也可直接读 guide.zh.md。按使用场景分十二章（先跑通 / 安装 / 迁移 / 建库 / 摄入 / 编译 / 图谱调优 / 检索 / 写作 / 雷达 / 看板 / 疑难速查），每一步都写清了预期效果和不达预期怎么办。卡住时让 agent 跑 magi guide --search "<报错>"——手册随 CLI 一起装，不用联网。

---

4. 研究生命周期（skills 总览）

在 agent 聊天框里以斜杠命令触发（Claude Code plugin 下带 magi: 前缀），或直接用自然语言描述需求：

阶段	Skill	作用
入口	magi	跑 magi next，照它说的做；见到 skill 名就调。不知道该干什么时先调它
摄入	ingest	PDF/LaTeX/链接/DOI/引文 → raw/。按阶梯自动选路：arXiv HTML → LaTeX 源码 → PDF 文本层 → MinerU 云端 → 本地 OCR。原生视觉转录不在阶梯上——按页计费、烧过用户一整周额度，只在你看过页数并明确同意后才走
编译	compile	raw 文献 → 文献卡 + 概念卡；顺带把太稀的卡片补挖成该有的密度
整理	tidy	修机械流程修不了的：转换弄坏的公式、长歪的标签体系、其实是同一个的两张概念卡
问答	ask	混合检索 + 图遍历 + 严格引用；检索不到就说检索不到，不从记忆里编
调研	research	多角度并行调研并核验，产物是 threads/ 里的命题 +（至多）一篇综述。找茬式审计是同一个 skill 换一套提示词，不是另一个 skill
写作	draft	在 drafts/ 里写：检索取证 → magi bib 导出引用 → 校验 claim / 公式 / 链接
雷达	radar_review	对 radar 摘要做 triage：分数只是排序不是判据，判断在你