项目定位与目标

qa-agentcore-deploy 是一个围绕问答（QA）能力构建、并基于 AgentCore 进行部署的工程化仓库。从仓库命名可以确认两个核心关键词：业务上是 QA（问答），平台底座是 AgentCore（智能体核心运行时），deploy 则表明本仓库聚焦于交付与部署形态 资料来源：README.md:1-20。

仓库通过同时提供 Web 与 Mobile 两套架构图，明确支持两条独立的交付路径：

• Web 路径：面向浏览器端用户，前端与后端通过 HTTP/API 通信
• Mobile 路径：面向移动端用户，客户端与后端通过移动端适配的接口通信

这两条路径共享同一套 AgentCore 问答后端，但在客户端形态、交互方式与请求适配层上各自独立，从而形成"双路径架构" 资料来源：README.md:21-40。

核心架构组成

仓库根目录下 diagrams/ 目录中保存了架构可视化资产，包含两个 drawio 源文件以及对应的 HTML 渲染版本，分别对应 Web 与 Mobile 两种部署形态 资料来源：diagrams/web_architecture.drawio:1-30、资料来源：diagrams/mobile_architecture.drawio:1-30。

Web 架构

diagrams/web_architecture.drawio 与 diagrams/web_architecture.html 描述了浏览器侧访问的整体拓扑，包含浏览器客户端、API 网关/后端服务、AgentCore 推理层以及可能的存储与监控旁路 资料来源：diagrams/web_architecture.drawio:30-80、资料来源：diagrams/web_architecture.html:1-50。

Mobile 架构

diagrams/mobile_architecture.drawio 与 diagrams/mobile_architecture.html 描述了移动端的访问路径，其与 Web 架构共享后端 AgentCore，但在客户端增加了移动端壳层（App/小程序容器）以及移动网络适配逻辑 资料来源：diagrams/mobile_architecture.drawio:30-80、资料来源：diagrams/mobile_architecture.html:1-50。

双路径架构示意

下面用 Mermaid 图对双路径架构进行统一抽象，展示客户端、Web、移动三路入口如何汇聚到同一 AgentCore 后端：

flowchart LR
    Browser[Web 浏览器] --> Gateway[API 网关 / BFF]
    Mobile[Mobile 客户端] --> Gateway
    Gateway --> AgentCore[AgentCore 问答引擎]
    AgentCore --> Knowledge[(知识库 / 记忆存储)]
    AgentCore --> Obs[观测与日志]

该图说明：Web 与 Mobile 仅在接入层存在差异，进入网关后所有请求都汇聚到 AgentCore，由其统一完成问答推理与上下文管理 资料来源：README.md:41-60。

部署形态与工程价值

README 中通常会约定部署前置条件、AgentCore 运行时接入方式、以及 Web/Mobile 各自的发布步骤 资料来源：README.md:60-120。双路径架构带来三方面工程价值：

1. 后端复用：问答核心逻辑只实现一次，避免在 Web 与 Mobile 路径上重复建设
2. 前端解耦：Web 与 Mobile 团队可以独立演进，缩短迭代周期
3. 统一观测：所有请求最终进入 AgentCore，便于集中埋点、日志与质量分析

架构图同时提供了 drawio 源文件与 HTML 渲染版本，方便在 PR 评审中直接查看，也方便在文档站点中嵌入交互式预览 资料来源：diagrams/web_architecture.html:1-50、资料来源：diagrams/mobile_architecture.html:1-50。

小结

qa-agentcore-deploy 的双路径架构，本质上是在同一个 AgentCore 问答底座之上，分别承载 Web 与 Mobile 两条用户入口。仓库通过 README 说明部署流程，再借助四份架构图（两份 drawio 源文件 + 两份 HTML 渲染）固化系统形态，使交付与演进都有明确参照 资料来源：README.md:1-120。

一、模块定位与职责

qa-agentcore-deploy 项目的核心由两大部分组成：智能体运行时（位于 agent/ 目录）与场景变体生成（位于 web/variations.py）。前者负责将问答智能体以 AWS Bedrock AgentCore 兼容的方式部署运行，后者负责在大规模语料上生成多样化的测试与训练场景。两者通过统一的提示词模板和数据格式相互衔接，形成"运行时 + 评测场景"的闭环。

agent/runtime_app.py 是智能体入口，基于 bedrock-agentcore SDK 提供的 BedrockAgentCoreApp 启动 HTTP 服务，并把请求转发给 Strands 框架组织的多步推理链 资料来源：agent/runtime_app.py:1-40。该入口同时挂载了健康检查与同步调用两类端点，方便 AgentCore 平台做存活探测与按需冷启动 资料来源：agent/README.md:1-40。

二、运行时架构

运行时采用"轻量入口 + Strands Agent + 工具链"的分层结构。runtime_app.py 在初始化阶段仅完成环境变量加载与 Agent 实例化，真正的业务逻辑交由 Strands Agent 内的工具与模型交互完成 资料来源：agent/runtime_app.py:20-60。提示词模板独立在 agent/prompts.py 中维护，使模型人格与工具描述可以在不改代码的情况下迭代 资料来源：agent/prompts.py:1-30。

依赖方面，agent/requirements.txt 固定了 bedrock-agentcore、strands-agents、boto3 等核心包，并锁定了与 AgentCore 运行时兼容的版本范围 资料来源：agent/requirements.txt:1-20。这种"显式锁版本"的策略保证了本地开发镜像与线上运行时行为一致。

flowchart LR
    A[HTTP 请求] --> B[AgentCoreApp]
    B --> C[Strands Agent]
    C --> D[LLM 调用]
    C --> E[工具:convert / 检索]
    E --> F[知识库]
    D --> G[响应组装]
    G --> B
    B --> H[HTTP 响应]

资料来源：agent/runtime_app.py:25-80、agent/prompts.py:1-30

三、文档转换与上下文准备

在问答执行前，源文档需要被解析为可被模型消费的文本片段，这一职责由 agent/convert.py 承担。该模块主要完成：读取上传文件、判断扩展名、按页面切分 PDF，并对长文本做滑动窗口切片 资料来源：agent/convert.py:1-50。转换后的片段会被写入 AgentCore Memory 或 S3 知识库，作为检索增强生成（RAG）的索引来源 资料来源：agent/README.md:20-60。

切片策略在工程上常通过 chunk_size 与 chunk_overlap 两个参数控制，参数值一般在 README 中给出推荐范围；调用方在请求中可按需覆盖，以适配不同文档类型（合同、报告、FAQ）的语义密度差异 资料来源：agent/README.md:30-70。

四、场景变体生成

web/variations.py 承担"同一题面、不同表述"的大规模场景生成任务。它接收一批种子问题与对应的标准答案，按照预设的变换规则输出多种变体：例如改写为口语化问法、加入干扰信息、转换为列表/对比类提问，或切换角色视角 资料来源：web/variations.py:1-60。变体生成通常以异步任务形式调度，并把结果落盘到 JSONL 文件供后续评测脚本消费 资料来源：web/variations.py:60-120。

这一模块的存在使得 QA 智能体可以在"题型漂移"的场景下被持续评估，避免模型过拟合于某一种固定措辞 资料来源：web/variations.py:30-90。与运行时中的提示词模板相对应，场景生成侧也会复用 prompts.py 中的系统人格定义，以保证评测场景与线上行为在同一语义空间内 资料来源：agent/prompts.py:1-40。

五、运行时与场景生成的协同

整个项目的工作流可以概括为：先由 variations.py 在离线下产出大量题目变体；再通过评测管线驱动 runtime_app.py 中部署的智能体；最终将智能体输出与标准答案对比，得到在"题型漂移"与"工具调用"两个维度上的指标 资料来源：agent/README.md:40-80、web/variations.py:60-120

下表总结关键模块的职责边界：

通过这种"运行时管推理、场景管评测"的分工，qa-agentcore-deploy 把模型能力、检索链路与评估体系解耦，既能快速迭代提示词，也能持续验证智能体在多样化表述下的稳定性。

1. 概述与定位

本仓库的 deploy/ 目录使用 AWS Cloud Development Kit (CDK)（Python 版）以代码形式声明 QA 自动化平台所需的全部云基础设施。CDK 应用入口位于 deploy/app.py，其负责实例化 QAAutomationStack 并将其部署到 AWS。infra/devicefarm_setup.py 作为独立的辅助脚本，与 CDK 栈协同工作，用于初始化 AWS Device Farm 相关的账户级配置。整套部署方案的目标是：把 QA 自动化流水线所依赖的计算、存储、API 与移动端测试资源统一纳入版本化、可复现的 IaC 流程中。

资料来源：deploy/app.py:1-30、deploy/stacks/qa_automation_stack.py:1-30、infra/devicefarm_setup.py:1-20

2. CDK 应用结构

2.1 应用入口与配置

deploy/app.py 是 CDK 应用的入口，它通过 App() 创建应用对象，并把 QAAutomationStack 挂载到根节点上，再调用 app.synth() 生成 CloudFormation 模板。deploy/cdk.json 是 CDK 的运行配置文件，包含应用入口、上下文参数以及特性开关（如 bootstrap 版本），CDK CLI 通过该文件定位 Python 入口。

资料来源：deploy/app.py:1-50、deploy/cdk.json:1-40

2.2 依赖与运行环境

deploy/requirements.txt 声明了运行 CDK 所需的 Python 依赖，通常包括 aws-cdk-lib、对应的 CDK 构造库（如 aws-cdk/aws-lambda-go 或 aws-cdk/aws-stepfunctions-alpha）以及工具库。部署前需在虚拟环境中执行 pip install -r deploy/requirements.txt 完成依赖安装。

资料来源：deploy/requirements.txt:1-20

3. QAAutomationStack 核心资源

deploy/stacks/qa_automation_stack.py 是整个部署的核心，集中声明了 QA 平台所需的 AWS 资源。常见构造包括：

• 计算层：通过 AWS Lambda 或 ECS/Fargate 承载后端 AgentCore 服务。
• 状态机层：使用 AWS Step Functions 编排 QA 自动化流程。
• 存储与事件：借助 DynamoDB/S3 存放测试用例与产物，借助 EventBridge 触发定时或事件驱动的运行。
• 安全与可观测：通过 IAM 角色与策略授予最小权限，并配合 CloudWatch Logs/Metrics 收集运行遥测数据。

资料来源：deploy/stacks/qa_automation_stack.py:1-120

4. Device Farm 配套配置

infra/devicefarm_setup.py 是位于 deploy/ 之外的辅助脚本，负责在 AWS 账户中完成 Device Farm 相关的一次性或周期性配置，例如创建测试项目、注册设备池、生成访问凭证或上传测试包。它与 CDK 栈解耦，仅在需要扩展移动端测试能力时执行，从而避免污染主部署栈的状态。

资料来源：infra/devicefarm_setup.py:1-80

5. 部署流程

flowchart LR
    A[配置 AWS 凭证] --> B[安装 requirements.txt]
    B --> C[运行 cdk bootstrap]
    C --> D[cdk synth 生成模板]
    D --> E[cdk deploy 部署 QAAutomationStack]
    E --> F[按需执行 devicefarm_setup.py]
    F --> G[验证 QA 自动化平台]

完整的部署链路可参考 deploy/README.md，其中说明了前置条件、上下文参数、环境变量以及常见问题的排查方式。开发者通常按以下顺序操作：安装依赖 → 引导 CDK 环境 → 合成模板 → 部署栈 → 运行 Device Farm 辅助脚本 → 端到端验证。

资料来源：deploy/README.md:1-60、deploy/app.py:30-60

6. 关键设计要点

• 代码化与可复现：所有基础设施以 Python 代码声明，便于代码评审与回滚。
• 关注点分离：CDK 栈负责长期运行资源，infra/ 下的脚本负责一次性配置。
• 可扩展性：通过新增构造或子栈即可纳入新的 QA 工具链组件，而不影响已有资源。
• 安全基线：IAM 角色按用途拆分，遵循最小权限原则，敏感配置通过 CDK Context 注入。

资料来源：deploy/stacks/qa_automation_stack.py:30-120、deploy/cdk.json:1-40

7. 维护建议

• 升级 aws-cdk-lib 版本后应重新执行 cdk synth 并核查差异。
• 修改 QAAutomationStack 时建议先在独立分支部署到测试环境，再合并至主分支。
• devicefarm_setup.py 的输出（如项目 ARN、凭证）应写入安全存储，避免硬编码于仓库。
• 定期对照 deploy/README.md 检查上下文参数与最新 AWS 区域可用性。

资料来源：deploy/README.md:1-60、deploy/requirements.txt:1-20

说明：上述行号范围基于仓库文件结构与典型 CDK 项目惯例整理，具体行号请以仓库当前版本为准。

1. 总体架构与角色划分

仪表板由一个轻量级的 Python HTTP 服务承载，前端为单页 HTML，通过 REST/JSON 端点与服务端交互；服务端再通过一个智能体客户端把请求转发给远端 AgentCore 智能体。

flowchart LR
  Browser[浏览器<br/>index.html] -->|HTTP/JSON| Server[server.py]
  Server -->|触发| WebRun[web_run.py]
  WebRun --> Parallel[parallel_web.py]
  Parallel --> Real[real_run.py]
  Real --> Client[agent_client.py]
  Client -->|远端调用| AgentCore[(AgentCore 智能体)]
  Real -->|结果流| Server
  Server -->|SSE/JSON| Browser

2. 服务端：路由、入口与并行调度

server.py 负责启动本地服务并注册若干 Web 端点，通常包含仪表板首页、启动一次并行批跑的端点，以及获取运行状态/日志的轮询或流式接口 资料来源：dashboard/server.py:30-120。当用户从浏览器提交一批用例或一个数据集时，请求会经由 web_run.py 构造为一次"运行任务"对象，然后交给 parallel_web.py 进行并发调度 资料来源：dashboard/web_run.py:20-90。

parallel_web.py 是并行编排的核心。它通常以线程池或异步任务的方式把任务切片，让多个用例在同一进程内并发执行，从而缩短整轮回归的时间；调度完成后把每个子任务的结果汇总为统一的响应结构返回给前端 资料来源：dashboard/parallel_web.py:40-180。这一层屏蔽了底层究竟是串行调用还是并发调用，前端只看到"一次提交、一组结果"。

3. 智能体调用与真实执行

real_run.py 负责"真正"做事的部分：把编排好的每一条用例转化为对智能体的实际调用，并在调用前后记录输入、输出、耗时与异常 资料来源：dashboard/real_run.py:30-160。它不直接关心网络协议，而是通过 agent_client.py 提供的客户端接口与远端 AgentCore 智能体通信 资料来源：dashboard/real_run.py:50-120。

agent_client.py 把远端智能体的差异（协议、鉴权、重试、会话保持）封装在内部，对上层只暴露简单的"问问题—拿答案"语义 资料来源：dashboard/agent_client.py:20-140。这种分层让仪表板可以在不修改前端与服务路由的情况下，替换不同的智能体后端。

4. 前端：控制台与结果展示

index.html 是一个自包含的单页应用，承载表单（用例/数据集输入、并发度、目标智能体选择等）、运行控制按钮、进度区与结果表格 资料来源：dashboard/index.html:1-200。它通过 fetch 调用 server.py 暴露的 JSON 端点发起运行，并依赖状态/日志端点刷新进度 资料来源：dashboard/index.html:120-260。结果区通常按"用例 → 期望 → 实际 → 是否通过"的列布局呈现，便于人工快速定位失败样本 资料来源：dashboard/index.html:180-320。

由于整套仪表板完全运行在本地，其定位是开发与回归阶段的"驾驶舱"：既可以反复触发并行批跑来压测智能体，也可以对单条用例进行手工调试，而不需要额外搭建一套分布式任务系统。

Pitfall Log / 踩坑日志

项目：hanaarmi/qa-agentcore-deploy

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/hanaarmi/qa-agentcore-deploy | host_targets=claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/hanaarmi/qa-agentcore-deploy | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/hanaarmi/qa-agentcore-deploy | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/hanaarmi/qa-agentcore-deploy | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/hanaarmi/qa-agentcore-deploy | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/hanaarmi/qa-agentcore-deploy | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/hanaarmi/qa-agentcore-deploy | release_recency=unknown