使用说明
Velle
拉丁语：“to will”-意志的根源。
Velle是一个MCP服务器，它使Claude Code能够自我提示。它通过Win32控制台API将文本作为用户输入注入终端，实现了无人干预的自主多回合工作流。功能包括自提示链、两步斜线命令自检、可配置转弯限制、冷却强制和审计日志记录。
运作原理
Velle作为Claude Code的MCP服务器子进程运行。当代理人来电时 velle_prompt，服务器将文本作为键盘输入注入父进程的控制台：
Agent calls velle_prompt("investigate the auth module")
|
v
Velle MCP Server (child process)
|
FreeConsole() -> AttachConsole(parent) -> CreateFile("CONIN$")
|
WriteConsoleInputW(key events) -> 500ms delay -> Enter key
|
v
Claude Code receives text as user input -> Agent gets a new turn
每一轮，代理都会决定下一步做什么，并可以链接另一轮 velle_prompt 继续自主。
Slash命令反思
Slash命令需要两步注入：命令本身，然后是后续提示，以便代理有机会读取输出。
velle_prompt(
text="/context",
follow_up="Summarize the context usage above.",
delay_ms=2000,
follow_up_delay_ms=3000
)
代理接收斜线命令输出，如下所示 <local-command-stdout> 根据其背景，可以采取行动。
允许的Slash命令
| 命令 | 描述 |
|---|---|
/compact |
将对话压缩到自由语境 |
/context |
可视化上下文窗口的使用情况 |
/usage |
显示计划使用限制和费率限制 |
/status |
显示版本、型号、帐户、连接 |
/stats |
可视化每日使用情况、会话历史记录 |
/todos |
显示活动待办事项 |
/tasks |
显示正在运行的后台任务 |
/bashes |
显示正在运行的后台bash命令 |
/doctor |
检查安装状况 |
/debug |
读取会话调试日志 |
/ide |
显示IDE连接状态 |
/release-notes |
查看发行说明 |
交互式命令(/help, /mcp, /config等等）被阻塞。
工具
velle_prompt
将文本作为用户输入注入Claude Code会话。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
text |
字符串 | 必需的 | 要注入的文本 |
delay_ms |
integer | 500 | 注射前延迟（ms） |
follow_up |
string | -- | 斜线命令的可选第二次注入 |
follow_up_delay_ms |
integer | 3000 | 第一次和第二次注射之间的延迟（ms） |
reason |
string | -- | 为什么发出此提示（审计跟踪） |
velle_status
返回当前会话状态：回合计数、限制、控制台可用性、最近的提示日志和配置文件路径。
安全
- 转弯限制 --每个会话可配置的最大自我提示数（默认值：20）。代理无法修改此内容；只有用户可以编辑配置文件。
- 冷却 --提示之间的最小延迟（默认值：1000ms）。防止意外双重火灾。
- 紧急停止开关 --Ctrl+C可以随时停止代理。
- 审计跟踪 --每个自我提示都会记录到
velle_audit.jsonl带有时间戳、文本和原因。
配置
设置从加载 velle.json 在项目根目录中：
{
"turn_limit": 20,
"cooldown_ms": 1000,
"budget_usd": 5.00,
"audit_mode": "both"
}
更改需要重新启动MCP服务器(/mcp 克劳德密码）。代理没有修改配置的工具，只有用户控制这些值。
安装
先决条件
- Windows 11（使用Win32控制台API）
- Python 3.10+
- 克劳德代码CLI
设置
# Clone the repository
git clone https://github.com/PStryder/velle.git
cd velle
# Create virtual environment and install
uv venv
uv pip install -e .
使用克劳德代码注册
添加到您的Claude Code MCP配置中(~/.claude/claude_mcp_config.json):
{
"mcpServers": {
"velle": {
"command": "/path/to/velle/.venv/Scripts/python",
"args": ["-m", "velle.server"],
"cwd": "/path/to/velle"
}
}
}
建筑
src/velle/
__init__.py # Package version
server.py # MCP server — tool definitions, session state, audit logging
injector.py # Win32 console injection — AttachConsole, CONIN$, WriteConsoleInputW
注入器连接到父进程的控制台（因为MCP服务器自己的stdin是MCP传输的管道），打开 CONIN$ 要获取真正的控制台输入缓冲区，请写入关键事件，然后分离。文本字符和Enter键之间有500毫秒的延迟，即使控制台忙于输出，也能确保可靠的提交。
项目结构
velle/
README.md # This file
pyproject.toml # Python package configuration
velle.json # Runtime configuration (turn limits, cooldown)
claude_mcp_config.json # Example MCP server registration
src/velle/ # Source code
spike/ # Proof-of-concept injection tests
docs/ # Design specification and command reference
SPEC.md # Technical specification
COMMANDS.md # Slash command inventory and access classification
词源
来自原始印欧语系 嗯… （“希望”），通过拉丁语 渴望 （“to will”），中世纪拉丁语 volitinem （“意志”）。Velle是自愿的行为——一个选择自己下一步行动的代理人。
许可证
Apache 2.0
