01 / 背景与目标
编程任务需要反复读代码、定位问题、修改文件和运行检查。Bit Agent 把这条链路做成可追踪的桌面工作流：模型负责分析并提出工具调用，OpenAI Agents SDK 负责模型与工具的循环，产品代码负责权限、持久化和修改后的验证。1.0 版本加入内置终端与浏览器，Agent 可在授权后操作网页。
02 / 核心实现
分层架构与事件流
Electron 提供界面，Fastify Gateway 经进程管道以 JSON Lines 驱动本地 Python AgentRuntime；执行事件通过 SSE 推送，断线后按游标续传。
只读多 Agent 调查
支持关闭、开启、智能三种模式。子 Agent 只有列目录、读文件、搜代码三类工具，每批最多 3 个、每轮最多 2 批，不能递归委派；主 Agent 汇总证据后统一修改。
Token 预算与分层记忆
输入超过可用预算的 75% 时，把较早的事件组摘要到 60%，工具调用与结果成对保留；过大的工具输出外置保存并记录 SHA-256。会话、工作记忆与长期经验存于本机 SQLite，重启后可续聊。
写入授权与沙箱验证
写文件前展示差异并等待授权，批准前不落盘；任务结束后可审阅、撤销，或只提交本次任务的文件。测试与检查在 Windows OS 沙箱的工作区副本中运行：禁网、只能写工作区、不能改 .git 与验证配置。
MCP 工具与浏览器自动化
主 Agent 可接入 stdio / HTTP MCP Server，按服务逐次确认，密钥经 Windows 加密存储。内置浏览器通过本机 MCP 服务开放给 Agent：读取与截图无需审批，点击和输入逐次确认，拒绝向密码框输入，网页内容一律标为不可信数据。
03 / 技术取舍
为什么子 Agent 只读
apply_patch 不在子 Agent 的工具 Schema 中，模型即使申请也会被框架拒绝。并发调查提高取证效率，单点写入避免多个 Agent 同时修改同一个文件。
为什么在客户端压缩上下文
不依赖服务端保存 previous_response_id，可对接不同的 OpenAI 兼容服务。摘要失败或不符合 Schema 时保留原历史；超过硬上限即明确停止，不带着残缺摘要继续执行。
为什么验证只追究新增问题
检查失败时，在私有副本中把本轮改动的文件还原为修改前内容再跑一次，逐条对比 pytest 失败编号与 Ruff 问题数，只把新增项判为失败；没有可运行的检查时标记为“无法验证”。任务能否结束取决于检查结果，而不是模型的自我报告。
为什么独立验收按改动规模触发
实测一次约 6 分钟的任务中，跑测试约 20 秒，验收 Agent 调用模型约 3.5 分钟。因此默认在本轮改动达到 60 行或涉及 3 个以上代码文件时才验收，小改动通过基础检查即可结束，并写明跳过原因。
为什么不依赖 Redis 和 Docker
桌面单机场景下，Gateway 经进程管道直接调用 Python，SQLite 负责持久化；测试与检查从 Docker 迁到 Windows OS 沙箱，用户无需额外启动服务。沙箱不可用时记为“无法验证”，不退回普通进程执行。
04 / 处理流程
- 桌面或命令行提交任务，可附图片
- Gateway 接收并转交本地执行服务
- 按会话恢复历史、工作记忆与长期经验
- Agents SDK 执行工具循环，按需委派只读子 Agent 或调用 MCP 工具
- 写入前授权，修改后沙箱验证，事件与结果回传界面
05 / 验证与数据
| 项目 | 结果 |
|---|---|
| GitHub Actions | 最新提交 03ddaa7（2026-10-07）CI 通过 |
| 自动化测试 | Python 697、Desktop 353、Gateway 68 项通过；lint、类型检查与 JS / Python 分层规则通过。跳过项需要真实模型、PostgreSQL 或显式启用的 OS 独立验收 |
| 沙箱安全回归 | 真实沙箱 SDK 13 项通过：并发任务互不写入、验证配置不可写、错误标记不可伪造、加固后无法写入工作区以外 |
| 打包 exe 端到端验收 | 启动真实 exe，走通流式回答、写文件授权、图片粘贴与历史恢复、改动审阅；深浅色、两种宽度共 32 种布局检查通过。2026-10-06 起另含内置终端、浏览器，以及 Agent 打开网页、读取、输入和截图的流程 |
测试数字取自 2026-10-05 验收记录，沙箱回归取自 2026-10-04 记录。端到端验收使用本地模拟模型，不代表在线模型的实际效果；沙箱依赖的官方 sandbox-runtime 对 Windows 的支持仍为 alpha。
06 / 当前边界
目前在 Windows 上开发与验证；尚未提供代码签名安装包、Web 管理后台与生产级认证。