vardoger

vardoger

一款面向 AI 编码助手的跨平台插件（Cursor、Claude Code、OpenAI Codex、OpenClaw、GitHub Copilot CLI、Devin Local、旧版 Windsurf 和 Cline），可读取受支持的本地对话历史格式，提取行为模式，并生成个性化的系统提示词补充内容，让助手逐步更适应你的工作方式。各平台当前的格式限制会在下文逐一说明，而不是悄悄读取未公开的存储数据。

历史发现、解析、检查点和生成的规则都会保留在你的设备上。分析由你调用的宿主助手执行，因此选取的对话片段会遵循该助手及模型提供方的数据政策。Vardoger 不运行任何后端，也不发送遥测数据。

先决条件

Python 3.11+

平台	命令
macOS	brew install [email protected]（安装 Homebrew）或 python.org/downloads/macos
Debian / Ubuntu	sudo apt install python3
Fedora	sudo dnf install python3
Windows	winget install Python.Python.3.13 或 python.org/downloads/windows

pipx

推荐使用 pipx 将 vardoger 安装为隔离的 CLI 工具。完整说明请参阅 pipx.pypa.io/stable/installation。

平台	命令
macOS	brew install pipx && pipx ensurepath
Debian / Ubuntu	sudo apt install pipx && pipx ensurepath
Fedora	sudo dnf install pipx && pipx ensurepath
Windows	scoop install pipx 或 pip install --user pipx && pipx ensurepath

快速开始

pipx install vardoger
vardoger setup cursor        # or claude-code, codex, openclaw, copilot, devin, windsurf, cline

然后告诉你的助手：“个性化我的助手。”

想查找应用内插件列表？可在 MARKETPLACE_STATUS.md 中查看各个市场（PyPI、Cursor、Claude Code、Codex、Copilot CLI、Devin Desktop、Cline、ClawHub）的审核状态。 Vardoger 目前已在 PyPI、Claude Code 社区目录、自托管的 Codex 和 Copilot 市场、McpMux 以及 Official MCP Registry 上线。此前的 Cursor 列表目前不可用。ClawHub 已回退到 0.3.1，并被有意冻结，因为其强制要求的 MIT-0 条款与本项目的 Apache-2.0 许可冲突。目前的 OpenClaw 历史记录已通过直接安装路径提供实时可用且经用户选择启用的完整读取 Gateway CLI 方式。

先前的预发布版本。 pipx install vardoger 现在会安装稳定版 0.4.0。以下 Beta 安装方式仍保留，供仍固定使用早期版本的用户参考；新安装通常无需使用这些方式。

# 选择安装未来的预发布版本（0.2.0bN 等）：
pipx install --pip-args="--pre" vardoger
# 或固定安装较早的预发布版本：
pipx install vardoger==0.1.0b3
# 或无需安装即可运行：
uvx vardoger --help

CLI 命令

命令	用途
vardoger setup <platform>	将 vardoger 注册到某个平台（cursor、claude-code、codex、openclaw、copilot、devin、windsurf、cline）。
vardoger status [--platform X] [--json]	报告每项个性化配置是最新还是过时。
vardoger prepare --platform X [--batch N] [--synthesize]	生成 AI 驱动的技能流水线所用的批量提示词。
vardoger write --platform X	从标准输入读取综合后的个性化配置，并将其写入平台的规则文件（支持 YAML frontmatter 置信度元数据）。
vardoger feedback accept|reject --platform X [--reason TEXT]	记录你是否保留或拒绝了上一次生成的内容。reject 会自动恢复到上一个版本。
vardoger compare --platform X | --all [--window DAYS] [--json]	对比最新个性化配置前后的启发式对话质量指标。
vardoger profile sources [--platform X] [--json]	列出已保存的生成版本及其稳定的一基选择 ID。
vardoger profile preview --source X:N [--source Y:latest]	将明确选定的生成版本编译为规范化的跨主机配置文件，并显示可移植的 AGENTS.md 差异，但不写入文件。
vardoger profile write --source X:N --target ./AGENTS.md [--apply]	显示相同的差异；只有用户明确添加 --apply 时，才更新 Vardoger 的围栏块。

工作原理

1. 读取 — 解析已存储在磁盘上的受支持对话文件，包括选择加入的 Devin ATIF 导出文件
2. 分析 — 主机 AI 模型识别你的沟通风格、技术栈、工作流和偏好方面的模式
3. 生成 — 生成一段针对你定制的系统提示词补充内容
4. 交付 — 将补充内容写入平台的原生配置（.cursor/rules/、.claude/rules/、AGENTS.md 等）

首次运行与增量运行。 默认情况下，vardoger 不会应用时间范围 — 首次运行会读取你的完整本地历史记录（此时信号最丰富；如果默认限制时间范围，就会悄悄漏掉较早的会话，而你之后再也没有机会将它们纳入处理）。此后，~/.vardoger/state.json 中按对话记录的检查点存储会确保后续每次运行都只重新处理新增或更改的对话，因此刷新速度很快。 如果你的本地历史记录非常庞大，想要控制首次运行的开销，可以传入 --since DAYS（例如 vardoger prepare --platform cursor --since 90）；使用 --full 可强制完整重新扫描，绕过检查点。

跨主机配置文件编译器

配置文件编译器只会合并你选定的现有 Vardoger 生成版本；它不会悄悄重新打开原始转录。生成版本索引从 1 开始，而 latest 会解析为该平台最新保存的生成版本：

# Discover the reviewed generations available for selection.
vardoger profile sources

# Read-only: render the profile, audit summary, and exact AGENTS.md diff.
vardoger profile preview \
  --source claude-code:latest \
  --source codex:2 \
  --target ./AGENTS.md

# Optional controls are applied before rendering and included in the audit.
vardoger profile preview \
  --source codex:latest \
  --min-confidence medium \
  --max-age 180 \
  --redact '@example\.com' \
  --target ./AGENTS.md

# Still preview-only without --apply. This is the explicit write step.
vardoger profile write \
  --source claude-code:latest \
  --source codex:2 \
  --target ./AGENTS.md \
  --apply

使用 profile preview --json 可查看规范化的 JSON 审计记录。该记录包含来源平台、生成版本、输出哈希/路径、观察时间、时效性、置信度、冲突、取代关系和排除项。相互矛盾的规则（例如“优先使用制表符”和“避免使用制表符”）在审核前不会纳入有效指令。写入时会保留 和 之外的所有内容。

支持的平台

平台	历史记录来源	提示词交付方式	集成方式
Cursor	Agent 对话记录 JSONL	.cursor/rules/vardoger.mdc	Marketplace 插件 + MCP
Claude Code	会话 JSONL	.claude/rules/vardoger.md	社区／自定义插件
OpenAI Codex	会话 rollout JSONL	~/.codex/AGENTS.md	仓库 Marketplace 插件
OpenClaw	旧版 JSONL，或通过官方 Gateway CLI 选择性地完整读取；绝不查询私有 SQLite	~/.openclaw/skills/vardoger-personalization/SKILL.md	分析器 + Gateway 兼容性状态
GitHub Copilot CLI	~/.copilot/session-state/<session-id>/events.jsonl，以及旧版平铺 JSONL	~/.copilot/copilot-instructions.md（全局）或 <project>/.github/copilot-instructions.md（项目）——在 `` 围栏区域内管理	自定义插件 + 已发布的技能
Devin Local	用户启用的 Devin CLI --export ATIF JSON，位于 ~/.vardoger/imports/devin/	~/.config/devin/AGENTS.md（全局，围栏区域）或 <project>/.devin/rules/vardoger.md	ATIF + 技能 + 规则集成
Legacy Windsurf / Cascade	~/.codeium/windsurf/**/*.jsonl	~/.codeium/windsurf/memories/global_rules.md（全局，围栏区域）或 <project>/.windsurf/rules/vardoger.md（项目，专用文件）	Legacy Cascade 技能 + CLI + MCP
Cline	VS Code globalStorage/.../tasks/*/api_conversation_history.json	~/Documents/Cline/Rules/vardoger.md（全局）或现有的 .clinerules 项目布局	CLI + MCP

开发

需要安装 uv（Python 包管理器）：

git clone https://github.com/dstrupl/vardoger.git
cd vardoger
uv sync
.venv/bin/vardoger --help

项目结构

src/vardoger/          # shared core — history reading, analysis, prompt generation
.agents/plugins/       # repository-level Codex marketplace catalog
plugins/_shared/       # shared analysis/personalization skill authored once
plugins/cursor/        # Cursor MCP server config, install script
plugins/claude-code/   # Claude Code plugin manifest, skills
plugins/codex/         # Codex plugin manifest, skills
plugins/openclaw/      # OpenClaw skill
plugins/copilot/       # GitHub Copilot CLI plugin manifest, skills
plugins/devin/         # Devin Local ATIF export, skill, and rules integration
plugins/windsurf/      # Legacy Cascade install snippet and rules delivery
plugins/cline/         # Cline integration and marketplace install guidance
tests/                 # all tests, mirroring src/ structure

• 与平台无关的逻辑位于 src/vardoger/ 下。
• 平台专属集成（清单、技能、安装脚本）位于 plugins/<platform>/ 下。
• 测试位于 tests/ 下，并与源代码树保持对应。

完整的编码标准和质量检查请参阅 AGENTS.md。

质量门禁

CI 会在每次推送和拉取请求中强制执行综合质量标准：

• ruff check / ruff format --check — 代码检查（包括复杂度、pylint、return、pathlib、tryceratops 规则）和格式检查。
• mypy src/ — 严格类型检查。
• pytest --cov=vardoger --cov-fail-under=80 — 在 Python 3.11–3.13 上运行测试，综合覆盖率不得低于 80%。
• 并行安全任务会运行 bandit -r src/ 和 pip-audit --skip-editable，以发现常见代码问题和依赖项中的 CVE。

推送前，请在本地运行完整检查：

uv run ruff check . && uv run ruff format --check . && uv run mypy src/ && uv run pytest --cov=vardoger --cov-fail-under=80

参与贡献

欢迎贡献。简要步骤如下：

1. 在 GitHub 上 Fork dstrupl/vardoger，并克隆你的 Fork。
2. 运行 uv sync 并创建一个主题分支。
3. 编写更改并添加测试，然后运行上文的一行质量门禁命令。
4. 推送到你的 Fork，并针对 main 创建 PR。

CI（在 Python 3.11/3.12/3.13 上运行的 test，以及 security 任务）会在 PR 上自动运行。首次贡献者可能需要维护者在首次工作流执行前点击 Approve and run。

完整的操作指南请参阅 CONTRIBUTING.md，编码标准和提交消息约定请参阅 AGENTS.md。

发布到 PyPI

CI 会在每次推送和 PR 时自动运行（lint、类型检查，以及 Python 3.11–3.13 的测试）。要发布新版本：

1. 同步更新软件包、生成的 setup 清单、平台清单和注册表元数据；关闭 CHANGELOG.md 中对应的章节。
2. 运行完整的质量、安全、插件验证和构建检查。
3. 提交并推送到 main，然后等待所有必需的检查完成。
4. 创建带注释的 vX.Y.Z 标签，并发布对应的 GitHub 发布版本。

publish.yml 工作流会构建软件包，并通过可信发布者上传到 PyPI（无需 API 令牌）。完成后，pipx install vardoger 将安装新版本。

状态

公开测试版。版本 0.4.0 已发布到 PyPI 并在 GitHub 上打上标签；此源代码树对应这一已发布版本。 请参阅 MARKETPLACE_STATUS.md，了解实时上架情况和剩余的官方目录提交。 请参阅 MANUAL_SUBMISSION_RUNBOOK.md，了解仅限所有者执行的提交、审核和发布步骤。 请参阅 PRD.md，了解完整的产品需求文档。

隐私与安全

• PRIVACY.md — vardoger 会读取、写入什么，以及（重要的是）不会向任何地方发送什么。
• SECURITY.md — 如何私下报告漏洞。

许可证

本项目采用 Apache License，Version 2.0 授权。 另请参阅公开的隐私政策和使用条款。