如何使用 AI Agent 管理大型项目

Agent 管理大型项目：DeepSeek Harness 与外部实践研究

研究日期：2026-08-29 范围：本仓库 ai-research/deepseek-harness/ 的源码与文档；企业官方技术资料；开源项目官方文档、仓库与论文。 证据原则：项目自身结论优先引用仓库中的 README、AGENTS.md、测试和设计文档；外部结论优先引用官方文档、官方博客、官方仓库或论文。没有把营销材料中的效果数字当作独立验证结果。

摘要

大型项目中的 Agent 管理，核心不是让一个模型拥有更长上下文，而是把工作组织成可追踪、可隔离、可验证、可恢复的执行单元。deepseek-harness 的做法尤其完整：父 Agent 通过统一的 subagent 服务委派任务；短任务使用 one-shot，长任务使用可继续的后台子 Agent；大量独立任务使用脚本化 workflow 的 parallel()/pipeline()；Todo、Session Log、Checkpoint 和投影把计划、状态和恢复做成持久数据；工具过滤、深度上限、模型路由、审批和沙箱控制权限与风险。

对外部实践的比较显示出相同的收敛方向，但侧重点不同：GitHub 把 Agent 嵌入 Issue→Branch→Draft PR→CI/Review 的软件交付闭环；Google DeepMind 的 AlphaEvolve 用“模型提出程序—自动评估—程序库进化”管理算法搜索；Microsoft AutoGen 提供显式团队拓扑、选人/轮转/交接和终止条件；OpenHands 把可委派 Agent、远程隔离工作区、持久会话和可观测性做成 SDK；SWE-agent 强调为模型设计可控的计算机接口；MetaGPT 把软件公司的角色与 SOP 编码进多 Agent 流水线。

另外，OpenAI 的 Harness Engineering/Symphony、Google Jules 和 AWS Amazon Q for GitHub 展示了更接近企业项目运营的形态：看板或 Issue 是调度入口，规范文件是版本化控制面，独立 workspace 承载执行，PR/CI/审查承担交付闸门。它们也共同表明，主动式、长时间运行的 Agent 仍应以“建议或草稿→验证→人工批准”为默认升级路径。

可迁移的结论是：先以单 Agent 加可靠工具和测试为基线，再按独立性进行扇出；每个子任务必须有明确输入、输出和验收器；把中间状态写入事件或外部工作对象；通过分支/工作区隔离并用 PR、测试、评估器或人工批准合并；对长任务提供暂停、继续、取消、恢复和审计；将权限、成本、并发、递归深度和失败策略作为系统配置，而不是隐藏在提示词中。

一、DeepSeek Harness 的管理模型

1. 用能力接缝组合，而不是把所有逻辑塞进 Agent Loop

仓库的 AGENTS.md 将 subagent/ 定义为“服务定义 + 提供方 + 委派消费者”，并将 workflow/、session/、todo/、interaction/、guard/、shell/ 等作为独立能力组。这意味着管理大型任务的关键控制面位于 Agent Loop 外部：委派、持久化、权限、交互和执行环境都可以替换或组合，而不必重写推理循环。

证据：AGENTS.md、CLI composition。

2. 父子层级：统一委派协议，多种后端

@deepseek-ai/dsh-subagent 对外提供统一的 ctx.subagents 服务，后端可以是进程内子 Agent、进程外 ACP/SDK Agent，或 Codex/Claude Code 等真实外部 Agent。子 Agent 有两种生命周期：

• one-shot：前台等待一次最终结果，适合小而封闭的子任务；也可作为普通后台任务运行，再通过任务接口收集或取消。
• continuable：后台创建拥有持久 Session 的子 Agent，返回稳定的 child id；父级可以 FIFO 地发送后续消息或中断当前轮次，子 Agent 结束时由运行时向父级发送结算通知。

委派工具通过 persona、toolFilter、agentOptions、模型/推理等级和 maxDepth 进行子级隔离与限制。工具描述还根据子级是否继承父级上下文而变化，避免模型错误假设自己看到了父级对话。

证据：subagent README、tool-subagent README。

3. 父到子控制、子到父报告、树状发现分离

dsh-tool-subagent-control 只负责父到子方向：send_message、interrupt_agent 和 list_agents。send_message 返回被接受的稳定 messageId，不假装同步拿到子级回复；interrupt_agent 只停止当前轮次，保留队列和后代；list_agents 按 children 或 descendants 展示可继续子 Agent 的持久化树。子到父方向由独立的 dsh-tool-subagent-report 负责，且接收方从持久化的 parentSession 推导，子级不能伪造收件人。

这种拆分把“控制权”和“结果回传”分离，减少跨层级越权，也让没有控制需求的部署可以不加载控制工具。它同时明确承认异步系统的现实：列表是快照，不是投递保证；排队消息没有独立结果；当前轮次不能被后续消息重定向。

证据：subagent control README、subagent report README。

4. 大量独立任务：脚本化 workflow，而不是让模型逐个手工调度

dsh-workflow 允许模型提交 JavaScript 编排脚本，脚本调用 agent()、parallel()、pipeline()、phase() 和 log()。宿主为每次运行建立一个 worker，子 Agent 都归属于调用 Agent；工作流最终返回一个 JSON 值，子 Agent 的中间 transcript 不直接灌入父级上下文。运行有 maxConcurrentAgents、maxTotalAgents、maxItemsPerCall、同步超时和 dispose 宽限期等上限。

这里的管理抽象是“声明任务图，宿主负责执行和归因”：格式错误、无效路由、超限和 hook 误用会显式失败；普通子 Agent 失败可映射为 null，由脚本决定是否继续。worker/vm 不是安全边界，仓库明确要求不可信脚本使用独立进程或容器。

证据：workflow README、worker-thread README。

5. 用 Todo 管理意图，用 Session Log 管理事实

dsh-tool-todo 要求模型每次提交完整 Todo 表，条目只有 pending、in_progress、completed 三种状态；列表归属于单个 Agent Session，写入 todo/write 事件，并由 projection 提供给 UI 和恢复流程。是否允许多个 in_progress 条目是部署策略：有并行工作时开启，没有并行需求时关闭。仓库刻意不把该策略硬编码进持久化不变式，因此同一日志仍可回放。

这形成了一个重要区分：Todo 是 Agent 对“下一步要做什么”的声明；Session Log 是系统对“发生了什么”的事实记录。二者不能互相替代。

证据：tool-todo README。

6. 以语义检查点处理长任务、崩溃和未知副作用

dsh-session-checkpoint-policy 在三个时刻强制持久化：模型请求交给适配器之前、顶层工具体执行外部副作用之前、以及下一步请求生成前的 step boundary。检查点失败时 fail-closed，不运行模型适配器或工具体。若恢复时发现已有工具调用但没有结果，系统记录 TOOL_OUTCOME_UNKNOWN，不自动重试，因为无法证明外部副作用是否已经发生；副作用工具应在支持时使用调用 idempotency key。

这不是“至少一次执行”的承诺，而是“执行意图与已观察结果可审计、未知状态不被伪装成成功”的承诺。

证据：session checkpoint policy README、semantic checkpoint test。

7. 测试、快照和不变式是 Agent 管理闭环的一部分

仓库的测试不仅验证函数结果，还验证持久 Session、Agent Team 的 peer mail、依赖任务、等待与 Lead 汇总、子 Agent 结算、上下文继承和检查点恢复。AGENTS.md 还规定“model-visible 等价于 logged”：任何进入模型请求的输入都必须能从 Session Log 重建。这让调试、回放和审计拥有同一真源。

证据：headless expected tests、AGENTS.md。

二、外部企业与开源实践

GitHub：把异步 Agent 纳入现有交付控制面

GitHub Copilot coding agent 的官方流程是：从 Issue 或自然语言任务开始，创建 branch 和 draft PR，在 GitHub Actions 提供的隔离环境中探索仓库、分解 checklist、修改代码、运行测试，并将结果留给人审阅。开发者可以通过 PR 反馈让 Agent 继续迭代；分支保护和 CI/CD 规则继续生效，而且官方说明 Agent 的 PR 在触发 CI/CD 工作流前需要人工批准。

GitHub 后续又把自审、代码扫描、secret scanning、依赖漏洞检查和 custom agents 纳入流程。custom agents 用仓库中的配置文件编码团队惯例，使“团队如何做事”成为可版本化配置，而不是依赖每次 prompt 的记忆。

这是一种强治理的异步协作模型：Issue 是输入，branch/PR 是工作对象，Actions 是执行环境，测试/扫描是自动验收器，人类 review 是合并闸门。

证据：GitHub 官方发布、Issue 到 PR 的官方流程、自审与安全扫描。

GitHub 还在官方文档中介绍了 Agentic Workflows：用 Markdown 描述 Issue 分类、优先级、状态报告、CI 失败调查和文档维护等自动化；front matter 声明触发器、权限和安全输出，系统将其编译为加固后的 lock workflow。官方文档说明这类工作流通常产生可审查的 Issue、评论或 PR，并采用只读 token 和显式 safe output 来限制写入面。

证据：GitHub Agentic Workflows、Copilot cloud agent。

OpenAI：Harness Engineering 与 Symphony 的“任务单驱动”调度

OpenAI 官方文章将 Harness Engineering 描述为：工程师主要设计工具、规范、测试和反馈回路，让 Agent 在大型代码库中持续执行；工程师的工作重心从手写每一行代码转向设计可供 Agent 工作的系统。其开源 Symphony 进一步把 Linear 看板变成 Agent 控制面：持续读取开放任务，为每个任务分配独立 workspace，通过版本化的 WORKFLOW.md 传入项目规则，调度器负责认领、并发上限、重试、状态协调和重启恢复，Agent 负责实现、测试、处理 CI 和审查反馈。

这类架构把“聊天线程”降级为执行细节，把任务单、工作区、规范和 PR 变成可重启的系统状态。边界是 Symphony 官方仍将其定位为面向可信环境的工程预览，且不替代工单写入、审批或沙箱策略。

证据：Harness Engineering、Symphony 官方仓库、Symphony SPEC。

AWS：实现 Agent 与审查 Agent 分离

Amazon Q Developer for GitHub 以 Issue label 或 /q dev 评论触发开发 Agent，Agent 实现功能或修复缺陷并创建带摘要的 PR；/q review 触发独立审查流程，审查结果以线程化问题、质量和安全意见出现，开发者选择是否让 Agent 生成修复并提交。新的反馈可以继续作用于同一 PR。

这里的关键不是角色数量，而是把“写代码”和“评价代码”分成不同的权限与决策点。官方同时列出 Preview、区域处理、管理员授权和审查不会因每次后续提交自动重跑等限制，因此不能把一次 Agent 审查当作持续正确性的证明。

证据：Amazon Q Developer for GitHub 官方文档。

Google Jules：维护型 Agent Pod 与主动式工作

Google 官方介绍的 Jules 会把代码库复制到安全的 Google Cloud VM，在后台执行写测试、开发功能、修复缺陷和依赖升级；完成后展示计划、推理和 diff，并支持并发任务与 GitHub 集成。后续官方文章介绍了按日运行的 Jules pod，分别负责性能优化、安全补丁、无障碍改进和测试覆盖率提升，也介绍了读取部署日志、生成修复并创建 PR 的主动式流程。

其管理方法适合把大型项目的维护债务拆成窄职责、周期性、可验证的队列。官方仍将 Suggested Tasks 标为实验性，并保留审查、批准或忽略建议的人工路径，因此主动运行不等于自动发布。

证据：Google Jules、Jules proactive updates。

Google DeepMind：用自动评估器管理开放式算法搜索

AlphaEvolve 不是让多个 Agent 在共享聊天中讨论，而是让模型提出实现算法的程序，由自动 evaluator 运行、验证和打分，再将高价值程序保存到程序数据库，用进化式选择决定下一轮 prompt 使用哪些候选。Google DeepMind 说明它同时使用快速模型扩大探索面、强模型提供更深的建议，并能演化整个 codebase 而不只是单个函数。

其可迁移机制是：当目标可以被量化时，把“完成”从语言判断转换为可重复的运行指标；让候选解进入受控数据库和选择循环；用多样性与质量的组合管理探索/利用权衡。对业务软件而言，对应物可以是测试通过率、性能基准、迁移一致性、静态安全扫描或成本指标。

证据：Google DeepMind AlphaEvolve 官方文章。

Microsoft AutoGen：显式团队拓扑与终止条件

AutoGen AgentChat 将多 Agent 团队建模为可组合的 team：RoundRobinGroupChat 负责轮流发言，SelectorGroupChat 由模型选择下一个发言者，Swarm 用 handoff 在 Agent 间转移控制，MagenticOneGroupChat 面向开放式任务。官方文档明确建议先优化单 Agent，只有在任务确实需要协作和多样专业能力时才引入团队，因为团队需要更多 scaffolding。

AutoGen 的示例还把 critic、termination condition 和 human-in-the-loop 作为一等组件。由此可见，其管理重点是显式的协作拓扑、发言/交接规则和停止条件，而非简单增加 Agent 数量。

证据：AutoGen Teams 官方文档、AutoGen Studio Team Builder。

OpenHands：把委派、隔离和运维做成可部署 SDK

OpenHands 官方 SDK 支持 DelegateTool，将复杂任务委派给同步返回结果的专门子 Agent；也支持用项目目录中的 Markdown 文件定义 Agent 的名称、描述、工具和 system prompt，项目级配置优先于用户级配置。其远程 Agent Server 将 SDK 放进容器，负责专用基础设施、workspace 管理、WebSocket 事件流、文件/命令操作和不同执行之间的隔离；官方仓库还宣称可在云端扩展到数千个 Agent。

与 DeepSeek Harness 相似之处是“父级编排 + 专门子级 + 统一返回”；差别在于 OpenHands 把 Agent 定义和 workspace 运维暴露成较直接的生产 SDK，而 Harness 更强调能力接缝、持久事件、生命周期与可替换提供方。

证据：OpenHands Task Tool Set / 文档索引、File-Based Agents、Remote Agent Server、OpenHands 官方仓库。

SWE-agent：先设计 Agent-Computer Interface，再谈自主性

SWE-agent 的论文将重点放在 Agent-Computer Interface：Agent 通过专门设计的命令和工具接口，读取、定位、编辑和验证真实 GitHub 仓库中的问题。官方文档把它定义为可处理 GitHub issue、漏洞发现等任务的可配置研究系统，并以单个 YAML 文件集中描述配置。

该项目的启示是，大型仓库中的 Agent 能力很大程度由工具接口决定：搜索、补丁、测试、错误反馈和上下文截断如何呈现，会直接影响长程执行。与其只改 prompt，不如先把“模型能观察什么、能改变什么、失败后得到什么反馈”设计清楚。

证据：SWE-agent 官方文档、SWE-agent ICLR 论文。

MetaGPT：用软件公司角色与 SOP 组织需求到实现

MetaGPT 论文把产品经理、架构师、工程师等角色编码为多 Agent 协作流程，用标准操作程序（SOP）规定角色之间的输入输出顺序，以 assembly line 方式把复杂软件任务拆为子任务，并让角色验证中间结果。论文的动机是避免简单聊天式串联导致的级联幻觉和逻辑不一致。

这种模式适合流程稳定、产物接口清晰的项目：需求文档、用户故事、架构、代码、测试可以成为阶段性工件。但它也提示一个边界：角色越多、SOP 越长，编排成本和错误传播面越大，必须保留可观察的中间产物与阶段验收，而不是把整个“软件公司”当作不可解释黑盒。

证据：MetaGPT 论文、MetaGPT 官方仓库。

三、横向比较

四、对大型项目落地的建议

1. 采用分层调度

将任务分成三层：根 Agent 负责目标、优先级和合并；子 Agent 负责有边界的领域任务；workflow/队列负责可批量化的独立项。只有依赖关系不明确或需要即时结果时才使用前台等待；独立任务默认后台扇出。

2. 让每个子任务成为可验证的工作对象

任务描述应包含范围、输入、输出、禁止触碰的区域和验收命令。软件项目中优先让子 Agent 产出 branch/PR、测试结果、迁移报告或结构化 JSON，而不是只返回自然语言总结。

3. 为每种状态定义真源

计划用 Todo 或任务系统，事实用事件日志，代码用 branch/commit，验收用测试/扫描/评估器，人工决定用 review/approval。不要让 prompt 中的一句“已完成”取代这些记录。

4. 将并发设计与隔离设计绑定

能并行不等于能共享工作目录。并行写代码应使用 worktree、branch、容器或独立 workspace；共享资源必须有明确所有权和合并策略。对于 workflow 脚本，worker 隔离能保护宿主稳定性，但不能自动成为安全边界，真正不可信代码应使用进程或容器隔离。

5. 长任务必须支持暂停、继续、取消和未知结果

异步 Agent 不应依赖一次工具调用同步返回所有结果。需要稳定 id、状态查询、FIFO 消息、取消语义、结算通知、日志和恢复。涉及外部副作用时，崩溃恢复应记录 unknown，而不是盲目重试；工具提供方应支持幂等键或人工确认。

6. 把“自动验收器”视为 Agent 管理的核心基础设施

AlphaEvolve 的 evaluator、GitHub 的 CI/扫描、SWE-agent 的工具反馈和 Harness 的测试/快照都说明：Agent 数量不是主要生产力指标，可靠反馈才是。应优先投资可重复、快速、覆盖关键风险的验收器，再扩展 Agent 并发。

7. 保留单 Agent 基线与人工升级路径

AutoGen 官方明确建议先把单 Agent 做好。实际落地可设升级规则：单 Agent 失败或任务可拆分时才引入子级；安全、架构、数据迁移和发布等高风险节点必须保留人工审批；低风险测试、文档、代码搜索和候选方案生成可更多自动化。

五、结论

deepseek-harness 的独特价值不在于“有 subagent 工具”，而在于把 Agent 管理的完整生命周期拆成了可组合且可审计的基础设施：谁被委派、以何种上下文和权限运行、如何并发、怎样回传、如何继续、何时持久化、崩溃后如何判断未知副作用，以及哪些事实必须进入日志。外部实践分别在交付工作流、自动评估、团队拓扑、远程执行、工具接口和 SOP 角色化上强化了同一套原则。

因此，管理大型项目的推荐架构可以概括为：

结构化目标 → 有界任务分解 → 隔离执行 → 持久状态与可观测性 → 自动验收 → 人工合并/批准 → 可继续和可审计的反馈闭环。

这里的“Agent Team”不是越多越好；只有当任务之间存在可表达的独立性、角色差异或评估收益时，并行和多 Agent 才值得其编排成本。