Metadata-Version: 2.4
Name: magi-research
Version: 2.0.0
Summary: MAGI: agent-native research workspace — knowledge base, retrieval, and literature radar for CLI agents
Author: Misaka16384
License-Expression: MIT
Project-URL: Homepage, https://github.com/Misaka16384/magi
Project-URL: Repository, https://github.com/Misaka16384/magi
Project-URL: Issues, https://github.com/Misaka16384/magi/issues
Project-URL: Changelog, https://github.com/Misaka16384/magi/releases
Keywords: research,knowledge-base,agent,cli,retrieval,rag,literature,obsidian,academic,wiki
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: filelock>=3.12.0
Requires-Dist: requests>=2.28.0
Requires-Dist: pillow>=9.0.0
Requires-Dist: pymupdf>=1.22.0
Requires-Dist: rich>=13.0.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pylatexenc>=2.10
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.22.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: httpx2>=2.0; extra == "test"
Provides-Extra: textlayer
Requires-Dist: pymupdf4llm>=0.0.17; extra == "textlayer"
Requires-Dist: onnxruntime>=1.18; extra == "textlayer"
Dynamic: license-file

# MAGI

*[中文](README.md) | [English](README_en.md)*

[![PyPI](https://img.shields.io/pypi/v/magi-research?label=PyPI)](https://pypi.org/project/magi-research/)
[![下载量](https://static.pepy.tech/personalized-badge/magi-research?period=month&units=abbreviation&left_color=grey&right_color=blue&left_text=downloads/month)](https://pepy.tech/project/magi-research)
[![Python](https://img.shields.io/pypi/pyversions/magi-research)](https://pypi.org/project/magi-research/)
[![License](https://img.shields.io/pypi/l/magi-research)](LICENSE)

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

| 核 | 状态 | 由谁承载 | 回答的问题 |
|---|---|---|---|
| **MELCHIOR** | 认知状态（知识） | 概念/文献卡片 + SQLite 知识图谱 + claim/证据溯源 | 我们知道什么？为什么可信？ |
| **BALTHASAR** | 意图状态（研究） | `threads/` 里的命题、问题、研究线 + `decisions.md`（机械任务另有 [Beads](https://github.com/gastownhall/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`。

---

## 先跑起来

```powershell
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 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` 事前会说要问谁、用哪个模型，
> 事后报本周用量；浏览器里按之前也会弹出同样的信息。周预算在
> `research.weekly_calls`，用完了它拒绝启动而不是安静地少做。

---

## 🌟 项目展示

### MAGI MODE —— WebUI 战术主题

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

![MAGI MODE · 红·战斗配置](https://raw.githubusercontent.com/Misaka16384/magi/main/docs/webui-magi-red.jpg)
*红·战斗配置：三贤者 HUD、全屏 EVA 背景画、液态玻璃面板、视口边缘琥珀呼吸光。*

![MAGI MODE · 蓝·静默值守](https://raw.githubusercontent.com/Misaka16384/magi/main/docs/webui-magi-blue.jpg)
*蓝·静默值守：同一套 HUD 的真·浅色模式——白霜玻璃、深青墨水、青色边缘光。*

![液态玻璃](https://raw.githubusercontent.com/Misaka16384/magi/main/docs/webui-glass.jpg)
*iOS 材质液态玻璃：背景画透过每一块面板仍保持文字可读；右下角 ◐ 校准器实时调节模糊 / 不透明度 / CRT 扫描线。*

![知识图谱视图](https://raw.githubusercontent.com/Misaka16384/magi/main/docs/webui-graph.jpg)
*Obsidian 式力导向知识图谱：拖拽布局、滚轮缩放、悬停邻域聚焦、点击节点直接读卡片，未解析的 wikilink 渲染为幽灵节点。*

![卡片预览](https://raw.githubusercontent.com/Misaka16384/magi/main/docs/webui-preview.jpg)
*点图谱里的任一节点，或检索结果里的任一条，卡片就地展开：公式由 KaTeX 排版、`[[链接]]` 可点、插图与 mermaid 图跟着一起画，左边正文右边目录与出入链。检索命中会直接滚到匹配的那一段。*

<img src="https://raw.githubusercontent.com/Misaka16384/magi/main/docs/webui-tuner.jpg" width="340" alt="◐ 材质校准器">

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

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

### 项目成品

![知识图谱可视化](https://raw.githubusercontent.com/Misaka16384/magi/main/graph.png)
*自动生成的密集语义图谱，展示物理与数学概念。*

![编译出的文献卡片](https://raw.githubusercontent.com/Misaka16384/magi/main/note1.png)
*从排版混乱的 PDF 编译出的整洁文献卡片。*

![数学与概念提取](https://raw.githubusercontent.com/Misaka16384/magi/main/note2.png)
*从 LaTeX 源码提取并格式化的数学证明与引理。*

---

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

```text
你（驾驶员）
  └─ 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
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/Misaka16384/magi/main/install.ps1 | iex"
```

**macOS / Linux：**

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

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

随时体检环境：

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

<details>
<summary>展开手动步骤</summary>

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

```powershell
# 一条命令管装和升级，幂等——已经是最新就什么都不做
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 见[官方文档](https://github.com/gastownhall/beads/blob/main/docs/getting-started/installation.md)。没有 `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。

</details>

### 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）

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

```powershell
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 插件路线**（一键脚本已自动执行，与上面的安装可共存）：

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

---

## 3. 快速上手（5 分钟）

```powershell
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              # 同步率 + 三核状态，并把能自动修的都跑掉
```

```text
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 分发**，三个入口读同一份内容：
>
> ```powershell
> magi guide                                # 列出十二章
> magi guide ingest                         # 读某一章
> magi guide --search "no project found"    # 把报错原文贴进去
> magi guide --symptoms                     # 全书「症状 → 原因 → 修法」索引
> ```
>
> 或 `magi ui` → **文档与指引** → **使用指南**（带章节导航），也可直接读 [`guide.zh.md`](./src/magi/docs/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：分数只是排序不是判据，判断在你 |

单命令的包装不再是 skill：建库是 `magi init`，修复是 `magi lint --fix`，建图是
`magi graph build`，语义连边是 `magi link`，查手册是 `magi guide`。样板（工具能力、
谁能问人、无人值守怎么办）只在 `AGENTS.md` 的托管块里写一次。

### 跨项目检索

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

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

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

```powershell
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`），但不进图谱、不计同步率。引用直接从参考卡导出：

```powershell
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 分类、种子论文与我方论文后：

```powershell
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），用于直观查看三核状态、执行维护与检索实验：

```powershell
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 迁移步骤（三条命令）

```powershell
# 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 变化对照

| 旧（Wikify） | 新（MAGI） |
|---|---|
| `install.ps1` / `install.sh` **复制** `skills/`+`bin/` 到 agent 目录 | 同名脚本已改为**一键引导安装**（uv + CLI + `magi setup`，§2.1）；skills 随包分发，用 `magi skills install` 按项目安装（§2.4） |
| `python <BIN>/llm-wiki.py lint --fix <dir>` | `magi lint --fix <dir>` |
| `python <BIN>/llm-wiki.py graph <dir>` | `magi graph build <dir>` |
| `python <BIN>/query-graph.py "<SQL>"` | `magi graph query "<SQL>"` |
| `python <BIN>/search-wiki.py <regex> <files>` | `magi grep <regex> <files>`；语义检索新增 `magi index` + `magi search` |
| `python <BIN>/ingest_helper.py --file ...` | `magi ingest add --file ...`（其余摄入脚本同理归入 `magi ingest *`） |
| `semantic_linker.py` | `magi link` |
| `verify_claims.py` | `magi verify`（v2：`--json`、空白归一化匹配、`--fetch-web`） |
| `requirements.txt` 手动装依赖 | 随 CLI 自动安装 |
| 任务/进度记在 `log.md` | Beads（`bd`）任务图；`log.md` 降级为人读叙事 |
| `~/.config/llm-wiki/config.json`（hub 路径） | `~/.config/magi/config.json`（旧路径仍被自动回退读取） |
| 依赖 ripgrep | 不再需要 |

---

## 6. Obsidian 集成

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

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

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

---

## 7. 开发

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

