内容
<p align="center">
<b>英文</b> | <a href="README.ua.md">乌克兰语</a>
</p>
# P.O.W.E.R. — 为 Obsidian 打造的 AI 原生工具包
从命令行验证、索引、搜索和管理你的 Obsidian 知识库 — 或者让 AI 代理通过 MCP 为你完成。专为希望拥有机器可读笔记、自动化质量检查以及高效 AI 访问其知识库的知识工作者设计。
[](https://github.com/weby-homelab/power-framework/actions/workflows/ci.yml)
[](https://github.com/weby-homelab/power-framework/actions/workflows/ci.yml)
[](https://github.com/weby-homelab/power-framework/releases)
[](https://www.python.org/)
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://github.com/weby-homelab/power-framework/actions/workflows/codeql.yml)
[](https://weby-homelab.github.io/power-framework/)
## 关于 P.O.W.E.R. - 混合知识管理系统（P.A.R.A. + OKF 叠加 + LLM-Wiki + 执行规则）
P.O.W.E.R. 是一个混合系统，旨在弥合人类工作流程、自动化脚本和基于 LLM 的自主代理之间的差距。它集成了三种不同的架构框架，构建了一个连贯、自验证和高效的知识库：
* **P.A.R.A. 方法（Tiago Forte）** — 根据可操作性将文件组织为 **项目**、**领域**、**资源** 和 **存档**。P.O.W.E.R. 采用此目录结构来决定笔记的生命周期。信息从原始 inbox 捕获有机地移动到主动项目执行、长期参考领域和最终存档。
* **OKF（Obsidian 知识框架）叠加层** — 在标准 Obsidian Markdown 文件上强加严格的模式层。基于 Pydantic v2 模式，OKF 要求每个笔记都具有明确的类型和验证（包含所需的 frontmatter 属性，如标题、描述、标签和时间戳）。这将非结构化的 Markdown 文件夹转换为可预测、可查询和机器可读的本地数据库。
* **LLM-Wiki 和执行规则** — 集成针对 AI 代理特别格式化的操作规则和指南（如 `AGENTS.md`、`Successor-Hub.md` 和 `MASTER-LESSONS-LEARNED.md`）。通过将这些规则与**分层索引**（生成顶级 `index.md` 地图和文件夹级 `_index.md` 子目录）相结合，它将 AI 代理的上下文使用量减少了 **75% 至 94%**，并强制执行安全、非破坏性的编辑边界。
### 为什么 P.O.W.E.R. 是独一无二的
大多数知识管理系统都强制进行权衡：它们要么针对人类布局（凌乱的文件夹、视觉标签）进行优化，要么严格格式化以适应数据库处理（JSON/数据库，零格式化）。
P.O.W.E.R. 是独一无二的，因为它提供了一个**双接口混合叠加层**:
1. **人机友好界面** — 标准 Obsidian 知识库，可由任何 Markdown 编辑器或应用程序读取。
2. **AI 友好界面** — 程序化 **模型上下文协议（MCP）** 服务器，结合分层导航索引，让 LLM 代理可以精确、高效地探索、搜索和编辑笔记。
它允许人类作者和 AI 代理作为平等者安全地共同创作、共同检查和共同维护同一个知识库。
## 为什么选择 P.O.W.E.R.？
与通用的 Obsidian 助手不同，P.O.W.E.R. 从头到尾设计用于 **AI-first 知识管理**：
- **AI 原生元数据** — Pydantic v2 模式强制执行严格的 OKF frontmatter，因此每个笔记都是机器可读的
- **高效索引** — 分层 `index.md` + 每个文件夹的 `_index.md` 将 AI 代理的上下文使用量减少约 75%
- **MCP 原生** — 将所有工具暴露给任何与 MCP 兼容的 AI 客户端（Claude、OpenCode、Cursor），无需额外的粘合代码
- **生产级** — 144 个测试，90% 覆盖率，CodeQL 扫描，OIDC 签名的 PyPI 发布
## 快速入门
```bash
pip install power-framework
power init ~/my-vault # 创建知识库结构
power lint ~/my-vault # 检查损坏的链接和缺失的元数据
power index ~/my-vault # 生成目录索引
```
## 内部功能
| 功能 | 功能描述 |
|---------|-------------|
| **CLI** | `power init`、`lint`、`index`、`ingest`、`search` — 从终端进行完整的知识库管理 |
| **MCP 服务器** | 向任何 AI 代理公开 `lint_vault`、`generate_index`、`read_sub_index`、`ingest_note`、`search_vault` |
| **OKF 验证** | Pydantic v2 模式强制执行每个笔记上的严格元数据 |
| **全文搜索** | 标题、内容和标签的关联性评分搜索，附带上下文片段 |
| **分层索引** | `index.md`（导航地图）+ 每个文件夹的 `_index.md`（详细目录）用于 AI 高效阅读（约 75-94% 令牌节省） |
| **CI/CD** | 144 个测试，90% 覆盖率，CodeQL SAST，OIDC 信任发布到 PyPI |
| **文档** | 完整的 [mkdocs-material 站点](https://weby-homelab.github.io/power-framework/)，包含 API 参考和指南 |
## 迁移报告
阅读从扁平索引迁移到分层索引的完整技术报告：
- **[英文：分层索引迁移报告](docs/hierarchical-index-migration.md)** — 性能指标、架构、见解
- **[Українська: Звіт міграції на ієрархічний індекс](docs/hierarchical-index-migration.ua.md)** — повний технічний звіт
### AI 代理迁移指南
任何 AI 代理（Claude、GPT、Gemini、OpenCode）将现有的 Obsidian 知识库迁移到 P.O.W.E.R. 结构的逐步协议：
- **[英文：AI 代理迁移指南](docs/migration-guide.md)** — 5 阶段协议，带有 MCP 工具、分类启发式和故障排除
- **[Українська: Ґайд міграції для AI-агента](docs/migration-guide.ua.md)** — покроковий протокол для будь-якого AI-агента
## 适用人群
- **Obsidian 用户**，希望 AI 代理能够理解和维护他们的知识库
- **开发者**，使用结构化知识库和机器可读元数据构建知识库
- **团队**，需要一致的笔记格式和自动质量检查
## 命令
```
power init <path> 创建具有 P.A.R.A. 文件夹结构的新知识库
power lint <path> 扫描损坏的链接、缺失的元数据或孤立文件
power index <path> 生成分层索引（index.md + _index.md 文件）
power search <path> <query> 全文搜索，带有相关性评分
power ingest <path> [options] 创建具有验证 OKF 元数据的笔记
```
### 吸收示例
```bash
power ingest ~/my-vault --type Project --title "My App" --description "A new project"
power ingest ~/my-vault --type Resource --title "Docker Guide" --description "Docker best practices" --tags devops,docker --resource "https://docs.docker.com"
```
### 搜索示例
```bash
power search ~/my-vault "api authentication"
power search ~/my-vault "deployment guide" --max-results 5
```
## MCP 服务器设置
将 P.O.W.E.R. 连接到任何与 MCP 兼容的 AI 客户端：
```bash
pip install power-framework
```
**Claude Desktop** (`~/.config/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"power": {
"command": "python3",
"args": ["-m", "power_framework.mcp"],
"env": {
"POWER_VAULT_DIR": "/path/to/your/obsidian/vault"
}
}
}
}
```
**OpenCode** (`~/.config/opencode/opencode.jsonc`）：
```jsonc
"mcp": {
"power": {
"type": "local",
"command": ["python3", "-m", "power_framework.mcp"],
"enabled": true
}
}
```
## 知识库结构
P.O.W.E.R. 使用 **P.A.R.A.** 方法和每个笔记的 **OKF 元数据** 来组织知识库：
```
~/my-vault
├── 00_Inbox/
│ └── _index.md # Inbox 笔记的详细子索引
├── 01_Projects/
│ └── _index.md # Projects 目录的详细子索引
├── 02_Areas/
│ └── _index.md # Areas 目录的详细子索引
├── 03_Resources/
│ └── _index.md # Resources 目录的详细子索引
├── 04_Archive/
│ └── _index.md # Archive 目录的详细子索引
├── 05_Templates/ # 带有 OKF 前置信息的笔记模板
├── 06_Daily_Logs/
│ └── _index.md # Daily Logs 目录的详细子索引
├── PROTOCOLS/ # AI 代理的系统规格
├── index.md # 导航地图（链接到子索引）
└── log.md # 追加更改日志
```
### 分层索引协议
AI 代理通过遵循此模式高效读取知识库：
1. **读取 `index.md`** — 通过笔记数量识别相关类别
2. **调用 `read_sub_index` MCP 工具** — 获取该类别的详细条目
3. **读取特定笔记** — 仅当子索引指示相关性时
4. **绝不遍历所有 `.md` 文件** — 使用子索引作为地图（约 75% 令牌节省）
每个笔记都以验证的 YAML 前置信息开头：
```yaml
---
type: Project
title: "My App"
description: "A new project with clear goals"
tags: [active, dev]
timestamp: 2026-07-02T19:00:00
---
```
## 架构详情
<details>
<summary><strong>P.O.W.E.R. 方法论 — 点击展开</strong></summary>
该框架结合了四种互补的方法论：
- **P** — **P.A.R.A.** （项目、领域、资源、存档）— 适用于人类认知的逻辑文件夹结构
- **O** — **OKF 叠加层** （开放知识格式）— 每个文件上的 YAML 前置信息，供 AI 即时解析
- **W** — **LLM-Wiki** （A. Karpathy 的哲学）— 将知识库视为 LLMs 可以读取、写入和维护的 wiki，通过自动目录索引、时间戳日志和结构链接验证
- **E.R.** — **执行规则** — GPG 签名提交、仅 PR 工作流、基于 cron 的同步、分支清理
### 视觉框架图
```mermaid
graph TB
subgraph Human ["👤 人类（Obsidian UI）"]
PARA["P.A.R.A. 目录结构"]
end
subgraph OKF ["📄 OKF 叠加层（元数据模式）"]
YAML["YAML 前置信息"]
end
subgraph Wiki ["📖 LLM-Wiki（Karpathy 的哲学）"]
IndexMD["index.md（导航地图）"]
SubIndex["_index.md（每文件夹详情）"]
LogMD["log.md（更改日志）"]
Lint["链接验证"]
end
subgraph AI ["🤖 AI 代理（本地 / 云）"]
Ingest["吸收笔记"]
Index["重建分层索引"]
ReadSub["按需读取子索引"]
end
subgraph ER ["🔐 执行规则"]
GPG["GPG 签名提交"]
PR["仅 PR 工作流"]
Sync["基于 cron 的自动同步"]
end
Human -- 编写笔记 --> YAML
YAML -- 被解析 --> AI
AI -- 更新 --> IndexMD
AI -- 更新 --> SubIndex
AI -- 追加 --> LogMD
AI -- 运行检查 --> Lint
ReadSub -- 按需 --> SubIndex
IndexMD -. 通过 .-> Sync
SubIndex -. 通过 .-> Sync
LogMD -. 通过 .-> Sync
Sync --> GPG
GPG --> PR
```
### 核心库（`src/power_framework/`）
| 模块 | 目的 |
|--------|---------|
| `core/models.py` | Pydantic v2 模式用于 OKF 元数据验证 |
| `core/parser.py` | 安全的 YAML 前置信息解析（基于 PyYAML） |
| `core/indexer.py` | 知识库扫描和 `index.md` 生成 |
| `core/linter.py` | 健康检查：损坏的链接、缺失的元数据、孤立文件 |
| `core/searcher.py` | 全文搜索，带有相关性评分 |
| `core/utils.py` | 路径遍历保护、原子写入、备份 |
| `core/cli.py` | 命令行界面（init、lint、index、ingest、search） |
| `mcp/server.py` | FastMCP 服务器，向 AI 代理公开所有工具 |
所有组件共享 `power_framework.core` 作为单一的事实来源。
</details>
## 开发
```bash
git clone https://github.com/weby-homelab/power-framework.git
cd power-framework
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# 运行测试（144 个测试，覆盖率 90%+）
pytest tests/ -v
# 检查和格式化
ruff check src/ tests/
ruff format src/ tests/
# 类型检查
mypy src/power_framework/
```
## 许可证
GPLv3 — 在乌克兰境内 ⚡
<p align="center">
在乌克兰境内 ⚡<br>
© 2026 Weby Homelab
</p>
