# 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 执行。

## 从源码启动

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

```powershell
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
```

启动桌面应用：

```powershell
cd desktop
npm start
```

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

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

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

更完整的安装和故障排查见 [GitHub 快速开始](docs/quickstart-from-github.md) 和
[Windows 源码安装](docs/windows-npm-usage.md)。

## 接入 Codex

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

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

```powershell
$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：

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

把仓库中的 Skill 安装到 Codex：

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

重启 Codex 后显式调用：

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

默认 Tool 和 Capability 白名单为空。需要文件读取、研究或受控修改时，必须在启动环境中
明确配置对应白名单。完整协议与权限说明见
[Codex 集成协议](docs/codex-personal-agent-task-protocol.md)。

## CLI 与本地 API

```powershell
.\.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：

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

桌面端：

```powershell
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](desktop/THIRD_PARTY_NOTICES.md)。