一种适合程序员的 Agent 协作方式的实践

构思与实践前提在展开具体实践之前先交代三个前提条件。第一使用集成开发环境IDE作为 Agent 协作的面板。本实践的 IDE 限定为 TRAE因为它免费且功能足以满足需求。更重要的是IDE 本身就是可观测性和可交互性的来源——你能实时看到 Agent 在做什么也能随时介入调整。第二使用 DeepSeek 作为 AI 模型。它足够便宜即便是 Flash 这样较轻量的模型产出质量也足够好。第三笔者有一个长期保持的习惯使用单独的 Git 仓库作为日常工作区和知识库。在 AI 时代这个习惯的好处被显著放大。Git 本身提供了优秀的版本控制和跨设备同步能力而基于 Git 的语义检索又将搜索提升到了新的维度——你不需要记住文件存在哪里只需要描述你想找什么。二者的结合使这套方案在信息的持久化和召回上胜过了常见的笔记系统。核心实践整个体系由三个子系统构成工具系统、记忆系统、Skill 系统。三者各司其职共同支撑 Agent 的高效协作。工具系统工具系统负责执行确定性的任务。笔者选择 .NET 10 的基于文件的应用程序FBA作为工具的构建基础。FBA 足够轻量无需复杂的项目配置一个 .cs 文件就是一个可执行的工具而且它有编译缓存重复执行时的冷启动开销极低。工具在设计时尽量支持管道运算以便组合使用。在使用 AI 调用工具的场景下工具参数的接口设计有一个重要原则宁可返回过量的内容也不要增加参数来追求精确的输出。举例来说假如要写一个获取项目连接字符串的工具那么应该做一次全量扫描通过模式匹配返回所有连接字符串而不是添加一个 --project 参数来指定具体项目。原因很简单AI 很可能会传递一个错误的参数值而返回过量的数据至少不会漏掉目标。核心的工具包括以下几种scheduler用于定时任务触发基于 cron 表达式支持超过一个周期的遗漏补偿。当 Agent 离线期间积压的任务在恢复后能够自动补齐。event-logger记录用户与 Agent 之间的交互事件为记忆系统提供原材料。每行日志简洁精炼仅记录关键信息。agent-runner在 .NET 进程中提供一个 Agent 执行环境用于加载外部的 Agent 定义并执行。vector-manage向量索引系统基于 Git 的变更历史做增量构建实现工作区知识的语义检索。记忆系统记忆系统参考了腾讯的 TencentDB-Agent-Memory 设计结合文件系统实现了一套分层记忆架构并基于 Git 做增量构建和版本管理。整个记忆系统围绕一个名为 Copilot 的 Agent 运转。Copilot 扮演个人助理的角色能够根据用户与 Agent 的交互事件自动构建和整理记忆。记忆的构建方式参考了 TencentDB-Agent-Memory 的分层设计L0 — 原始事件每一条交互日志以 JSONL 格式按日期存储作为记忆的原材料。L1 — 结构化摘要按天为单位从原始事件中提炼关键信息形成当日的活动摘要。L2 — 上下文场景将多个相关事件组织成场景块描述一段完整的工作叙事。例如SQL 优化 Skill 开发和线上实战就是一个典型的场景。L3 — 用户画像从大量场景中蒸馏出用户的编码偏好、行为模式和关注领域形成持久化的画像。L4 — 持久化事实原子级的知识节点记录具体的偏好、规则和关键信息。记忆的整理和消化由 scheduler 驱动每 6 小时触发一次整理L0 → L1 → L2 的流水线处理每 12 小时触发一次消化L2 → L3 → L4 的深度蒸馏。这样的频率既保证了记忆的时效性又不会过度消耗 API 配额。Skill 系统Skill 系统与工具系统不同它不执行确定性的任务而是处理那些复杂的、不确定的、需要多步推理的工作。每个 Skill 是一份结构化的 Markdown 文档定义了触发条件、使用流程、退出条件和输出标准。其中最具代表性的是 long-task Skill它的执行流程体现了整个体系的核心理念。当一个长期任务被触发时long-task Skill 首先检索记忆系统用户画像、相关场景、历史事实同时搜索工作区的向量数据库汇总出足够的信息作为任务规划的上下文。然后它理解用户的需求创建一个 Readme.md 概述任务的目标和范围同时创建一个 Tracking.md 记录进度和状态。在任务真正开始执行之前用户和 Agent 的主要工作集中在对这些前置规划的修正上——推敲目标是否清晰、范围是否合理、方案是否可行。这个过程确保了每一次执行都有一个经过审慎思考的上下文从而产出较高质量的结果。Skill 和工具的区别在于工具是确定性的同样的输入总是产生同样的输出Skill 则不然它可能包含多轮对话、多次工具调用、多次人工判断。工具是 Skill 的积木Skill 是工具的使用者。目录结构整个 Copilot 体系以 Copilots/ 为根目录纳入 Git 仓库管理。以下是精简后的目录结构Copilots/├── agents/ # Agent 定义│ └── copilot/ # Copilot 个人助理│ ├── config.json # Agent 配置│ └── skills/ # Agent 私有 Skill│ ├── git-skill/│ ├── memo-facts-skill/│ ├── memo-persona-skill/│ ├── memo-pipeline-skill/│ ├── memo-recall-skill/│ ├── memo-scenes-skill/│ └── memo-summary-skill/ # 记忆分层体系6 个 Skill 管道编排│├── commands/ # 命令定义向用户开放的快捷入口├── rules/ # 规则文件编码、写作、工作流等│├── skills/ # 全局 Skill│ ├── long-running-task-skill/ # 长期任务跟踪│ ├── task-brainstorm-skill/ # 任务头脑风暴│ ├── fba-tool-skill/ # FBA 工具编写规范│ ├── yunshu-sql-optimizer-skill/# SQL 查询优化│ └── … # 其他 Skill│├── tools/ # 可执行工具│ ├── copilot-mcp-tool/ # MCP 服务端│ ├── scheduler-tool.cs # 定时调度器│ ├── event-logger.cs # 事件日志│ ├── harness-agent-tool.cs # Agent 执行环境│ ├── guard-tool.cs # 进程守卫│ ├── sql-server/ # SQL Server 工具集│ ├── vector-tool/ # 向量索引工具│ └── lib/ # 共享工具库│└── memories/ # 记忆系统├── l0.events/ # 原始事件JSONL├── l1.summaries/ # 结构化摘要JSON├── l2.scenes/ # 上下文场景Markdown├── l3.persona/ # 用户画像└── l4.facts/ # 持久化事实JSONagents/ 与 skills/ 的分离是刻意的设计agents/copilot/skills/ 中的 Skill记忆体系相关仅供 Copilot Agent 自身使用受权限控制skills/ 中的全局 Skill 则对所有 Agent 开放。tools/ 目录的扁平化结构便于工具发现和调用功能相关的工具以子目录分组。整体架构下方这张图概括了整体设计。Copilot 个人助理位于中心对接三个子系统。TRAE 内置 Agent 同样可以调用本体系中的 Agent、Skill 和 Tool两个 Agent 共享同一套基础设施。architecture工具之间并非松散堆积而是有一条清晰的依赖链条。下方这张图展示了各工具之间的调用关系和上下层依赖toolchain核心的依赖关系可以概括为三层Hooks 在最底层负责采集一切原始输入guard-tool 在中间层确保常驻进程不会因异常退出而中断scheduler 在调度层驱动定时任务按周期执行。其余工具处于运行层——不驻留、不等待被 MCP 或其他 Agent 按需调用执行完成就退出。实践案例从构思到完成这个工程约莫花了一周时间——严格来说编码工作几乎全部由 AI 完成即便此刻你在阅读的这篇文章也不例外。下方选取三个具有代表性的案例展示这套体系在实际工作中的运作方式。案例一设计 SQL 查询优化 Skill背景我司产品线基于 SQL Server经常遇到慢查询问题。虽然已经积累了参数嗅探、快照隔离等知识点的 Wiki 文档但整个优化流程仍然依赖人工分析缺乏自动化手段。笔者决定开发一个标准化的 SQL 优化 Skill让 Agent 能够自动执行从分析到建议的迭代闭环。第 1 轮 — 可行性分析Agent 首先评估了项目的技术现状确认 SQL Server 数据库可以直连存在连接字符串配置main.json 中的 adoSql* 节点具备工具开发的基础条件。Agent 输出了一份可行性分析报告提出了四个 FBA 工具的技术方案连接列表获取、Schema 读取、查询计划分析、查询执行。笔者确认方向可行要求进入实施。第 2 轮 — 工具开发与快速迭代Agent 在一小时内完成了四个 FBA 工具的初版开发。笔者的要求是先跑通再看没有追求完美。四个工具涵盖从连接发现到执行验证的完整链路。笔者在这个过程中持续给出调整指令工具从 Skill 目录迁移到 tools/ 下的独立目录共享工具放 tools/sql-server/私有工具放 tools/yunshu-sql-optimizer-skill/增强 JSON 输出的结构化程度添加多结果集支持改进了 AOT 编译配置。第 3 轮 — 流程标准化Agent 设计了一套七文件的模板体系来规范优化产出。笔者审阅后给出关键意见模板文件太过零碎了要求精简。最终确定为两文件范式——一份面向人的分析报告optimization-report.md和一份面向过程的技术记录tracking.md采用双环境闭环Develop 环境验证可行性 Debugger 环境执行线上变更。Agent 按照这个要求重新设计了产出模板并通过一次真实数据验证确认方案落地。第 4 轮 — 经验沉淀第一次实战暴露了 Sort 算子优化器代价与实际耗时严重脱节的问题。笔者要求补充服务器诊断步骤sys.dm_os_wait_stats 区分 IO/锁/CPU 瓶颈增加读代码前置环节理解 SQL 是如何构造的——动态拼接还是 EF Core 生成——决定可改范围增加可行性校验区分可加索引“可改写 SQL”不可修改三种状态。Agent 逐项更新了 SKILL.md。这些改进使 Skill 从能跑进化到了可靠的程度。案例二执行 SQL 查询优化 Skill——线上实战Skill 设计完成后立即投入了一次真实的线上 SQL 优化实战。这次实战不只是验证了 Skill 的有效性更重要的是反哺了 Skill 本身的设计这是一条 OnlineOrder 订单列表的分页查询涉及 4 张表的 JOIN 加一个标量子查询计算同物流单号的订单数。筛选条件通过动态字符串拼接最终 SELECT 近 50 列含 nvarchar(MAX) 宽列。OnlineOrder 表 51 万行的数据量不算大但查询涉及多级排序Number ASC, CreateTime DESC, LogisticsNumber ASC, Id ASC加上近 50 列含 nvarchar(MAX) 宽列的 SELECT 负载线上耗时高达 7,474 毫秒。排序规则硬编码在代码中且无法使用 CTE 或两阶段拆分。Agent 遵循刚刚完善的三步前置流程先读了代码确认 SQL 构造方式和可改范围再做服务器诊断确认 IO 是主要瓶颈最后备份表结构。核心问题是 Sort——其 IO 代价 5,045 占查询总代价的 99.6%严重溢出到 tempdb。优化方案是创建一个与 ORDER BY 完全匹配的复合索引以 IsDeleted 作为等式前导列后续列顺序与排序完全一致。这是一个纯索引方案零代码改动。Develop 环境验证结果100 条数据指标 优化前 优化后Sort 算子 存在代价 5,323 已消除总预估代价 5,324 0.79-99.98%扫描方式 Clustered Index Scan Index Seek笔者确认后在线上执行效果显著查询 优化前 优化后 提升COUNT 1,817 ms 1,499 ms -18%数据查询 7,474 ms 1,695 ms -77%Sort 算子 存在 已消除 —数据查询从 7.5 秒降至 1.7 秒改善了 77%。更重要的是这次实战验证了双环境闭环流程的有效性先在 Develop 验证计划变化再到线上体现真实耗时——Develop 数据量小但能确认执行计划变更线上才能体现耗时优化的真实幅度。案例三用这套体系写一篇博客——本文的诞生long-task 的工作流程可以概括为三步用户给出大纲outline.mdAgent 生成任务说明书Readme.md和进度跟踪文件Tracking.md然后双方基于这两份文件迭代推进。下面就是本文从构思到产出的完整过程。第一步笔者给出了一份大纲。一种适合程序员的Agent协作方式的实践注意本文使用AI辅助生成本文章亦是本文章所述实践之产物。背景简述AI在这个时代的快速普及以致于各行各业都无法忽视。笔者尝试过多种AI的使用方式但大多数的实践方式都落在两个极端。使用现成的第三方客户端或者产品无法快速的为AI提供上下文信息要么需要频繁补充上下文信息要么产出结果不符合预期。使用OpenClaw这样的Agent集群工具无法获得高可观测性或者需要大量的工程成本。之所以会出现这样的情况主要是因为程序员这个职业比较特殊。一方面需要向AI提供足量的上下文来约束AI的行为和输出另一方面他不能当老板或者当皇帝笑。他更像一个施工小队的队长必须及时、快速的调整AI的行为和输出以满足当前工作的规范。所以可观测性是非常重要的。总而言之在AI尚未成为真正的AI之前程序员需要像一个Agent一样介入多个Agent的工作。构思与实践前提使用IDE作为Agent协作的面板本实践限定IDE为TRAE因为他免费功能做的也不错。使用deepseek作为AI模型因为它足够便宜而且flash模型的产出就足够好。笔者有一个使用单独git仓储作为日常工作区和知识库的习惯所以这个仓储作为本实践的根目录。核心实践工具系统使用.NET10的FBA作为工具构建基础因为它足够轻量而且有编译缓存。工具实现的时候尽量能够支持管道运算。工具主要用来快速执行确定性的任务。为了符合AI的使用习惯工具的参数不能设计的太死板。宁愿返回过量的内容也不要增加参数来追求精确的输出。举个例子比如我要写一个工具获取项目的连接字符串。那么我宁愿做一次扫描模式匹配返回所有的连接字符串也不要添加一个–project参数因为AI可能传递一个错误的参数。核心的工具-scheduler 用户定时任务触发基于corn并且支持1周期的遗漏补偿。-event-logger 用户记录用户和Agent的交互事件-agent-runner 用于在.NET进程中提供一个Agent执行环境以便加载外部的Agent定义并执行。-vector-manage 向量索引系统基于git做向量增量构建。记忆系统参考TencentDB-Agent-Memory搭建一个基于文件的记忆系统基于git做记忆增量构建。记忆系统定义了一个Copilot的Agent作为个人助理能够根据Agent和用户的交互时间自动构建记忆。记忆的构建方式是让AI参考TencentDB-Agent-Memory实现的。本实践基于scheduler工具每6小时触发一次记忆整理每12小时触发一次记忆消化。Skill系统主要用来完成复杂的、不确定的任务。核心的SKILL-long-task该SKILL在执行之前会检索记忆系统同时检索工作区的向量数据库返回足够的信息用作头脑风暴上下文。然后他会理解用户的需求并指定一个readme.md概述任务的需求和目标。同时会创建一个tracking.md文件用来记录任务的进度和状态。在任务真正开始之前用户和agent的主要工作都是根据这些前期规划做修正。最终这份材料会作为任务的执行上下文。从而预期一个较高质量的结果。实践案例从构思到实践这个工程约莫花了一周的事件可以说99%的编码工作都是AI完成的包括这篇博客。让AI设计一个Sql查询优化Skill从对话记录中提取这部分的日志作为案例执行这个Sql查询优化Skill从对话记录中提取这部分的日志作为案例这份大纲本身就是一份粗粒度的需求文档——结构有了方向有了但占位符和松散的表达意味着它还需要被翻译成可执行的任务。而翻译它的正是后面的 Readme.md。第二步Agent 基于大纲和头脑风暴生成了 Readme.md。博客撰写一种适合程序员的 Agent 协作方式的实践背景与动机基于已有的博客大纲 outline.md撰写一篇完整的博客文章记录笔者在 yunshu-station 项目中构建的 Agent 协作实践体系。目标根据大纲填充所有占位内容撰写完整博客从工作区的记忆系统、任务记录、事件日志中提取素材填充实践案例博客语言为规范的现代汉语书面语范围纳入根据 outline.md 结构撰写完整博客正文补全「Copilot 目录结构」部分补全「实践案例」部分SQL 优化 Skill 的设计与执行输出为独立 markdown 文件排除不修改大纲的结构和章节划分不添加大纲未提及的内容不进行发布格式转换技术方案直接从工作区记忆中提取两次 SQL 优化实战的详细数据对话轮次、SQL 语句、优化方案、效果数据按照书面表达要求组织为案例章节。博客产出物放置于 .temp/blog-way-of-better-cop-with-agent/blog.md。依赖与前置outline.md 已存在工作区记忆系统l2.scenes、l4.facts包含案例素材风险