企业官网建设流程全解析

Pinvou Agent 代码模式实战：通过 ACP 在同一工作台驱动 Codex、Claude Code 与 Kimi

【免费下载链接】pinvou-agentOpen-source desktop AI agent for tools, files, knowledge, workflows, and real deliverables.项目地址: https://gitcode.com/gh_mirrors/pi/pinvou-agent

Pinvou Agent 是一款开源的桌面 AI 智能体工作台，它的"代码"模式基于 ACP 协议，让你用同一套界面驱动 Codex、Claude Code 与 Kimi 三大编码智能体：真实项目目录、权限确认、计划与工具步骤、会话恢复全部开箱即用，无需在终端和 IDE 之间来回切换。

同一个工作台：三种模式、四个编码智能体

Pinvou Agent 的主页输入框上方提供"工作 / 设计 / 代码"三种模式切换。切到"代码"后，输入框下方可以直接选择编码智能体：🤖Codex、🟠Claude Code、🅺Kimi（三者走 ACP 链路），另有品悟原生代码会话可选手动选择。

三类会话按最近更新时间混排在左侧统一会话列表中，以各自的 Agent 图标区分，不再占用单独的侧边栏入口。也就是说，你可以在同一个界面里继续昨天用 Claude Code 改的 bug，又能新开一个 Codex 会话处理另一个项目。

详细对照表见 docs/multi-agent-acp.md

ACP 代码模式新手使用：从选择目录到发送首条消息

上手只需要四步：

1. 进入代码模式：主页切换到"代码"，选择 Codex / Claude Code / Kimi 之一；
2. 选择工作区：输入框左下角默认"临时会话"（Agent 在隔离目录干活）；也可以选择项目目录——Agent 的进程 cwd、session/new和session/load都使用该真实项目目录；
3. 首次发送自动建会话：直接发送首条消息时才创建会话，避免只切换模式就产生空记录；
4. 流式接收结果：思考、工具步骤、计划、权限选择、停止生成、会话恢复全部可用。

同一项目可以创建多个独立会话；会话开始后不能更换目录，需要切换项目时新建会话即可。

CLI 一键安装与升级：缺失自动装、过旧自动升

这是 ACP 方案对新手最友好的地方。Pinvou 对三个 Agent 走同一套探测流程：先探测本机 CLI（PATH与常见安装位置），再对照官方 latest 来源判断版本。

• CLI 缺失：经你确认后，自动调用官方安装脚本完成用户态安装（无需管理员权限），装到用户目录；
• 版本过旧：先判定安装来源（Homebrew / npm 全局 / 官方脚本），再按来源用对应包管理器或脚本升级，避免同一 CLI 多来源并存；
• 国内网络兜底：官方脚本源不可达且系统存在 npm 时，安装动作自动降级为 npm 全局安装。

安装升级的实现位于 install.rs，对应的应用层命令install_acp_agent定义在 codex.rs。整个过程不静默执行外部命令，也不会创建 Pinvou 托管的 CLI 副本；Bridge 本体（隔离 Node + JS 适配器）随安装包自带，不要求你系统安装 Node/npm。

为什么 ACP 能统一驱动三个编码智能体？

ACP（Agent Client Protocol）的核心思想：宿主应用负责"壳"，Agent 负责"脑"。

• Pinvou 负责：进程托管、ACP transport、session/workspace 绑定、事件持久化、权限交互与 UI；
• Agent 自己负责：system prompt、模型、工具循环、skills、MCP、登录态与自身配置。

前端只消费 Agent 在initialize、session/new、session/load中实际上报的 capability、model、mode 和配置项，不按 Agent 名称猜能力。三个 ACP Agent 共用同一条acp-timeline.jsonl时间线和工作区安全边界，不复制三套界面逻辑。这意味着新 Agent 只要支持 ACP，就能以几乎零成本接入同一个工作台。

会话事件在前端被投影为结构化时间线（思考、命令执行、文件变更、权限、计划、Agent 消息），原始 ACP JSON 不会进入普通会话界面。投影逻辑见 acp-state.js，ACP 会话的完整实现集中在 features/codex/ 目录。

权限确认与会话恢复：新手最关心的两个问题

权限模式如何工作

权限模式以 ACPconfig_options.mode为主，只有 Agent 未上报该配置时才回退到session/set_mode。你确认过的权限模式、模型、推理强度等配置会按 Agent 持久化：新建该 Agent 会话时自动重新应用；历史会话仍使用自己的 session 配置，不会被新会话的默认值覆盖。配置应用期间和回合运行期间会暂停另一项配置修改，避免状态冲突。

重启后不会"卡在处理中"

应用被直接关闭时，旧进程里的 Prompt 无法挂回新进程。Pinvou 的启动恢复会把时间线中只有turn_started没有turn_completed的遗留回合收口为Interrupted，对应运行中的工具、权限和输入项显示为已取消。恢复后的会话保留原历史和工作目录，可继续发送新消息——这是桌面端长任务场景下非常实用的容错设计。

Provider 管理：为编码智能体配置第三方中转

三个 ACP Agent 都支持在设置 →「Provider 管理」中配置第三方中转：预设/自定义 base URL、wire 协议（Anthropic 兼容 / OpenAI 兼容）、模型与 API key，也可以一键恢复官方登录。

几点新手须知：

• 🔑 API key 只存系统凭据库（keyring），JSON、日志和仓库中都没有明文；
• ⚠️ 切换 Provider 是本机级操作，会影响所有使用该 CLI 的入口（终端、IDE 插件），不只是 Pinvou 代码模式；
• 每次受管写入前原配置会备份为*.pinvou3-bak；配置文件不可解析时拒绝覆盖并明确报错；
• 会话级解析优先级：会话选项 > 全局当前 Provider > 官方登录。

源码与文档索引：想深入可以看的模块路径

• 使用、验证与发布（含数据位置与 Provider 管理）：docs/codex-acp.md
• 多 Agent 架构单一真相源（CLI 探测、安装矩阵、架构边界）：docs/multi-agent-acp.md
• 品悟原生代码会话的设计决策：docs/code-native-agent.md
• 前端 ACP 时间线投影与会话操作：pinvou3-app/src/features/codex/
• 后端 ACP 运行时与安装升级：pinvou3-app/src-tauri/src/features/codex_acp/

会话数据统一存放在~/.pinvou3/sessions/<id>/下（acp-state.json、acp-timeline.jsonl等），项目目录本身零污染——时间线、状态和会话文件都不会写进你的仓库。

总结

Pinvou Agent 的代码模式证明了一件事：多编码智能体不需要多套入口。通过 ACP 这一层统一协议，Codex、Claude Code 与 Kimi 以完全一致的心智模型运行在同一工作台：统一的会话列表、一致的权限交互、可靠的崩溃恢复，再加上免 Node 依赖的内置 Bridge 与一键安装升级，让新手也能在几分钟内把最合适的编码智能体接入真实项目。

如果你希望从源码运行，克隆仓库后按文档执行./pinvou3-app/scripts/prepare-codex-bridge-runtime.sh准备 Bridge，再运行./pinvou3-app/run-dev.sh启动即可：

git clone https://gitcode.com/gh_mirrors/pi/pinvou-agent cd pinvou-agent/pinvou3-app ./scripts/prepare-codex-bridge-runtime.sh ./run-dev.sh

【免费下载链接】pinvou-agentOpen-source desktop AI agent for tools, files, knowledge, workflows, and real deliverables.项目地址: https://gitcode.com/gh_mirrors/pi/pinvou-agent