Personal Agent

本仓库是 develop 分支的公开快照（2026-09-04），内部规划文档与开发指令不在公开范围内。 完整开发历史保留在私有仓库中。

Personal Agent 是一个本地优先的 AI 助手，可以独立作为桌面 Agent 使用，也可以接入 Codex，成为 Codex 的受控执行端。

它最重要的使用方式是：让 Codex 继续负责分析、规划和验收，把明确委派的子任务交给 Personal Agent，再由你配置的 DeepSeek、Qwen、MiniMax、Claude、OpenAI、Gemini 等模型执行。 这样可以减少适合外部分流任务对 Codex 额度的消耗，同时保留 Codex 的工作流和最终控制权。

Personal Agent 不会绕过、破解或扩充 Codex 官方配额。它通过公开的 MCP 接口，把用户明确 委派的工作交给另一个独立 Runtime 执行。

功能

• Codex 协作：Codex 负责分析、规划和验收，Personal Agent 使用你配置的其他模型执行明确委派的子任务，减少 Codex 额度压力。

• 独立桌面 Agent：不接入 Codex 也能直接聊天、切换模型、管理会话和查看运行过程。

• 多模型支持：支持 DeepSeek、Qwen、MiniMax、Claude、OpenAI、Gemini、GLM 和 MiMo 等 Provider。

• 项目上下文：按实际项目目录隔离会话、消息和文件能力，可读取项目资料并运行预定义检查。

• 文件与附件：支持图片、PDF、DOCX、XLSX、PPTX、源码和普通文件。

• 长期记忆：保存明确的用户事实和偏好，支持审核、更新、检索与遗忘确认。

• 受控修改：项目变更先生成 diff，经过人工批准后才应用，并支持回滚。

• 本地优先：数据保存在本地，桌面端使用 Windows DPAPI 加密 API Key，模型不会直接获得任意 Shell、文件写入或网络权限。

Personal Agent 不会绕过或扩充 Codex 官方配额。它通过 MCP 把用户明确委派的工作交给 独立 Runtime 执行。

Related MCP server: agent-bridge-mcp

从源码启动

当前开发环境面向 Windows，需要 Python 3.12、Node.js 22 或更新的 LTS 版本，以及 Git。

git clone -b codex/public-preview --single-branch `
  https://github.com/lxhyk-work/personal_helper.git
cd personal_helper
Set-ExecutionPolicy -Scope Process Bypass
.\scripts\setup-windows.ps1

启动桌面应用：

cd desktop
npm start

首次启动向导会让你选择模型、输入对应 API Key 并选择实际项目目录。API Key 使用 Windows DPAPI 加密，磁盘中只保存与当前 Windows 用户绑定的密文。开发者也可以继续用环境变量：

$env:PERSONAL_AGENT_RUNTIME_PROVIDER = "deepseek"
$env:PERSONAL_AGENT_RUNTIME_MODEL = "deepseek-chat"
$env:DEEPSEEK_API_KEY = "<your-api-key>"

桌面端会启动本地 Python 服务，关闭窗口时一并停止。首次打开后可选择实际项目目录， 所有文件操作都会绑定该目录。

更完整的安装和故障排查见 GitHub 快速开始 和 Windows 源码安装。

接入 Codex

完成首次启动配置后，在桌面端“设置 > 连接 Codex”中复制为当前项目生成的 MCP 配置， 粘贴到 Codex 的 config.toml。该配置包含 MCP 命令、当前项目目录和非密钥环境参数。

源码用户也可以手动计算当前项目的本地项目 ID：

$projectId = node -e "console.log(require('./desktop/project-workspaces.cjs').describeProject(process.cwd()).id)"
$env:PERSONAL_AGENT_ACTIVE_PROJECT_ID = $projectId
$env:PERSONAL_AGENT_CODEX_TASKS_ENABLED = "true"
$env:PERSONAL_AGENT_CODEX_TASK_USER_ID = "local-user"

在 Codex 的 config.toml 中注册 MCP Server：

[mcp_servers.personal_agent]
command = "C:\\path\\to\\personal_helper\\.venv\\Scripts\\personal-agent.exe"
args = ["codex-mcp"]

把仓库中的 Skill 安装到 Codex：

Copy-Item -Recurse -Force `
  .\integrations\codex\skills\personal-agent-routing `
  "$env:USERPROFILE\.codex\skills\personal-agent-routing"

重启 Codex 后显式调用：

$personal-agent-routing 使用 Personal Agent 完成这项任务，并把结果交回 Codex 验证。

默认 Tool 和 Capability 白名单为空。需要文件读取、研究或受控修改时，必须在启动环境中 明确配置对应白名单。完整协议与权限说明见 Codex 集成协议。

CLI 与本地 API

.\.venv\Scripts\personal-agent.exe chat --session default
.\.venv\Scripts\personal-agent.exe memories list
.\.venv\Scripts\personal-agent.exe serve

除 /health 外，所有 /v1/* 请求都需要本地 Bearer Token。桌面端会自动生成并注入该 Token，普通桌面用户不需要手动填写。

开发与验证

Python：

.\.venv\Scripts\python.exe -m pytest -m "not live" -q
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m mypy src

桌面端：

cd desktop
npm install
npm run test:unit
npm run test:contract
npm run build:web

测试默认不访问真实模型。只有显式配置凭据并主动运行 live 测试时才会调用供应商 API。

当前状态

这是一个仍在开发中的本地项目。Windows portable/installer、代码签名和自动更新尚未作为 正式公开 Release 提供。从源码运行时不会包含虚拟环境、Node 依赖、数据库、附件、日志或 API Key。

第三方来源与许可证信息见 Third-party notices。