用Agent将需求文档自动拆解为可追踪工作项的工程实践-代码聚汇网

用Agent将需求文档自动拆解为可追踪工作项的工程实践

申月有五·2026-09-01·阅读 26 GEO检测（免费）

AI Agent需求文档工作项

|难度：普通|阅读约 38 分钟

先说结论：需求文档到工作项这条链路，值得用 Agent 重做一遍。PingCraft 是我在公司内部做了两个多月的一个落地项目，核心就干一件事——把产品经理写的需求文档自动拆成结构化的、可追踪的工作项，并且让工作项和需求原文之间的映射关系一直保持不丢、不变、可回溯。这篇文章把整个实践过程、架构选择和踩过的坑详细写出来，适合正在做研发效能、工具链建设，或者打算用 Agent 改造现有工作流的朋友参考。

1. 需求到工作项的断点到底在哪里

1.1 最原始的流程长什么样

我先描述一个绝大多数团队每天都在发生的场景，你看看是不是很熟悉。

产品经理写完一份 PRD，传到在线文档，群里@所有人“需求评审”。评审会上大家七嘴八舌聊了一轮，开发负责人拍板说“行，能排期”。然后关键的搬运工出现了——通常是技术组长或者某个苦逼的后端工程师，打开项目管理工具，照着 PRD 一段段手动创建 Epic、Story、Task，再把验收标准从文档里复制粘贴到任务描述里。光一个中等规模的需求，三十多个工作项，手动建小一个小时，还容易漏。

这还不是最要命的。最要命的是需求文档从来不是一次定稿。产品经理过两天说“登录方式改一下，加个微信”，技术组长要去 Jira 里找一个叫“登录模块”的 Story，点进去改描述，再通知前端加一条子任务。如果文档改了而工作项没同步，两周后测试拿着工作项验收，发现跟线上行为对不上，到时候谁都不记得最初怎么约定的。

我把这类问题归纳成四类：

工作项产出速度慢。手动拆解耗时，尤其需求频繁调整时，前面拆的所有工作项可能白费。
颗粒度不一致。同一个人上午拆的任务特别细，下午累了就粗放一点；不同的人拆出来的格式更是五花八门。
追踪关系靠人工记忆维护。文档和工作项之间的对应关系存在人脑里，人一换、时间一久，就断了。
变更之后的联动完全缺失。需求文档改了，对应工作项的更新靠“自觉”，没有任何机制来保证。

1.2 真正要解决的核心问题

PingCraft 要解决的其实不是“把自然语言变成结构化数据”这么简单，而是要把“需求追踪”这件事从人的脑子搬到系统里。我给自己定了三个核心目标：

第一，需求文档必须能够被拆解成统一层级的工作项结构，而且拆解的颗粒度标准要固定。不能昨天拆粗今天拆细，得有明确的映射规则。

第二，每一条工作项必须能追溯到需求原文的精确位置。不管是某一段章节还是某一句话，都得有引用依据。这个依据不是人写的备注，而是系统自动生成的双向链接。

第三，需求文档重新导入后，系统要能自动感知变更，并且只对受影响的工作项做增量更新。不是整批删除重建，那样历史记录就没了。

这三个目标里，第三条是最难做的，也是我后来认为最有价值的部分。因为大量团队能解决“拆分”问题，但解决不了“变更后不丢追踪”的问题。

1.3 为什么这个场景适合用 Agent 来做

聊方案选型之前，先说一个很多人会问的问题：这个需求用纯规则引擎或者写个脚本也能做，为什么要上 Agent？

我最早也是这么想的，后来试下来发现真的不行。需求的表达方式太不固定了。同样一个含义，有的产品经理写“用户可通过手机号登录”，有的写“支持手机号验证码登录”，还有的写“登录模块：手机号+验证码”。同一个 PRD 里，章节层级可能是两级也可能是四级，验收标准有时用“GIVEN/WHEN/THEN”格式，有时就是一句“要能正常登录”。规则引擎遇到这些变体，基本是写一个规则漏一批案例，维护成本高到离谱。

Agent 的方案就不一样。LLM 天然擅长理解语义而不是匹配关键词，它能把 10 种写法不同的“手机号登录”归一化成同一条 Story 描述。另一层优势是 Agent 能自主判断什么时候该怎么处理——依赖模糊时查上下文，信息不足时停下来问人，输出模型不对时重试。这些都是传统脚本做不了的。

当然，Agent 不是万能药，我后面会讲它带来的新问题，比如幻觉、格式不稳定、长文档截断这些，都是一步一步填坑填过来的。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. PingCraft 整体架构与任务拆解

2.1 三层设计：解析、映射、落地

PingCraft 的架构我分成三层，每一层职责单一，中间用结构化的 JSON 数据传参，方便出问题时单独调试。

解析层接收原始需求文档，输出一个中间表示——我把这个叫需求对象模型（Requirement Object Model，简称 ROM）。ROM 里包含文档的章节树、每个章节下的功能点描述、依赖关系、业务规则和验收标准。这个模型是语义层的，不绑定任何项目管理工具格式。

映射层拿到 ROM，按照预设的映射规则，把功能点转成工作项草稿。比如“一个完整业务闭环”映射成 Story，“Story 下的具体操作步骤”映射成 Task，“一批 Story 组成的上线单元”映射成 Epic。同时生成每条工作项与需求原文之间的 TraceLink，Link 里记录了来源章节、原文摘要和置信度分数。

落地层负责和外部系统对接，把这些草稿创建到 Jira、PingCode 或者你们内部的工单系统里。为了安全，落地层默认不直接写外部系统，而是先输出一个 YAML 审核文件，人工确认后再批量导入，后面的实操部分我会展开讲这个设计。

2.2 Agent 编排模式：Plan-and-Execute 加人工确认节点

Agent 的具体实现上，我采用的是 Plan-and-Execute 模式，不是单一的 Autonomy 模式。原因不复杂：需求拆解这件事，步骤本身是清晰的，但每一步的执行结果有不确定性，所以用“计划先定好，执行中动态调整”最合适。

整体跑一个循环：主 Agent 接收任务后先读文档，制定解析计划——比如先遍历章节，再逐段抽取功能点，然后识别验收标准；接下来由子 Agent 按计划执行，执行完的结果交回主 Agent 做质量校验；校验通过后再进入映射阶段。

值得一提的是子 Agent 的调用方式。我一开始用独立的 Agent 节点去实现解析，后来发现没必要，子 Agent 本质上就是“一个带有独立 Prompt 和工具权限的函数调用”，主 Agent 按需调用它。这个思路很重要，它让整个系统的调试难度降了一个量级——每个子环节都能单独跑、单独看输出、单独出问题单独修。

架构里还少不了人工确认节点。工作项是要进项目管理系统里的，出错了会影响真实团队的工作。所以我在两个地方强制加了人工介入：一是生成工作项草稿但还没写入外部系统前，二是检测到需求变更需要批量修改已有工作项前。

2.3 可追踪性的底层数据结构设计

可追踪是整个项目最重要的特性，所以我要专门说一下底层数据怎么设计的。

最核心的数据结构是 TraceLink，一条 TraceLink 代表“需求原文的一部分”到“一个工作项”之间的关系。字段我这样定义：

link_id：全局唯一 ID，格式建议用 trace- 开头加日期加序号
source_ref：需求原文的定位信息，我存的是文档 ID、章节路径、原文 hash、原文摘要
target_ref：工作项的 key（比如 Jira 的 JIRA-123）
relation_type：枚举值，可以是 refines（需求衍生出工作项）、validates（验收标准验证工作项）、depends_on（工作项之间的依赖）
confidence：置信度，0 到 1 之间，低置信度的记录会标记出来提醒人工检查
status：当前追踪状态，active、stale、broken 三种

这里 status 字段特别关键。当需求文档重新导入后，系统会重新计算原文的 hash，如果发现某段原文变了，对应 Link 的 status 就标记为 stale，同时把关联的工作项置为“待更新”。如果某段原文被删除了，Link 变成 broken，系统会提醒做删除或归并操作。这样一来，“需求文档改了，工作项要不要改”这个问题就有了唯一的判断入口，而不是靠任何人的自觉。

3. 工具选型与关键技术决策

3.1 Agent 框架：为什么最终选择了 LangGraph

Agent 框架当时考察了几个选项：LangGraph、AutoGen、再加一个自研的轻量编排器。

AutoGen 的多 Agent 会话机制很灵活，但是从代码可读性角度，它把太多逻辑藏在会话消息流里。项目里需要清晰的、可中途打断的状态转换，AutoGen 就不太合适。

LangGraph 的图执行模型和这个项目的契合度最高。它能把 Plan、Parse、Map、Verify、Publish 这些步骤定义成图节点，节点之间的跳转逻辑显式声明，状态管理也是内置的。单步调试的时候可以直接定位到是哪个节点出了问题，对排障效率提升巨大。

不过我也做了一部分轻量自研。在最外层，我用一个 Python 的 asyncio 事件循环包了一层，负责文档监听、队列调度和外部系统回调。这样 LangGraph 只负责单条需求链路的内部编排，外层的事件驱动和数据持久化由自己掌控，两边都不至于拧巴。

3.2 LLM 选型与结构化输出的关键问题

选 LLM 的时候，我对比了 GPT-4o 和 Claude 3.5 Sonnet。最后主力用的是 Claude 3.5，原因是它在长文档的理解和结构化 JSON 输出上更稳。但这不是绝对的，不同时期不同模型的差异很大，选型时要锚定两家硬指标：一是长上下文窗口下的准确率衰减曲线，二是结构化输出的 JSON 格式通过率。

关于结构化输出，我的经验是不要依赖普通的 json 输出模式，要用 function calling。把“提取需求实体”“生成 TraceLink”“判断变更类型”分别定义成 function，让模型在对话过程中按需调用。这样输出格式的稳定性比纯文本让模型“输出 JSON”高出好几个档次。

另外补充一个细节：所有 Prompt 里的 JSON 输出要求，我都会附上一个完整的示例。模型对“给一个例子”的响应远好于对“描述一个格式”的响应，这个差异在实测中非常明显。

3.3 项目管理工具对接：先出中间文件再导入

对接外部项目管理系统这里，我用了一个中间文件策略。系统解析完文档后，先生成一个 work_items.yaml，里面包含所有工作项的完整结构和 TraceLink 映射。这一步不对外部系统做任何写操作。等人工审阅通过后，再执行导入脚本，通过 REST API 批量创建。

为什么这么设计？两个原因。第一，外部系统的数据结构通常比较脏，同名项目分散在不同命名空间、字段必填项不一致，直接实时创建会很脆弱，一旦创建到一半失败，要么回滚要么留下一堆垃圾任务。先全量生成再统一导入，一次失败可以重来，不会对系统留下脏数据。第二，需求方很需要“提前看到工作项再点确认”这个过程，它是建立信任的关键环节，直接把结果灌进 Jira 会让他们感觉自己失去了掌控。

4. 核心实现：从需求文档到可追踪工作项的完整链路

4.1 需求文档的预处理与分段策略

第一步是处理原始文档。我们的输入多是 Markdown 或者从在线文档导出的 Word，为了统一处理，我全部转成 Markdown 后进行解析。

分段是一个容易被忽略但非常关键的步骤。LLM 有上下文窗口限制，需求文档动不动就几十页，根本塞不进去。我的做法是先把文档按标题结构分割成多个 chunk，每个 chunk 限制在 3000 字左右，然后有策略地分配给解析 Agent 做并行处理。

这里有个细节：切分时，我会把每个 chunk 对应的章节路径和前后章节的标题也一起传进去。这样子 Agent 在解析“登录功能”时，能知道自己处于“用户模块-认证机制-登录功能”这条路径上，对理解文档上下文帮助巨大。切分后加上章节路径，能显著降低后续实体抽取的歧义。

4.2 实体抽取与工作项映射的 Agent Prompt 设计

这一节我放一个核心的 Prompt 片段，里面的设计点都很实用。实际项目中，这部分的调优花了最多时间。

整个 Prompt 的核心思路是：给模型非常明确的三个锚点——文档里写的是什么，你要提取什么，输出格式是什么。中间用一段示例告诉它什么是好的提取结果。

我用一个简化版的示例，方便你理解结构：

python复制SYSTEM_PROMPT = """
你是一个需求分析 Agent。你的任务是从用户提供的需求文档片段中，识别并提取结构化的需求实体。

你需要提取三类实体：
1. func_point: 功能点，描述系统需要支持的一个具体能力
2. acceptance_criteria: 验收标准，可以验证这个功能是否完成的条件
3. business_rule: 业务规则，功能运行中必须遵守的约束条件

提取时注意：
- 功能点必须是一个动词短语，比如"用户通过手机号验证码登录"
- 验收标准必须是可验证的，比如"输入错误验证码时提示'验证码错误'"
- 业务规则要有明确的输入输出约束，比如"验证码有效期5分钟"
- 如果一段文字同时包含多个实体，全部提取，不要遗漏

## 示例
文档片段：
"用户可以通过手机号验证码登录。验证码发送后5分钟内有效，每个手机号每天最多发送10条。如果用户输入错误验证码超过5次，账号锁定30分钟。"

输出：
{
  "entities": [
    {
      "type": "func_point",
      "content": "用户通过手机号验证码登录",
      "chapter_path": "登录模块-手机号登录",
      "confidence": 0.97
    },
    {
      "type": "business_rule",
      "content": "验证码有效期5分钟",
      "chapter_path": "登录模块-手机号登录",
      "confidence": 0.99
    },
    {
      "type": "business_rule", 
      "content": "每个手机号每天最多发送10条验证码",
      "chapter_path": "登录模块-手机号登录",
      "confidence": 0.99
    },
    {
      "type": "acceptance_criteria",
      "content": "输入错误验证码超过5次，账号锁定30分钟",
      "chapter_path": "登录模块-手机号登录",
      "confidence": 0.98
    }
  ]
}

## 待处理文档片段
{chunk_content}
"""

从示例里你能看到，我在 Prompt 中做了三件事：给出实体类型的精确定义、用一个高质量示例框住输出风格、要求每个实体带 chapter_path 和 confidence。chapter_path 后面是要写入 TraceLink 的，confidence 用来筛低质量结果。

映射层的 Prompt 则是另一个方向，要把 ROM 里的功能点转成工作项。映射规则我写死在 Prompt 里：

一个完整的业务闭环（比如“登录”整个流程）映射为 Story
Story 内每个可独立交付的动作（比如“发送验证码”“校验验证码”“锁定处理”）映射为 Task
一组同迭代交付的 Story 聚合为 Epic
每个验收标准映射为这条 Story 的验收描述

这个映射标准一旦定了，后续的颗粒度问题就彻底解决了。

4.3 工作项生成的完整链路

当所有实体抽取完毕后，就进入工作项生成阶段。这一步我用一个独立的 Agent 来执行，输入是完整的 ROM，输出是工作项集合 work_items.yaml。关键代码如下：

python复制async def generate_work_items(rom: RequirementObjectModel):
    mapping_agent = WorkItemMappingAgent()
    
    # 分类：识别哪些功能点可以作为 Story 主体
    story_candidates = []
    for func_point in rom.func_points:
        # 判断这个功能点是否构成完整业务闭环
        if await mapping_agent.is_complete_business_flow(func_point):
            story_candidates.append(func_point)
    
    # 为每个 Story 生成 Task
    work_items = []
    for story in story_candidates:
        tasks = await mapping_agent.generate_tasks_for_story(story, rom)
        acceptance = await mapping_agent.extract_acceptance_criteria(story, rom)
        
        work_items.append({
            "type": "story",
            "title": story.content,
            "description": story.get_description(),
            "acceptance_criteria": acceptance,
            "tasks": [task.dict() for task in tasks],
            "trace_links": [
                {
                    "source_ref": story.chapter_path,
                    "source_hash": get_text_hash(story.content),
                    "relation_type": "refines"
                }
            ]
        })
    
    return work_items

这段代码的流程很直接：先确认哪些功能点是 Story 级别，然后为每个 Story 生成 Task，提取验收标准，最后写入 TraceLink。实际运行时你会发现，最耗时的是第一步 is_complete_business_flow 的判定，因为它要综合上下文判断，这里必须用 LLM。后面生成 Task 反而比较快，因为规则明确。

4.4 双链映射与变更同步的机制实现

这部分是 PingCraft 不同于普通“文档转任务工具”的地方。设计目标刚才说了，需求文档重新导入后要能增量更新对应工作项。

实现上核心是文档分块的 hash 对比。我每次导入文档时，对每个 chunk 计算 hash，跟数据库里存的旧 hash 比对，得到三类结果：新增的 chunk、内容变化的 chunk、被删除的 chunk。

新增 chunk：走完整解析流程，创建新工作项，生成新 TraceLink。
内容变化的 chunk：提取变更文本与旧文本的差异，结合差异文本更新对应工作项的描述和验收标准，同时把 Link 的 status 置为 stale 并通知人工确认。
删除 chunk：输出“建议删除工作项”的清单，交人工决策，不会自动删。

这套机制跑起来之后，最直观的效果是：产品经理改完文档重新导入，5 分钟内系统就能告诉研发负责人“这轮变更影响 3 个 Story、7 个 Task，其中 2 个需要更新验收标准”。这在以前至少需要半天的人工梳理。

4.5 人工审核节点的具体设计

人工审核放在两个位置，我用一个轻量级的 Web UI 来呈现。

第一个审核点是生成 work_items.yaml 之后、批量导入之前。界面上左边显示工作项列表，右边显示每个工作项对应的需求原文片段，审核人可以直接修改标题、描述、验收标准，也可以删除某个工作项。修改完点击确认，系统把最终结果写回数据库并触发导入流程。

第二个审核点是变更同步时。界面会标出变更的影响范围，用表格列出“需求原文变更摘要 / 影响的旧工作项 / 建议的新描述”，审核人逐条确认“更新”或“忽略”。

起初我尝试过全自动化，不做任何人工确认。结果有一次模型把“登录失败锁定”识别成一条独立业务规则，自动生成后直接建到了项目里，差点让开发实现一个完全不存在的需求。从那以后我老实加了人工确认，这个环节不能省。

5. 实操演示：从一份 PRD 到 Jira 工作项全流程

5.1 运行环境与配置准备

先说运行环境。我的技术栈是 Python 3.11 + LangGraph + FastAPI，数据库用的 SQLite，外部系统对接的是 Jira Cloud。整个项目跑在一个 4C8G 的容器里，非常轻量。

关键配置都在 config.yaml 里管理，分为三块：

yaml复制llm:
  provider: anthropic
  model: claude-3-5-sonnet
  max_tokens: 4096
  temperature: 0.2

parser:
  chunk_size: 3000
  overlap_size: 200
  enable_parallel_parse: true

jira:
  url: https://your-domain.atlassian.net
  project_key: OPS
  create_epic: true
  create_story: true
  create_task: true
  assignee_rule: "default_assignee"

这里温度设 0.2 是为了在保持一点灵活性的同时尽量稳定。测试过温度设 0 完全确定，但输出比较僵硬；0.2 是一个比较稳的经验值。

5.2 构造一份示例 PRD 并执行

下面我用一份非常简化的 PRD 演示这个过程。文档内容：

markdown复制# 用户认证模块

## 1. 手机号登录
用户输入手机号，点击获取验证码，系统发送6位验证码到用户手机。
验证码有效期5分钟，每手机号每天最多发送10条。
输入错误验证码超过5次，账号锁定30分钟。
登录成功后进入首页。

## 2. 邮箱登录
用户输入邮箱和密码进行登录。
密码错误超过5次，需要输入图形验证码。
支持忘记密码流程，通过邮箱重置密码。

导入脚本：

bash复制python pingcraft_cli.py import \
  --input docs/user_auth.md \
  --format markdown \
  --output work_items.yaml \
  --workspace demo_workspace

执行过程日志能看到 Agent 的阶段流转：

text复制[01] 开始解析文档... 
[02] 按章节路径切分完成，共 2 个 chunk
[03] 并行解析 2 个 chunk，抽取到 6 个功能点、8 条业务规则、4 条验收标准
[04] 识别出 2 个 Story 主体：「手机号登录」「邮箱登录」
[05] 为 Story 生成 Task 和验收描述
[06] TraceLink 生成完成，共 12 条
[07] 写入 work_items.yaml，待人工审核

5.3 生成的中间文件与导入 Jira

生成的 work_items.yaml 长这样：

yaml复制epics:
  - id: E-1
    title: 用户认证模块重构
    stories:
      - id: S-1
        title: 手机号验证码登录
        acceptance_criteria:
          - 输入正确验证码后登录成功
          - 验证码有效期5分钟，过期后提示重新获取
          - 错误验证码超5次锁定30分钟
        tasks:
          - id: T-1-1
            title: 实现验证码发送接口
          - id: T-1-2
            title: 实现验证码校验逻辑
          - id: T-1-3
            title: 实现账号锁定机制
        trace_links:
          - source: "用户认证模块##手机号登录"
            source_hash: "7a3f6b..."
            relation: refines
      - id: S-2
        title: 邮箱密码登录
        # 省略

审核人用 Web UI 确认无误后，执行导入：

bash复制python pingcraft_cli.py publish --input work_items.yaml --target jira

导入后 Jira 上会按映射关系分别创建 1 个 Epic、2 个 Story、6 个 Task，每条的描述末尾都附带需求原文摘要和链接地址。双击工作项就能看到它的来源，比如任务描述里会写上“来源: 用户认证模块 - 手机号登录”。

5.4 变更同步的实操演示

假设产品经理两天后改了需求，在手机号登录下面加了一句“新增语音验证码功能”。重新导入后，系统输出的变更报告：

text复制[变更检测]
变更范围：用户认证模块 - 手机号登录
受影响工作项：
  S-1 手机号验证码登录（需新增 Task）
  T-1-1 实现验证码发送接口（描述需更新）
  新增建议：T-1-4 实现语音验证码发送

审核人看了报告发现“语音验证码”目前只是产品经理的一句话，还没有明确的业务规则，于是选择先忽略新增 Task，只更新 T-1-1 的描述。这个操作两分钟完成，放在以前不重新开会梳理根本做不到这个响应速度。

6. 常见问题与排查技巧实录

6.1 问题排查速查表

问题现象	可能原因	排查思路	解决方案
实体抽取严重遗漏	文档 chunk 切分过小，上下文不连续	检查 chunk 大小和 overlap	调大 chunk 到 4000-5000，overlap 设为 200-400
生成的 Story 颗粒度太粗	Prompt 里没有明确“业务闭环”定义	检查 Prompt 示例	用 2-3 个正反例加强约束
TraceLink 的 source 定位到错误章节	切分时章节路径传递遗漏	检查 chunk 的元数据	确保切分后每个 chunk 都带完整章节路径
工作项批量导入时接口超时	同时创建几十个任务触发限流	看 Jira API 返回码	增加并发限制，使用 `batch` 模式或串行导入
重复导入导致工作项重复创建	没有做幂等控制	检查是否传入 `workspace_id`	以 `source_hash` 作为唯一键，已存在的直接跳过
模型输出 JSON 频繁格式错误	模型版本或温度设置问题	检查 function calling 是否启用	改走 function calling，不要裸输出 JSON
变更检测误报	文档在线协作时自动格式变化改变 hash	对比 hash 前做文本归一化	去掉空白符、特殊转义后再计算 hash

6.2 三个典型的失败案例复盘

第一个案例已经提过，是缺乏人工审核时模型自动“发挥”创造了一个不存在需求的 Story。这个教训让我养成了一个习惯：凡是会写入生产系统的自动化产物，必须保留一个人工确认的缓冲带。

第二个案例是关于长文档截断的。当时一份 80 页的 PRD 直接喂进去，结果模型只处理了前 20 页，后面 60 页的内容一个实体都没抽出来。排查后发现是子 Agent 的 max_tokens 不够，模型在最前面还没处理完就被截断了。后来我改成先切分再并行解析，并且给每个子 Agent 单独设置 max_tokens，这个坑就再也没踩过。

第三个案例是 Jira 的限流问题。批量创建 50 个工作项时，Jira Cloud 直接返回 429。后来把创建请求改成串行，每条之间睡 0.5 秒，再加一个简单的重试退避，问题解决。这个坑提醒我，Agent 调用外部系统时，速率控制不能只在代码里写死，要结合目标系统的实际限制来设计。

6.3 几个值得分享的实用技巧

最后补充几个日常使用中沉淀下来的小技巧，不算什么宏大设计但非常实用。

关于文档格式：强烈建议先让产品团队统一用 Markdown 写 PRD，或者至少用带规范标题层级的结构。这能显著降低 Agent 的理解成本。实测统一标题层级后，实体抽取的准确率从 82% 提升到了 93%，只是格式规范化这一个变化。

关于 Prompt 版本管理：需求解析类的 Prompt 改动很频繁，我建议把 Prompt 当成代码来管理，每个版本打 tag，并且在每次跑批量任务时记录用的哪个 Prompt 版本。这样当某次输出质量回退时，能快速定位是 Prompt 问题还是数据问题。

关于置信度阈值：我设了两档阈值，置信度低于 0.7 的实体不进工作项，直接进“待人工确认池”；置信度在 0.7 到 0.9 之间的，生成工作项但标记为“低置信”，要求审核人多看一眼。这个设计平衡了自动化和安全性，跑下来体验很好。

再分享一个小经验：在实现变更同步时，不要一上来就追求完全自动更新。先做成“变更检测 + 人工确认更新”，跑一两个迭代，收集大量真实变更日志后，再逐步把那些重复性高、判断规则清晰的变更类型自动化掉。这样做既能保证准确率，又能持续观察模型的判断模式，很容易找到可以放开的边界。

PingCraft 这个项目我从零搭到稳定运行，最大的体会是：Agent 项目在 demo 阶段都很惊艳，真正拉开差距的是在生产环境下对边界情况、幂等性、人工介入机制这些细节的处理。用 Agent 把需求拆成工作项这条路，方向完全正确，但别指望一次成型，把它当成一个需要持续投入打磨的工具来做，才会有真正好用的产出。