内容
<p align="center">
<b>英文</b> | <a href="README.ua.md">乌克兰语</a>
</p>
# 🚀 P.O.W.E.R. 框架 — 混合知识管理系统
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/)
[](https://docs.pydantic.dev/)
[](https://modelcontextprotocol.io/)
[](https://obsidian.md/)
[](https://github.com/weby-homelab/P.O.W.E.R/actions/workflows/ci.yml)
[](https://github.com/weby-homelab/P.O.W.E.R/releases)
[](https://github.com/weby-homelab/P.O.W.E.R/tree/main/tests)
一种混合知识管理系统（Obsidian 第二大脑），它将人类友好的目录组织与 AI 代理的严格机器可读性相结合。
建立在 **P.A.R.A.** + **OKF Overlay** + **LLM-Wiki** + **执行规则** 的协同作用之上。
---
## 🎯 系统架构（P.O.W.E.R.）
该框架由四种互补的方法论组成：
* **P** — **P.A.R.A.** （项目、领域、资源、存档）— 一个针对人类认知布局优化的逻辑文件夹结构。
* **O** — **OKF Overlay** （开放知识格式）— 每个文件顶部包含元数据（YAML frontmatter），以实现 AI 代理的即时解析。
* **W** — **LLM-Wiki** （A. Karpathy 的理念）— 自动目录索引、时间戳日志和结构链接校验。
* **E.R.** — **执行规则 / 强制例行程序** （自定义自动化规则）— GPG 签名提交、仅限 PR 工作流、基于 cron 的 5 分钟同步和分支清理策略。
### 📊 视觉框架图
```mermaid
graph TB
subgraph Human ["👤 人类（Obsidian UI）"]
PARA["P.A.R.A. 目录结构"]
PARA_P["01_项目"]
PARA_A["02_领域"]
PARA_R["03_资源"]
PARA_AR["04_存档"]
PARA --> PARA_P
PARA --> PARA_A
PARA --> PARA_R
PARA --> PARA_AR
end
subgraph AI ["🤖 AI 代理（本地 / 云）"]
Ingest["摄入笔记"]
Lint["校验保险库（lint_brain.py）"]
Index["重建索引（generate_index.py）"]
end
subgraph OKF ["📄 OKF 叠加层（元数据模式）"]
YAML["YAML frontmatter"]
IndexMD["index.md（目录）"]
LogMD["log.md（变更日志）"]
end
subgraph ER ["🔐 执行规则和强制例行程序"]
GPG["GPG 签名（验证提交）"]
PR["仅限 PR 工作流（GitHub）"]
Sync["Cron 自动同步（sync-brain.sh）"]
Clean["分支清理（cleanup_branches.py）"]
end
Human -- 编写笔记 --> YAML
YAML -- 由 --> AI
AI -- 更新 --> IndexMD
AI -- 追加 --> LogMD
AI -- 运行校验 --> Lint
IndexMD -- 通过 --> Sync
LogMD -- 通过 --> Sync
Sync -- 需要 --> GPG
Sync -- 遵循 --> PR
PR -- 触发 --> Clean
classDef human fill:#1A365D,stroke:#3182CE,stroke-width:2px,color:#FFF;
classDef ai fill:#2C3E50,stroke:#E74C3C,stroke-width:2px,color:#FFF;
classDef okf fill:#1B4D3E,stroke:#2ECC71,stroke-width:2px,color:#FFF;
classDef er fill:#5D3F6A,stroke:#BB8FCE,stroke-width:2px,color:#FFF;
class PARA,PARA_P,PARA_A,PARA_R,PARA_AR human;
class Ingest,Lint,Index ai;
class YAML,IndexMD,LogMD okf;
class GPG,PR,Sync,Clean er;
```
---
## 📂 保险库目录结构
Obsidian 保险库（第二大脑）组织如下：
```text
/brain
├── 00_Inbox/ # 临时文件夹，用于快速记笔记和原始输入
├── 01_Projects/ # 具有特定截止日期和目标的活跃项目
├── 02_Areas/ # 长期责任（基础设施、财务、健康）
├── 03_Resources/ # 通用资源（指南、堆栈、代码片段、脚本）
│ └── lint_brain.py # 自动链接验证和清理脚本
├── 04_Archive/ # 已完成的项目和过时/过期的笔记
├── 05_Templates/ # 具有预定义 OKF 元数据块的模板
├── 06_Daily_Logs/ # 时间戳日志和经验教训（MASTER-LESSONS-LEARNED）
├── PROTOCOLS/ # AI 代理的系统配置和规范
│ └── LLM_WIKI_SCHEMA.md # AI 操作的格式化和校验标准
├── index.md # 自动生成的保险库目录索引
└── log.md # 时间戳变更日志
```
---
## 🏗️ 项目架构（power_core）
该框架建立在共享的 `power_core` Python 包上，提供：
| 模块 | 目的 |
|--------|---------|
| `power_core/models.py` | Pydantic v2 模式，用于严格的 OKF 元数据验证 |
| `power_core/parser.py` | 安全的 YAML frontmatter 解析（基于 PyYAML） |
| `power_core/indexer.py` | 保险库扫描和 index.md 生成 |
| `power_core/linter.py` | 健康检查：损坏的链接、缺失的元数据、孤立的笔记 |
| `power_core/utils.py` | 路径遍历保护、原子写入、备份管理 |
所有组件（MCP 服务器、CLI 脚本）都使用 `power_core` 作为单一的真实来源，消除了代码重复并确保了一致性。
---
## 📄 元数据规范（OKF）
每个笔记都必须在文件顶部包含一个严格的 YAML 块（frontmatter）。这允许 AI 代理立即索引和过滤文档：
```yaml
---
type: 项目 | 领域 | 资源 | 每日日志 | 存档 | 系统指南 # 笔记类别
title: "文档标题" # 人类友好的标题
description: "单行摘要（最多 150 个字符）用于目录" # 简短描述
resource: "https://github.com/..." # 外部源代码（如果有）
tags: [active, guide] # Obsidian 标签
timestamp: YYYY-MM-DDTHH:MM:SS+TZ # 最后修改日期
---
```
---
## 🤖 健康校验过程
`lint_brain.py` 脚本用于执行按需或自动的保险库校验。
### 功能：
1. **损坏的链接**：查找指向不存在文件的内部 wikilink `[[笔记]]` 和 GFM markdown 链接 `[标题](路径.md)`。
2. **元数据验证**：识别缺少 YAML frontmatter 或必需 `type` 字段的笔记。
3. **孤立检查**：报告没有传入链接的笔记（排除核心文件）。
---
## 🔐 安全性和自动化（E.R.）
1. **零秘密**：存储库中没有密码、API 密钥或私有 IP 地址。所有凭证都存放在主机上的本地 `.env` 文件中（添加到 `.gitignore`）。
2. **验证提交（GPG）**：所有提交都必须使用开发人员的 GPG 密钥签名，以在公共存储库中验证提交者身份。
3. **仅限 PR 工作流**：直接推送到 `main` 分支被禁用。所有更新都推送到 `feature/*` 分支，并通过拉取请求合并。
4. **自动同步 Cron**：服务器 Cron 作业每 5 分钟运行一次，自动提交并将保险库更改推送到 GitHub。
---
## ⚡ P.O.W.E.R. 代理技能和 MCP 服务器安装
我们将整个 P.O.W.E.R. 框架规则和索引/校验工具打包成两个可重用的组件：
1. **AI 代理自定义技能**：一个包含指令 (`SKILL.md`) 和脚本 (`scripts/`) 的文件夹，可以加载到支持自定义提示或技能注入的任何代理平台中。
2. **模型上下文协议（MCP）服务器**：一个自包含的、可移植的 Python 服务器 (`mcp_servers/power_server.py`)，为任何兼容的 LLM 客户端（Claude Desktop、Cursor、OpenCode 等）提供三个 MCP 工具（`lint_vault`、`generate_index` 和 `ingest_note`）。
这些组件与任何 AI 代理一起使用，无论是在本地还是在云中运行。
### ⚙️ 一键安装
要将 P.O.W.E.R. 技能和 MCP 服务器自动安装到您的活动工作区，使其准备好与任何 AI 代理（本地或云）一起使用，请运行：
```bash
curl -sSL https://raw.githubusercontent.com/weby-homelab/P.O.W.E.R/main/install.sh | bash
```
或者，您可以指定自定义的目标工作区路径：
```bash
curl -sSL https://raw.githubusercontent.com/weby-homelab/P.O.W.E.R/main/install.sh | bash -s -- /path/to/your/workspace
```
### 🔌 MCP 服务器配置
安装程序运行后：
1. 在目标执行环境中安装所需的 Python 依赖项：
```bash
pip install mcp
```
2. 配置您喜欢的 AI 客户端以加载 MCP 服务器：
* **Claude Desktop** (`~/.config/Claude/claude_desktop_config.json`)：
```json
{
"mcpServers": {
"power": {
"command": "python3",
"args": ["/path/to/your/workspace/.agents/mcp_servers/power_server.py"],
"env": {
"POWER_VAULT_DIR": "/path/to/your/obsidian/vault"
}
}
}
}
```
* **OpenCode** (`~/.config/opencode/opencode.jsonc`)：
```json
"mcp": {
"power": {
"type": "local",
"command": [
"/root/.config/opencode/venv/bin/python",
"/path/to/your/workspace/.agents/mcp_servers/power_server.py"
],
"enabled": true
}
}
```
### 🔌 手动技能配置（可选）
如果您更喜欢手动配置技能：
1. 将 `skills/power` 目录的内容复制到工作区的 `.agents/skills/power` 文件夹中。
2. 使 `scripts/` 中的脚本可执行：`chmod +x .agents/skills/power/scripts/*.py`
3. 将技能添加到 OpenCode 系统配置中，位于 `~/.config/opencode/opencode.jsonc`：
```json
"instructions": [
"/path/to/your/workspace/.agents/skills/power/SKILL.md"
]
```
---
## 🛠️ 开发
### 设置
```bash
git clone https://github.com/weby-homelab/P.O.W.E.R.git
cd P.O.W.E.R
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```
### 质量检查
```bash
# 运行测试
pytest tests/ -v
# 校验
ruff check power_core/ mcp_servers/ scripts/ tests/
# 格式化
ruff format power_core/ mcp_servers/ scripts/ tests/
# 类型检查
mypy power_core/
```
### 自动化脚本
| 脚本 | 目的 |
|--------|---------|
| `scripts/sync-brain.sh` | 兼容 Cron 的自动同步，支持 GPG 签名 |
| `scripts/cleanup_branches.py` | 通过 GitHub API 自动合并分支清理 |
---
## 📄 许可证
该框架在 MIT 许可证下分发。您可以自由使用它来构建自己的个人或企业知识库。
