DeepCode P4 Code Workbench 架构解析基于 P2/P3 会话栈的桌面代码审查能力层【免费下载链接】DeepCodeDeepCode: Open Agentic Coding (Agent Harness Loop Engineering Multi-Agent Orchestration)项目地址: https://gitcode.com/GitHub_Trending/deepc/DeepCode导读本文以 DeepCode 仓库的 P4_CODE_WORKBENCH_ARCHITECTURE.md 为骨架系统讲解 P4 Code Workbench 如何在 P2/P3 已有的 Thread、Turn、Item、Approval 与本地 stdio App Server 之上新增代码审查Code Review能力文件浏览与编辑、Git 状态/差异/丢弃、隔离 worktree、Thread 专属 PTY 终端与测试发现/运行。读完本文你将掌握 P4 的服务边界划分、RPC 协议扩展、安全不变量及其源码级实现依据并了解各服务的核心行为约束、消息大小限制与验证方式可直接对照 core/application 与 app_server 继续深入。一、P4 在整体架构中的定位DeepCode 的整体架构按阶段演进P1 搭建本地 stdio App Server 与基础协议P2/P3 建立 Thread、Turn、Item、Approval 等会话与执行模型参见 P1_APP_SERVER_ARCHITECTURE.md、P2_AGENT_EXECUTION_ARCHITECTURE.md、P3_DESKTOP_RUNTIME_ARCHITECTURE.md。P4 的工作是在这条会话栈之上叠加代码审查能力让桌面端 Inspector 可以直接查看文件树、浏览 Git 变更、运行测试并在 Thread 终端中执行命令。P4 架构有三个贯穿始终的原则业务规则集中在core/application所有路径校验、权限判断、并发保护、revision 检查都放在 Python 应用层React 前端不直接访问文件系统、Git 或 shell。React 保持哑客户端前端只消费 RPC 返回的结构化数据不复制业务规则。Rust bridge 不复制规则Rust 侧只负责消息传输与 sidecar 生命周期不实现文件、Git、终端等业务判断。也就是说P4 的所有新增能力都通过本地 App Server 暴露为协议方法前端与 Rust 只是通道。二、服务边界五个核心服务与各自的职责P4 把代码审查能力拆分为五个服务全部位于 core/application职责边界非常清晰2.1 WorkspaceService一切路径操作的共同边界WorkspaceService是所有文件系统访问的守门人其resolve方法见 workspace_service.py完成四层校验Project/Thread 存在性校验通过ThreadRepository与ProjectRepository加载 Thread 与 Project缺失即抛ThreadNotFoundError/ProjectNotFoundErrortrust 校验需要 trusted 的操作写文件、discard、worktree 变更、终端、测试运行通过require_trustedTrue强制要求project.trust_state is TrustState.TRUSTED否则抛ProjectNotTrustedErrorcanonical root 校验Thread 的workspace_path经Path.expanduser().resolve(strictTrue)规范化并确认是目录若 Thread 不拥有 worktree还必须root.is_relative_to(project_root)防止 workspace 越出项目边界WorkspaceOutOfScopeErrorowned worktree 校验若 Thread 拥有 worktree则要求root worktree且worktree/.git存在即路径必须是真实注册的 Git worktree而不是任意目录。path方法workspace_service.py负责把 UI 提供的相对路径映射为物理路径拒绝绝对路径、包含..的路径、包含 NUL 字节的路径candidate.resolve(strictTrue)后再做一次is_relative_to(context.root)检查无论是否存在 symlink 指向 workspace 之外最终解析结果都必须留在 workspace 根之内对尚不存在的目标如新建文件则先解析父目录再拼接文件名同样做边界检查。这是安全不变量 #1 和 #2UI 路径永远是 workspace-relative、canonicalization 只在后端执行的落地实现。2.2 FileService有界目录树 UTF-8 小文件 SHA-256 乐观编辑FileServicefile_service.py只做三类事有界目录树list方法限制depth在 18、limit在 1750MAX_TREE_ENTRIES 750排序优先目录后文件、忽略.git目录扫描超限即标记truncatedUTF-8 小文件读取read方法默认只读 128 KiBDEFAULT_READ_LIMIT MAX_READ_LIMIT 128 * 1024发现 NUL 字节或非法 UTF-8 即抛BinaryFileError确保只返回文本文件截断的文件不计算 SHA-256sha256None if truncated即截断内容不返回可写 revision防止前端基于不完整内容发起覆盖写原子小范围编辑write方法要求内容不超过MAX_EDIT_BYTES 128 * 1024通过同目录NamedTemporaryFile写入、fsync、os.replace原子替换、再fsync目录实现崩溃安全落盘。write的乐观并发控制值得单独强调对已存在文件必须提供expected_sha256若与当前内容哈希不一致则抛FileChangedErrorfile changed since it was read实现旧视图不能覆盖新内容安全不变量 #3对不存在的文件若带了expected_sha256则视为目标已消失写入前后还会二次比对哈希防止保存期间文件被并发修改活动 Turn 期间禁止编辑TurnRepository.active_for_thread(thread_id)非空即抛ConflictError避免与 Agent 执行中的文件操作冲突。2.3 GitService只返回结构化 status/diffdiscard 必须提交 revisionGitServicegit_service.py把所有 Git 交互封装成三类操作status调用git status --porcelainv1 -z --branch --untracked-filesall解析出GitStatusEntrypath、original_path、index_status、worktree_status、kind并支持_parse_branch_header处理 detached HEAD、No commits yet 等边界diff支持scope为all/staged/working三种对 untracked 文件直接读取内容构造新文件hunk对 tracked 文件调用git diff --no-ext-diff --no-color --find-renames --unified3 [--cached|HEAD]并解析成结构化的FileDiff/DiffHunk/DiffLine每个 FileDiff 通过_attach_revision附带一个基于 path、status、binary 标记与 patch 内容计算的 SHA-256 revisiondiscard逐文件执行前置条件非常严格必须require_trustedTrue且 Thread 无活动 Turn重新调用diff获取当前变更要求恰好命中 1 个文件提交的expected_revision必须与后端重新计算的 revision 一致否则抛FileChangedError——这是逐文件 discard 必须提交该 revision并在后端重新计算后才允许执行的实现untracked 文件直接删除unborn 仓库无 HEAD用git rm --cached加删除正常情况用git restore --sourceHEAD --staged --worktree恢复。revision 机制保证了旧视图不能覆盖新内容这一安全不变量在 Git 侧同样成立UI 看到某个 diff 后若文件在审查期间被改动discard 会因 revision 不匹配而被拒绝。Git 输出还有硬上限MAX_GIT_OUTPUT 8 MiB含逐文件 diff 累计、MAX_DIFF_FILES 500、MAX_DIFF_LINES 4000、MAX_DIFF_TEXT_BYTES 256 KiB任何一项超限都会抛出InvalidArgumentError且通过 drain 线程在超限时直接 kill 子进程避免 sidecar 因超长输出卡死。2.4 WorktreeService确定性 sibling 目录 专属分支 ownership manifestWorktreeServiceworktree_service.py为 Thread fork 出来的并行 Turn 提供隔离 workspace确定性路径worktree 一律创建在项目父目录下的.projectName.deepcode-worktrees/threadId分支固定为deepcode/threadId要求项目即 Git rootgit rev-parse --show-toplevel必须等于 project canonical path否则拒绝创建保证 sibling 目录可控ownership manifest每次创建在.projectName.deepcode-worktrees/.deepcode-manifests/threadId.json写入包含version/threadId/projectId/repositoryRoot/worktreePath/branch的清单清理时必须校验数据库归属Thread 记录、managed path必须是期望路径、branchgit worktree list --porcelain注册分支与git branch --show-current实际分支都必须等于deepcode/threadId和 manifest 四者一致绝不根据目录名猜测所有权安全不变量 #5脏 worktree 必须显式 forceremove的disposition只允许keep或cleanclean时若git status --porcelain非空且未传forceTrue则抛ConflictError活动 Turn_require_idle或 Thread 终端仍存活_terminal_activity都会阻止清理reclaim 逻辑若 worktree 目录与.git存在但 Thread 记录未注册只要 manifest 匹配、分支匹配就回收使用否则报 ConflictError。2.5 TerminalServiceThread 专属 PTY有界增量输出不写 durable event logTerminalServiceterminal_service.py管理 Unix PTY 终端Thread 专属每个 terminal 绑定thread_id_owned校验 terminal 必须属于发起 Threadcreate时以 workspace 为cwd、start_new_sessionTrue建立独立进程组shell 取$SHELL无则/bin/sh并注入DEEPCODE_THREAD_ID环境变量大小与输入输出上限窗口行列校验在 20500 列、5200 行write单次输入上限 64 KiB输出读取循环每次最多 16 KiB 并增量发布terminal.output通知不写 durable event log输出通过订阅-发布subscribe/unsubscribe直接推送给 App Server 写入 stdout 通知不落入持久化事件仓库退出清理进程退出后发布terminal.exit带 exitCodeclose_all在应用退出时终止所有会话_terminate先killpg(SIGTERM)0.75 秒后未退出再killpg(SIGKILL)清理 worktree 前若 terminal 仍活跃会被拒绝set_terminal_activity_check注入的回调Windows 平台PTY 路径需要 Windows ConPTY 适配器当前实现直接抛NotSupportedApplicationError并在文档中说明适用前提是 Unix 环境。2.6 TestService只暴露探测到的白名单命令结果落为 durable TestResult ItemTestServicetest_service.py与 core/verification.py 配合探测而非猜测discover_verification_commands只从仓库真实标记中探测——有pytest.ini/pyproject.toml/setup.cfg/tests目录则暴露pytest根目录存在test_*.py/*_test.py且导入 unittest 则暴露unittestpackage.json有非空testscript排除 no test specified则暴露npm test存在Cargo.toml则暴露cargo test运行条件test/run要求 trusted Project、指定turn_id必须属于该 Thread 且当前无活动 Turn有界输出stdout/stderr 各自只保留最后 64 KiBMAX_VERIFICATION_OUTPUToutput_truncated标记截断超时范围限制在 11800 秒超时后killpg终止持久化运行结果写入ItemKind.TEST_RESULT成功为ItemStatus.COMPLETED、失败为FAILEDpayload 携带 command、exitCode、timedOut、durationMs、stdout、stderr并通过item.created事件广播——测试结果成为会话历史的一部分。三、协议与 UIRPC 扩展与方法清单3.1 Canonical schema 新增的 P4 方法P4 在协议层新增四组方法完整方法常量见 app_server/protocol/methods.pyfile/list git/status terminal/create file/read git/diff terminal/write file/write git/discard terminal/resize git/worktree/create test/discover terminal/close git/worktree/remove test/run对应的协议 schema 定义位于 protocol/app-server.schema.json。所有方法都由 app_server/server.py 的Dispatcher分发给五个服务。3.2 消息与数据硬上限文档明确的大小约束在源码中可逐条验证约束数值源码位置App Server 单条消息上限1 MiBcodec.pyDEFAULT_MAX_MESSAGE_BYTES 1024 * 1024文件读取/写入128 KiBfile_service.py测试 stdout/stderr 各保留最后 64 KiBverification.pyMAX_VERIFICATION_OUTPUT结构化 Diff 文件数500git_service.pyMAX_DIFF_FILES结构化 Diff 行数4000git_service.pyMAX_DIFF_LINES结构化 Diff 文本字节256 KiBgit_service.pyMAX_DIFF_TEXT_BYTES超限时的降级行为若请求或响应超过 1 MiBApp Server 返回稳定的RESPONSE_TOO_LARGE错误码-32004stable_codeRESPONSE_TOO_LARGE并继续服务不会让 sidecar 因超长行退出——对应 server.py 的_write_response逻辑对超长请求还会_discard_remainder丢弃本行剩余内容再继续读下一行。事件回放event/replay则通过二分查找切出最大可装入单条消息的 cursor 页_fit_replay_response保证大历史也能分页送达。3.3 UI 层消费与按需加载Inspector 的Changes、Files、Tests、Terminal四个标签全部消费真实 RPC 数据而非 mockChanges →git/status、git/diff、git/discardFiles →file/list、file/read、file/writeTests →test/discover、test/runTerminal →terminal/create、terminal/write、terminal/resize、terminal/close。Monaco 与 xterm 均按需加载常规首屏 bundle 不包含编辑器和终端运行时代码降低启动体积。Thread forkthread/fork随后为并行 Turn 创建 owned worktree使各 Turn 在隔离 workspace 中执行。四、安全不变量七条规则的源码对应文档列出七条安全不变量逐条可找到实现证据UI 提供的路径永远是 workspace-relativecanonicalization 只在后端执行→ workspace_service.pypath()拒绝绝对路径与..所有resolve在后端完成symlink 不能把读取、写入或 discard 导向 workspace 之外→ 同上resolved.is_relative_to(context.root)二次校验FileService.list用follow_symlinksFalse标记 symlink 类型写文件和 discard 都使用 optimistic revision旧视图不能覆盖新内容→ file_service.py 的 SHA-256 校验、git_service.py 的 revision 比对discard 仅处理明确选择的文件并由 UI 二次确认worktree force clean 另有独立确认→ discard 只接受单个path且后端重新计算 diff 恰好命中一个文件force 作为显式参数worktree_service.pyUI 侧还需独立弹窗worktree 清理同时校验数据库归属、managed path、branch 和 manifest不根据目录名称猜测所有权→ worktree_service.py_require_manifest四要素比对PTY 和 test subprocess 使用显式cwd不调用全局os.chdir()→ terminal_service.py 与 verification.py 均以cwdroot启动子进程Terminal input、Git output、文件内容、目录项和 test output 均有硬上限→ 64 KiB 输入、8 MiB Git 输出、128 KiB 文件、750 目录项、64 KiB 测试输出的常量定义。此外写文件、discard、worktree 变更、test/run、terminal/create 均要求trusted Project把代码审查能力限制在用户显式信任的仓库内参见 project_trust.py 的 trust 流程。五、验证证据测试如何覆盖这些边界P4 的验证证据在仓库中有大量对应测试5.1 应用层组合测试tests/application/test_p4_code_workbench.py 覆盖test_file_tree_read_and_optimistic_edit_stay_inside_workspace——文件树与乐观编辑的 workspace 边界test_file_read_truncates_on_a_utf8_boundary_without_hashing_partial_content——UTF-8 截断边界与截断内容不返回可写 revisiontest_git_status_and_diff_include_tracked_and_untracked_files、test_git_diff_handles_unborn_repositories_renames_and_deletions——unborn 仓库、rename、delete 等 diff 边界test_worktree_lifecycle_requires_explicit_dirty_cleanup、test_worktree_recreates_a_missing_registered_path_only_with_its_manifest——脏 worktree 显式 force 清理与 manifest reclaimtest_terminal_is_thread_owned_and_emits_output_and_exit——PTY ownership 与输出/退出通知test_allowlisted_test_run_creates_durable_test_result_item、test_test_discovery_requires_a_real_npm_script_and_bounds_failure_output——白名单测试发现与输出截断。5.2 App Server 协议层测试tests/app_server/test_p4_server.py 覆盖test_p4_file_git_and_terminal_protocol_round_trip——file/git/terminal 方法完整 RPC 往返test_oversized_result_returns_a_protocol_error_without_stopping_server——超限响应返回RESPONSE_TOO_LARGE且服务器继续服务test_event_replay_is_split_into_byte_bounded_cursor_pages——事件回放按字节边界分页。5.3 前端与 Rust 侧验证React TypeScript、ESLint、5 项 Vitest 与 production build 通过慢旧 Thread 请求不能覆盖当前 Inspector 的竞态保护在桌面端测试中有对应覆盖Rust fmt、单元测试与 clippy-D warnings通过PyInstaller sidecar 与 macOS arm64DeepCode.apprelease bundle 构建通过并从 bundle 内 sidecar 实测file/read、git/diff、PTY 与 graceful shutdown。文档记录 P4 组合共51 项通过这些边界场景——UTF-8 截断、symlink fence、stale SHA/Diff revision、unborn repository、rename/delete/untracked discard、manifest reclaim、脏 worktree、PTY ownership、test output truncation 与 oversized RPC response recovery——正是 P4 安全不变量能被持续验证的关键。六、总结与延伸阅读P4 Code Workbench 的核心贡献可以概括为在既有会话模型之上用五个职责单一的服务 一组受限 RPC 方法 七条可验证的安全不变量把代码审查这一桌面功能完整装进了业务规则只在 core/application、前端与 Rust 不复制规则的架构约束中。对使用者和二次开发者而言理解WorkspaceService的路径围栏、FileService/GitService的双重乐观 revision、WorktreeService的四要素归属校验是安全使用该能力的前提。继续深入可参考架构总览README.md、README_ZH.md分层架构P2_AGENT_EXECUTION_ARCHITECTURE.md、P3_DESKTOP_RUNTIME_ARCHITECTURE.md、P4_CODE_WORKBENCH_ARCHITECTURE.md协议 schemaprotocol/app-server.schema.json核心实现core/application/workspace_service.py、file_service.py、git_service.py、worktree_service.py、terminal_service.py、test_service.py协议层app_server/server.py、app_server/protocol/methods.py测试证据tests/application/test_p4_code_workbench.py、tests/app_server/test_p4_server.py【免费下载链接】DeepCodeDeepCode: Open Agentic Coding (Agent Harness Loop Engineering Multi-Agent Orchestration)项目地址: https://gitcode.com/GitHub_Trending/deepc/DeepCode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
