Vinf Agent · 个人认知外延系统（开源版）

定位：V∞ 体系开源版——零代码门槛、纯文本配置、单机自治的个人认知外延 Agent。 一句话：把你的方法论编译成一套跨模型可复现的本地规则，模型只是外网耗材，规则才是你的本地主权。

这是什么

Vinf Agent 是 V∞ 体系的开源版落地。它不承诺「智能涌现」，只做一件事：

把「你想让 Agent 记住并遵守的规则」写成你可以看到、可以修改、可以版本管理的本地文件，不依赖模型会话记忆。

这意味着：

• 换任意模型，规则不变（方法论与模型解耦）；
• 你的记忆、人设、行为边界都在本地，外网不可见（数据主权在本地）；
• 你 fork 一份配置，就获得一份可复现的认知外延（零代码门槛）。

快速开始

# 1. 克隆
git clone https://github.com/vinf-eternal/vinf-agent.git
cd vinf-agent

# 2. 复制配置模板
cp -r config.example config

# 3. 配置你的 API key（模型 = 外网耗材，随意更换）
#   编辑 config/global/agents.md 设置人设、记忆规则、行为边界

# 4. 运行（零安装，无需 pip install —— 纯 stdlib）
python run.py --config config            # CLI 模式
python run.py --config config --web      # 本地 Web 版，浏览器开 http://127.0.0.1:8787

一行安装（可选，体验 = npx pi）

把 bin/ 加入 PATH 后，任意目录直接执行 vinf-agent：

# macOS / Linux
./install.sh          # 软链 bin/vinf-agent 到 ~/.local/bin

# Windows
powershell -ExecutionPolicy Bypass -File install.ps1   # 创建 %LOCALAPPDATA%\bin\vinf-agent.cmd

# 之后任意位置：
vinf-agent --web      # 启动本地 Web 版

需要 Python 3.10+（本机已装即可，项目零第三方依赖）。测试：python -m pytest tests（32 tests）。

目录结构

vinf-agent/
├── README.md              # 本文件
├── run.py                 # 零安装入口（python run.py）
├── install.sh             # 一键安装（macOS/Linux）
├── install.ps1            # 一键安装（Windows）
├── bin/
│   ├── vinf-agent         # PATH 启动器（POSIX）
│   └── vinf-agent.cmd     # PATH 启动器（Windows）
├── docs/
│   ├── ARCHITECTURE.md    # 设计架构图（单黑盒拓扑 + 双层循环）
│   ├── DUAL_LOOP.md       # 双层循环详解（外环交互 + 内环工具）
│   └── AUDIT.md           # 设计审计记录
├── config.example/
│   ├── global/
│   │   └── agents.md      # 全局常项（人设/记忆规则/行为边界）
│   ├── project/
│   │   └── agents.md      # 项目变项（按场景覆盖）
│   └── append_system.md   # 第四层热补丁（最高优先级，可选）
├── prompts/
│   └── system.md          # 系统提示词
├── src/
│   └── vinf_agent/        # 核心代码
│       ├── __main__.py    # CLI 入口（--config / --web）
│       ├── agent_loop.py  # 双层循环内核
│       ├── bootstrap.py   # 组件装配（CLI/Web 共享）
│       ├── web.py         # 本地 Web 版（stdlib http.server）
│       ├── web/index.html # 单 HTML 聊天页（无 CDN）
│       ├── config.py      # 三层配置读取 + append_system
│       ├── memory_gate.py # B_in 记忆读写门
│       ├── filter.py      # B_out 外层过滤
│       ├── tools.py       # 工具白名单
│       └── llm.py         # OpenAI 兼容客户端
└── tests/                 # 32 tests

配置分层（旁路由）

append_system.md   ← 最高优先级（跨项目热补丁）
project/agents.md  ← 项目变项（场景定制）
global/agents.md   ← 全局常项（人设/记忆/边界）

三层规则持续后台生效，不直接处理用户原始流量——就像网络里的旁路由，主链路照常，规则始终在场。

本地 Web 版

python -m vinf_agent --config config --web [--port 8787] [--host 127.0.0.1]

• 自托管：仅监听 127.0.0.1，API key 留在本机，浏览器只连 localhost（数据主权本地）；
• 零新增依赖：纯 stdlib http.server + 单 HTML 页（无 CDN、可离线）；
• 会话记忆：同一会话多轮消息在服务端累积，私人记忆经 B_in 门读写；
• 不做公开 SaaS：这是开源版定位（个人认知外延系统），对外宣称不承诺「智能涌现」。

设计原则

1. M33 双层势垒：用户输入走外层过滤（PublicBuffer），私人记忆走内层隔离（PrivateCore），两层读写不互通；
2. C-01 模态上限：全部为 md 文本 + 轻量规则引擎，不做认知涌现承诺；
3. C-02 审计纪律：系统自检仅做逻辑纠错；本仓库不产出「AGI/意识/认知跃迁」类表述。

Roadmap

许可证

MIT。内核方法论属于你，代码属于社区。

本文档版本: 0.1 | 开发态 | 设计审计通过（docs/AUDIT.md）