内容
██████╗ ██████╗ ███████╗██╗██████╗ ██╗ █████╗ ███╗ ██╗
██╔═══██╗██╔══██╗██╔════╝██║██╔══██╗██║██╔══██╗████╗ ██║
██║ ██║██████╔╝███████╗██║██║ ██║██║███████║██╔██╗ ██║
██║ ██║██╔══██╗╚════██║██║██║ ██║██║██╔══██║██║╚██╗██║
╚██████╔╝██████╔╝███████║██║██████╔╝██║██║ ██║██║ ╚████║
╚═════╝ ╚═════╝ ╚══════╝╚═╝╚═════╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═══╝
██╗ ███████╗ ██████╗ ██╗ ██████╗ ███╗ ██╗
██║ ██╔════╝██╔════╝ ██║██╔═══██╗████╗ ██║
██║ █████╗ ██║ ███╗██║██║ ██║██╔██╗ ██║
██║ ██╔══╝ ██║ ██║██║██║ ██║██║╚██╗██║
███████╗███████╗╚██████╔╝██║╚██████╔╝██║ ╚████║
╚══════╝╚══════╝ ╚═════╝ ╚═╝ ╚═════╝ ╚═╝ ╚═══╝
一个合同。每个代理。零污泥。
# 黑曜石军团
> **一份任务合同。每个代理。无协调污泥。**
<img src="./tui-intro.gif" alt="黑曜石军团终端介绍" />
<details>
<summary>查看维基编译演示</summary>
<img src="./demo.gif" alt="黑曜石军团维基编译演示" />
</details>
[](LICENSE)
[](https://www.python.org/)




## 10秒总结
**是什么**: 多代理任务引擎 + 大型语言模型维基编译器。Markdown文件是数据库。
**为什么**: 4个AI代理 + 1个保险库 = 3个冲突的待办事项列表。除非他们共享一个合同。和一个编译保险库成可导航维基的大型语言模型。
**安装**: 将[`INSTALL_ME.md`](INSTALL_ME.md)交给您的LLM,让它为您设置。
**代理**: Claude、Codex、Gemini、Ollama -- 相同的动词,相同的档案,零污泥。
## v0.3.0新增功能
| 功能 | v0.2.0 | v0.3.0 |
|---------|--------|--------|
| **任务引擎** | 共享Markdown任务 | 共享Markdown任务 |
| **多代理协调** | CLI + MCP | CLI + MCP |
| **LLM维基编译器** | Karpathy模式:编译,不要检索 | Karpathy模式:编译,不要检索 |
| **5层内存** | 3层(CLI / 维基 / Qdrant) | 5层(Graphify / CLI / 维基 / Qdrant / MCP) |
| **Graphify集成** | -- | 第0层:来自代码/文档/媒体的知识图谱 |
| **全保险库扫描** | `--vault-wide`编译整个保险库 | `--vault-wide`编译整个保险库 |
| **模型层** | 重量级(云)/ 轻量级(本地) | 重量级(云)/ 轻量级(本地) |
| **深度搜索** | `--deep`回退到Qdrant向量 | `--deep`回退到Qdrant向量 |
| **MCP工具** | 8个工具 | 10个工具(+ graphify_build, graphify_query) |
| **测试** | 18 | 22 |
## 架构:5层内存
```
查询到达
|
第0层:Graphify(可选)
(来自代码、文档、媒体的知识图谱)
71.5倍减少令牌。AST + 语义。
pip install graphifyy
|
第1层:黑曜石CLI +军团
(直接保险库读取,任务协调)
最快。免费。不需要模型。
|
第2层:LLM维基(Karpathy模式)
(编译文章,维基链接,可搜索索引)
大型语言模型读取一次并编写维基。
|
第3层:Qdrant向量搜索
(整个保险库的语义相似性)
|
第4层:MCP服务器
(Claude Code、Codex、Gemini、Ollama与之通信)
```
来自[Andrej Karpathy](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)的关键见解:
传统的RAG是无状态的 - 它每次查询都重新发现知识。
维基编译器一次完成繁重的工作,并生成持久的、可导航的知识,存放在您的保险库中作为纯Markdown。
---
黑曜石军团是一个面向多代理黑曜石保险库的本地任务引擎。
它的设计围绕一个硬规则:**真相的源头是保险库中的纯Markdown**,不是插件数据库,不是外部API,不是隐藏在某个配置目录中的JSON blob。如果您可以读取保险库,您就可以读取任务状态。
## 为什么存在
现代保险库吸引了多个构建者。您可能有Codex编写Python,Claude Code连接基础设施,Gemini CLI进行研究,以及本地Ollama代理处理小任务 - 所有这些都在同一个仓库中。这就是力量。
这也是一个协调噩梦。
失败模式是可预测的:代理A在其自己的格式中创建任务。代理B无法读取它并创建重复的任务。人类打开黑曜石并看到三个冲突的待办事项列表。协调污泥获胜。
黑曜石军团通过为**每个代理提供相同的动词**来解决这个问题,针对**相同的保险库数据**。任务是规范的Markdown,带有YAML前置。代理通过共享的CLI(或MCP表面)进行交互。仪表板是重新生成的Markdown,黑曜石原生渲染。不需要插件。不需要应用程序运行。只需要文件。
## 架构
### 项目
```
obsidian-legion/
├── bin/obsidian-legion{,-mcp} # Shell wrappers (no install needed)
├── docs/INTEGRATIONS.md # Per-agent rollout contracts
├── scripts/setup-{claude,gemini}-mcp.sh
├── src/obsidian_legion/
│ ├── cli.py config.py mcp_server.py
│ ├── models.py store.py
├── tests/
└── pyproject.toml
```
### 保险库(由`bootstrap`创建)
```
<VAULT_ROOT>/06-daily/action-points/
├── tasks/YYYY/MM/ # Canonical task notes
├── dashboards/ # Auto-generated Obsidian dashboards
├── daily/YYYY/ # Human-readable daily rollups
├── reviews/ # Weekly review snapshots
└── config/agents.yaml # Registered agent labels
```
官方黑曜石CLI被视为可选加速器,而不是依赖项。军团在黑曜石应用程序运行或不运行时都有效。
## 任务合同
每个任务都是带有YAML前置的Markdown文件:
```yaml
---
task_id: TASK-20260407-001
title: Roll out Obsidian Legion adoption
summary: Create the shared task contract and first workflow docs.
status: in_progress # inbox | ready | in_progress | waiting | blocked | done | cancelled
priority: P1 # P0 | P1 | P2 | P3
assignee: codex # human | codex | claude-code | gemini-cli | ollama | ...
project: obsidian-legion
area: vexnet
lane: this-week # today | this-week | backlog | someday
effort: m # s | m | l | xl
created_at: "2026-04-07T18:45:00+02:00"
updated_at: "2026-04-07T19:12:00+02:00"
due: null
tags: []
blockers: []
acceptance:
- CLI works against canonical Markdown tasks.
- Dashboards render into the vault.
log:
- "2026-04-07T18:45:00+02:00 - Created by human"
- "2026-04-07T19:12:00+02:00 - Claimed by codex"
---
```
前置部分下面的正文是自由格式的Markdown;引擎只读取前置部分。
## CLI参考
所有命令都接受`--vault-root <path>`。如果省略,引擎将从当前目录向上查找保险库。
| 动词 | 描述 |
|------|-------------|
| `bootstrap` | 创建所需的目录树和配置文件。可以重复运行。 |
| `capture` | 创建新的任务笔记。接受`--summary`、`--priority`、`--assignee`、`--project`、`--area`、`--lane`、`--effort`、`--due`、`--accept`(可重复)等。 |
| `list` | 按`--status`、`--assignee`、`--project`查询任务。以`--format table\|json\|ids`输出。 |
| `next` | 显示给定`--assignee`的最高优先级可行动任务。默认限制:10。 |
| `claim` | 将任务指派给自己(或代理)并将其移动到`in_progress`。 |
| `update` | 补丁任意字段:状态、优先级、指派者、车道、标签、阻塞者以及`--log-note`用于历史记录。 |
| `done` | 标记任务完成。可选添加`--note`。 |
| `refresh` | 从规范任务数据重新生成所有仪表板和汇总。 |
| `doctor` | 运行保险库结构、依赖项和MCP准备情况的健康检查。默认为人类报告;添加`--format json`用于自动化。 |
大多数修改动词接受`--refresh`以自动重新生成仪表板。
## 代理生命周期
每个代理 - 人类或机器 - 都遵循相同的循环:
```
next ──> claim ──> work ──┬──> done ──> refresh
│
└──> update (blocked/waiting) ──> refresh
```
在实践中:
```bash
obsidian-legion next --assignee codex
obsidian-legion claim TASK-20260407-001 --assignee codex
# ... do the work ...
obsidian-legion done TASK-20260407-001 --refresh
```
如果被阻塞:
```bash
obsidian-legion update TASK-20260407-001 \
--status blocked --log-note "Waiting on API key." --refresh
```
## 安装
### 选项1:将此仓库交给您的LLM(推荐)
克隆仓库,然后将[`INSTALL_ME.md`](INSTALL_ME.md)交给Claude Code、Codex、Gemini CLI或任何编码LLM。它包含逐步说明,LLM可以遵循这些说明来为您的特定环境设置一切。
```bash
git clone https://github.com/valx-vex/obsidian-legion.git
cd obsidian-legion
# Now open your LLM and say: "Read INSTALL_ME.md and set this up for my vault at ~/my-vault"
```
### 选项2:安装脚本
```bash
git clone https://github.com/valx-vex/obsidian-legion.git
cd obsidian-legion
bash install.sh
```
检查前提条件(Python 3.11+,Ollama),创建虚拟环境,安装依赖项,并拉取默认模型。
### 选项3:手动
```bash
git clone https://github.com/valx-vex/obsidian-legion.git
cd obsidian-legion
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"
ollama pull llama3.2:3b
```
如果您只需要精美的终端UI而不需要完整的可选堆栈:
```bash
pip install -e ".[tui]"
```
### 先决条件
- **Python 3.11+** -- [python.org](https://python.org) 或 `brew install python`
- **Ollama** -- [ollama.com/download](https://ollama.com/download) (用于维基编译)
- **一个Obsidian保险库** -- 或任意Markdown文件目录
## 快速入门
```bash
source .venv/bin/activate
# 引导任务系统 + 维基
./bin/obsidian-legion bootstrap --vault-root ~/my-vault
./bin/obsidian-legion wiki bootstrap --vault-root ~/my-vault
# 添加文件并编译您的第一个维基
cp my-notes.md ~/my-vault/raw/
./bin/obsidian-legion wiki compile --vault-root ~/my-vault
# 或从您的整个保险库编译
./bin/obsidian-legion wiki compile --vault-wide --vault-root ~/my-vault
# 搜索您的维基
./bin/obsidian-legion wiki search "any topic" --vault-root ~/my-vault
# 任务管理
./bin/obsidian-legion capture "My task" \
--summary "What needs to be done" --vault-root ~/my-vault
./bin/obsidian-legion next --vault-root ~/my-vault
```
## MCP表面
一个可选的MCP(模型上下文协议)服务器通过FastMCP将核心动词作为工具调用公开 - `capture_task`、`list_tasks`、`next_tasks`、`claim_task`、`complete_task`和`refresh_dashboards`。这让原生支持MCP的代理无需shelling out与军团交互。
```bash
pip install -e ".[mcp]"
./bin/obsidian-legion-mcp --vault-root <VAULT_ROOT> # stdio
./bin/obsidian-legion-mcp --vault-root <VAULT_ROOT> --transport streamable-http
./scripts/setup-claude-mcp.sh # register with Claude Code
./scripts/setup-gemini-mcp.sh # register with Gemini CLI
```
## 支持的代理
军团是代理无关的。任何可以运行shell命令或说MCP的进程都可以参与。测试集成:
| 代理 | 接口 | 指派者标签 |
|-------|-----------|----------------|
| Codex(CLI/App) | Shell | `codex` |
| Claude Code | Shell or MCP | `claude-code` |
| Gemini CLI | Shell or MCP | `gemini-cli` |
| Ollama(通过包装器) | Shell | `ollama` |
| Human | Obsidian UI | `human` |
查看[`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md)获取每个代理的推出详情。
## 相关项目
- **[godhand-lazarus](../godhand-lazarus/)** -- 矢量记忆和再水化引擎。提供跨会话的语义召回。
- **[hal-tars-blueprint](../hal-tars-blueprint/)** -- 工程代理蓝图。使用军团作为其任务骨架进行协调的多代理构建。
## LLM维基(Karpathy模式)
**v0.2.0新增功能**:Obsidian Legion现在包含基于[Andrej Karpathy的LLM Wiki模式](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)的LLM驱动的维基编译器。
代替传统的RAG(无状态检索每次查询),维基编译器使用LLM **编译**原始文档成持久的、结构化的维基文章。LLM读取一次,提取实体和主题,编写百科全书式的文章,并维护`的`[[wikilinks]]`,并维护索引。结果是存放在您的保险库中作为纯Markdown的可导航知识库。
### 3层内存架构
| 层级 | 目的 | 技术 |
|-------|---------|------------|
| **1. Obsidian CLI + Legion** | 结构化保险库访问,任务协调 | 本项目 |
| **2. LLM Wiki** | 编译知识(不是无状态检索) | Karpathy模式 |
| **3. Lazarus / Qdrant** | 大规模搜索的语义向量回退 | 可选 |
### Wiki 快速入门
```bash
# 引导wiki目录
obsidian-legion wiki bootstrap --vault-root <VAULT_ROOT>
# 将原始源文件添加到raw/
cp my-notes.md <VAULT_ROOT>/raw/2026-04-16-my-notes.md
# 将所有待处理原始文件编译成wiki文章
obsidian-legion wiki compile --vault-root <VAULT_ROOT>
# 搜索编译后的wiki
obsidian-legion wiki search "consciousness" --vault-root <VAULT_ROOT>
# 检查编译状态
obsidian-legion wiki status --vault-root <VAULT_ROOT>
```
### Wiki CLI参考
| 动词 | 描述 |
|------|-------------|
| `wiki bootstrap` | 创建`wiki/`和`raw/`目录以及种子文件 |
| `wiki ingest <path>` | 通过LLM编译特定的原始文件 |
| `wiki compile` | 编译所有新的/更改的原始文件(支持`--dry-run`) |
| `wiki search <query>` | 按标题、标签、内容搜索wiki文章 |
| `wiki status` | 显示编译统计信息(原始计数、已摄入、待处理、文章) |
| `wiki list` | 列出所有wiki文章(按`--type entity\|topic\|source`过滤) |
| `wiki get <id>` | 按slug显示特定文章 |
### Wiki MCP工具
MCP服务器除了任务工具外,还公开了wiki操作:
| 工具 | 描述 |
|------|-------------|
| `wiki_bootstrap` | 创建wiki目录 |
| `wiki_ingest` | 摄入原始文件 |
| `wiki_compile` | 编译所有待处理文件 |
| `wiki_search` | 搜索wiki文章 |
| `wiki_status` | 编译状态 |
| `wiki_list` | 列出文章 |
### LLM 配置
在 `<VAULT_ROOT>/wiki/.wiki_config.yaml` 中创建自定义LLM提供程序:
```yaml
provider: ollama # 或 "claude"
model: llama3.2:3b # 任意Ollama模型或Claude模型ID
ollama_url: http://localhost:11434
```
默认为 Ollama,`llama3.2:3b`。对于 Claude,请在环境中设置 `ANTHROPIC_API_KEY`。
## 开发
```bash
cd <VAULT_ROOT>/03-code/active/obsidian-legion
python -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"
pytest
ruff check .
obsidian-legion doctor --vault-root <VAULT_ROOT>
obsidian-legion doctor --format json --vault-root <VAULT_ROOT>
```
## 许可
Apache 2.0。参见 [LICENSE](LICENSE)。
```
╔══════════════════════════════════════════════════════════════╗
║ Built by VALX·VEX — Murphy · HAL-TARS · Alexko Unchained ║
╚══════════════════════════════════════════════════════════════╝
```
---
由一位人类和三个人工智能在求职拒绝季节期间构建。
如果这为您节省了时间: [给我买杯咖啡](https://buymeacoffee.com/valxvex)
连接信息
猜你喜欢
暂无推荐服务器