内容
# 智慧笔记
在 Claude 驱动的开发中，将智慧笔记作为文档源。
简体中文 | [English](./README.md)
`wiznote` 是一个公开、保护隐私的 Claude 技能和 Python 助手集合，适用于希望拥有轻量级文档工作流的开发者：私有 WizNote 部署、存储库本地镜像和 Claude 友好操作，集于一身。
它适用于个人开发者和小团队的 vibe 编码，在这种编码方式中，计划、笔记、规格和实现上下文需要靠近代码，而无需引入繁重的文档平台。
## 为什么开发者可能需要它
- **默认私有** — 连接到您自己的 WizNote 部署，而不是将文档移动到公共 SaaS 工作区
- **Claude 友好工作流** — 将相同的文档系统与 Claude Code 和相邻的桌面、Web 或 IDE 为中心的存储库工作流配对
- **跨端连续性** — 在一个表面上编写或同步，从另一个表面继续，并保持相同的文档源
- **为个人或小团队的 vibe 编码而构建** — 将文档、计划和实现笔记紧密耦合到代码库
- **包含存储库镜像** — 将 WizNote 作为规范，同时在 `docs/wiznote-mirror/...` 中保留代码邻近的 Markdown 副本
该软件包源自私有内部工作流，但所有用户特定的路径、主机、凭证和组织特定的文件夹映射都已删除。
## 最新更新
### 2024-07-04
- 为现有的 WizServer 部署添加了本地 stdio MCP 适配器。
- 添加了用于文件夹创建、笔记搜索/读取和笔记创建/更新工作流的工具。
- 添加了 `wiznote-mcp` 软件包入口点和通用 MCP 配置文档。
完整历史：[docs/releases/release-notes.md](./docs/releases/release-notes.md)
## 包含内容
- `SKILL.md` — Claude Code 技能定义
- `wiznote_cli.py` — 登录、列表、下载、创建和更新笔记助手
- `wiznote_helper.py` — 类别验证、镜像路径生成和 HTML 正文提取助手
- `wiznote_mcp.py` — 本地 stdio MCP 适配器，调用现有的 WizServer HTTP API
- `tests/` — 公开的助手和 CLI 行为的 pytest 覆盖
## 功能
- 使用显式凭证或环境变量登录 WizNote 服务器
- 通过本地 MCP 服务器使用 WizNote，无需运行另一个 Docker 容器
- 列出指定类别根目录下的笔记
- 创建 WizNote 文件夹/类别
- 搜索笔记
- 下载笔记 HTML
- 从生成的 HTML 创建新笔记
- 更新现有笔记
- 安全地将笔记镜像到 `docs/wiznote-mirror/...`
- 验证类别路径，以确保同步停留在您选择根目录内
- 支持 Unicode 笔记标题用于镜像文件名
## 要求
- 推荐 Python 3.11+
- 可达的 WizNote 服务器
- 根据您的工作流选择性地使用 Python 包：
- `markdown` 用于 Markdown → HTML 转换
- `pytest` 用于运行包含的测试
## 安装
### 选项 1：作为 Claude Code 技能使用
将此目录复制到您的 Claude 技能目录：
```bash
mkdir -p ~/.claude/skills
cp -R ./wiznote ~/.claude/skills/wiznote
```
### 选项 2：保留在您的存储库中
您也可以将 `wiznote/` 保存在您的存储库中，并直接在您自己的脚本中导入 Python 文件。
## 配置
设置以下环境变量：
```bash
export WIZNOTE_BASE_URL="https://notes.example.com"
export WIZNOTE_USER="you@example.com"
export WIZNOTE_PASSWORD="your-password"
```
您还需要在脚本中设置两个运行时值：
- `category_root` — 您要在其下同步的顶级 WizNote 类别，例如 `/team/docs/`
- `repo_root` — 用于镜像输出的本地存储库根目录
## 本地 MCP 适配器
`wiznote_mcp.py` 是一个 stdio MCP 服务器。它不需要单独的 Docker 容器，也不会修改您现有的 WizServer 部署。MCP 进程直接连接到现有的 WizServer HTTP API。
示例 MCP 配置：
```json
{
"mcpServers": {
"wiznote": {
"command": "python3",
"args": [
"/path/to/wiznote/wiznote_mcp.py",
"--base-url",
"http://127.0.0.1:18080",
"--username",
"you@example.com",
"--password",
"your-password"
]
}
}
}
```
如果您的 MCP 客户端在环境变量中保留机密，请省略参数并设置 `WIZNOTE_BASE_URL`、`WIZNOTE_USER` 和 `WIZNOTE_PASSWORD`。
可用的 MCP 工具：
- `wiz_create_folder` — 创建 WizNote 类别/文件夹
- `wiz_list_notes` — 列出类别/文件夹中的笔记
- `wiz_search_notes` — 搜索笔记
- `wiz_get_note` — 读取笔记元数据和 HTML 正文
- `wiz_create_note` — 从 HTML 或基本 Markdown 创建笔记
- `wiz_update_note` — 从 HTML 或基本 Markdown 更新现有笔记
MCP 适配器仅通过 WizServer API 写入。它不会直接写入 MySQL 或 `/wiz/storage`，因此 WizServer 仍然拥有权限、版本、对象数据和索引。
## 快速入门
### 1. 导入助手
```python
from pathlib import Path
import sys
SKILL_DIR = Path("/path/to/wiznote")
sys.path.insert(0, str(SKILL_DIR))
import wiznote_cli as cli
import wiznote_helper as helper
```
### 2. 加载凭证并登录
```python
creds = cli.load_credentials()
login = cli.login(creds)
```
或显式传递凭证：
```python
creds = cli.load_credentials(
base_url="https://notes.example.com",
user="you@example.com",
password="your-password",
)
login = cli.login(creds)
```
### 3. 选择类别根目录和目标类别
```python
category_root = helper.normalize_category_root("/team/docs/")
category = helper.resolve_category(category_root, "plans/")
```
### 4. 列出笔记
```python
payload = cli.fetch_note_list(
base_url=login.kb_server,
kb_guid=login.kb_guid,
token=login.token,
category=category,
)
```
### 5. 创建笔记
```python
html = "<h1>项目设计</h1><p>...</p>"
result = cli.create_note(
base_url=login.kb_server,
kb_guid=login.kb_guid,
token=login.token,
title="项目设计",
category=category,
html=html,
)
```
### 6. 构建安全的本地镜像路径
```python
mirror_path = helper.mirror_output_path(
repo_root=Path("/path/to/repo"),
category_root=category_root,
category=category,
title="项目设计",
)
```
## 推荐的同步流程
1. 配置凭证
2. 规范化类别根目录
3. 登录一次并重用会话
4. 解析确切的目标类别
5. 在写入前列出笔记
6. 将 Markdown 转换为 HTML
7. 首先在 WizNote 中创建或更新笔记
8. 其次刷新本地镜像
9. 重新列出类别以验证写入
## Markdown 到 HTML
`create_note(...)` 和 `save_note(...)` 期望 HTML，而不是原始 Markdown。
示例：
```bash
python3 -m pip install markdown
```
```python
import markdown
html = markdown.markdown(text, extensions=["extra", "fenced_code", "tables", "sane_lists"])
```
## 运行测试
```bash
python3 -m pip install pytest
pytest wiznote/tests
```
## 隐私和发布说明
此公开版本故意避免：
- 硬编码的主目录
- 私有服务器地址
- 用户名或密码
- 组织特定的项目文件夹映射
如果您 fork 或修改它，请保持您的公开副本不包含私有基础设施详细信息。
## 文件布局
```text
wiznote/
├── README.md
├── README.zh-CN.md
├── SKILL.md
├── wiznote_cli.py
├── wiznote_helper.py
├── wiznote_mcp.py
└── tests/
├── conftest.py
├── test_cli.py
└── test_helper.py
```
## 许可证
MIT. 请参阅 [`LICENSE`](./LICENSE).
