MAGI

中文 | English

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

进入任意项目先跑 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 install

装完了，就这两条。magi init 建项目；magi install 把技能、协议和会话钩子装进你机器上每一个它探测到的 agent CLI（不问你，因为它们互不冲突）。

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

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

每天就这几件事

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

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

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

复核会花钱（一次外部模型调用）。magi review 事前会说要问谁、用哪个模型， 事后报本周用量；浏览器里按之前也会弹出同样的信息。周预算在 research.weekly_calls，用完了它拒绝启动而不是安静地少做。

🌟 项目展示

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 手动安装（备选）

# 一条命令管装和升级，幂等——已经是最新就什么都不做
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 .

2.3 可选外部工具

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

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

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）

8 个 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    # 全机可用（技能只在项目里有意义，慎用）

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

不是每个 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
magi install                 # 技能 + 协议块 + 收工闸门（装进它探测到的每个 CLI，不问）
magi pm init                 # 可选：任务追踪。它把这个目录交给 bd —— 会 git-init、
                             # 并用你自己的 git 身份提交。跑之前它会说清楚并问你

magi sync --fix              # 同步率 + 三核状态，并把能自动修的都跑掉

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 init，修复是 magi lint --fix，建图是 magi graph build，语义连边是 magi link，查手册是 magi guide。样板（工具能力、 谁能问人、无人值守怎么办）只在 AGENTS.md 的托管块里写一次。

跨项目检索

magi search 默认只搜你现在这个项目。 想读别的，得说一声。

早先它默认就跨项目去搜，结果是:人搜自己十分钟前写的笔记,拿回一整页别人项目的 研究——因为每次 magi init 都会把自己注册进去，而注册表里那个「可搜索」开关是 全机一份的，于是这份跨项目清单自己长大，没有人选过它。

现在拆成两个问题、两个家：

magi kb list                     # 这台机器上都注册了哪些项目
magi kb disable <name>           # 这个项目不允许被别处读到（enable 恢复）
magi search "..."                # 默认：只搜本项目
magi search "..." --scope all    # 加上本项目 research.search_projects 点名的那些
                                 # （一个都没点名时 = 所有 enable 的）
magi search "..." --kb <name>    # 定向搜某一个

• enable / disable（注册表，全机）——这个项目允不允许被别处读到。
• research.search_projects（项目自己的 config.yaml）——本项目读哪几个。

默认只搜本项目，但结果末尾会点名还有哪些可读，所以别的项目不会因此消失。 magi kb register <path> 手动注册任意项目，unregister 只移除注册项、不动文件。WebUI 里点开带 [kb:名称] 标记的命中，卡片照样就地展开、公式插图照样渲染——预览请求带着来源项目名走，不用先切过去。

检索小抄：--path 'raw/papers/2026-*<slug>*' 可把语义检索限定在某一篇论文里；中英文问题都支持（中文经 CJK 二元组分词进 BM25，向量侧由嵌入模型天然跨语言）。

写作与引用（drafts/ + magi bib）

草稿是项目一等公民：放在 drafts/，被 magi index 收进检索（collection drafts），但不进图谱、不计同步率。引用直接从参考卡导出：

magi bib pretko-2020            # 参考卡 frontmatter → BibTeX 条目
magi bib --all -o drafts/refs.bib
magi bib pretko-2020 --fetch    # 有 arxiv_id 时拉取 arXiv 官方 BibTeX

magi ingest tex 会把源码包里的 .bib/.bbl 原样保留在 markdown 旁边（raw/papers/<slug>.bib），文件名里的 arXiv ID 也会写入 frontmatter arxiv_id: 供雷达识别。完整写作流程见 draft skill。

关于 claims 的边界：magi verify 的 verified 意为引文存在性验证（引文确实逐字出现在来源里，含空白/连字/全角标点鲁棒匹配）——它不判断命题与引文在语义上是否一致，那一层由 LLM/人工审查负责（magi claims verify 是同一命令的别名）。

文献雷达（magi radar）

项目 config.yaml 的 radar: 段配置 arXiv 分类、种子论文与我方论文后：

magi radar harvest              # 手动收割：S2 推荐 ∪ arXiv 新文 → inbox/radar/日期-digest.md
                                # （候选按"与本项目嵌入质心的余弦相关度"排序并标注 relevance 分；
                                #   config 里 radar.min_relevance 可设过滤阈值）
magi radar install-schedule     # 注册每日定时收割（Windows 任务计划程序 / macOS launchd；--uninstall 卸载）
magi radar citation-gap         # 侦察"该引我方论文却未引"的近期文献（四层漏斗，人工审核队列）

夜间确定性收割 + 下次会话由 radar_review skill 做 LLM triage——magi sync 会提示待审摘要。

本地 WebUI 看板（magi ui）

MAGI 内置了基于 Claude 纸墨美学的零构建本地轻量看板（FastAPI + 原生 SPA），用于直观查看三核状态、执行维护与检索实验：

magi ui                       # 启动并在默认浏览器中打开本地看板（默认 http://127.0.0.1:8737，占用时自动探测 8738-8746）
magi ui --port 8080 --no-open # 自定义端口且不自启浏览器

包含 7 大面板：Dashboard（你该看的两件事：等你拍板的决定和每条线现在在哪，外加一个「想到什么就写在这」的框直接写进 inbox/notes.md、一段回头看给你的预测命中率；再往下才是同步率、一键修复建议、注册项目和 config.yaml 关键字段）、Melchior（Threads 与单条论坛视图、时间线、认知网络/Claims/图谱 SQL/文献 BibTeX 复制/草稿；图上现在也画 threads/，可以只看知识、只看研究状态或缩到骨架）、Balthasar（Beads 任务）、Casper（混合检索实验台：联邦/集合/路径过滤）、Radar（简报阅读 + 审阅动作：标已审/收入 inbox/建阅读任务）、Operations & Danger Zone（服务端操作白名单 + 输入操作 ID 确认 + SSE 实时终端，任务历史落盘）与内置文档。API 与 --json 契约逐字段一致。

顶栏的 ⚡ MAGI MODE 可一键切换 EVA/NERV 战术主题：三贤者三体阵列 HUD（MELCHIOR·1 / BALTHASAR·2 / CASPER·3 实时状态 + 同调率）、CRT 扫描线、蜂窝网格、警示条纹 Danger Zone 与启动同步序列。看板仅监听 127.0.0.1，带 Host 白名单防护，不发送任何 CORS 头。

5. 从 Wikify 迁移（老用户指引）

MAGI 是 Wikify 的全面重构：脚本集升级为统一 CLI，任务状态外接 Beads，新增混合检索、claim 溯源与文献雷达。你的数据完全兼容——raw/、wiki/、inbox/ 格式未变。

5.1 迁移步骤（三条命令）

# 1. 一键安装新版（§2.1 的脚本；magi setup 会顺带检测旧版拷贝并提示）
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/Misaka16384/magi/main/install.ps1 | iex"

# 2. 删除旧安装拷贝（旧 SKILL.md 会误导 agent 调用已不存在的脚本路径）
magi setup --remove-legacy

# 3. 在 Hub 根目录先看一眼，再跑：
cd <你的KnowledgeHub>
magi migrate --dry-run   # 说清会改什么，一个字节都不写
magi migrate
#    ↳ 逐个项目补齐 CLAUDE.md / AGENTS.md / config.yaml / scratch/（沿用 config.md
#      里的旧标题与 scope）、把旧 config.yaml 里的 token/模型/阈值搬过来，重建
#      graph.db（新增 claims/evidence 表）与 _index.md。raw/ 与 wiki/ 的字节不
#      改写；唯一会动的是 wiki/theses/*.md——它们被移进 drafts/，重名的留在
#      原地并报出来，什么都不会删。
#      随后自动 magi pm init + 每个项目的 magi sync --fix（建索引、同步积压）。
#      --minimal 只迁移不收尾；在单个项目目录里跑则只迁移那一个。

# 收尾：各项目跑 `magi install`（技能 + 协议 + 闸门）、`magi index`、`magi sync` 验收。
# 迁移后 hub 自己的 wikis.json / topics/ / log.md 就不起作用了，想删随时删。

5.2 变化对照

6. Obsidian 集成

在 Obsidian 中直接打开具体的项目目录（不要打开 Hub 根目录）。在 设置 → 档案与链接 → 排除档案 中添加两条正则，让图谱只显示纯粹的知识卡片：

/(?:^|/)(?:_index|log|config|uncompiled-source-coverage|CLAUDE|AGENTS)\.md$/

/^\..*|(?:^|/)(?:scratch|inbox|raw|output|vendor)(?:/|$)/

7. 开发

git clone https://github.com/Misaka16384/magi.git ; cd magi
uv venv && uv pip install -e .
.venv\Scripts\python.exe tests\smoke_test.py     # 端到端冒烟（含回归锁）