为游戏业务团队构建只读代码问答 Agent：架构、性能与安全实践

摘要：游戏规则、数值和活动配置最终由代码与项目配置决定。策划、测试、运营和客服在核对规则或处理玩家反馈时，往往需要研发协助定位实现，零散问题因此反复打断研发工作。为缩短这条确认链路，我们构建了一套只读代码问答 Agent：代码副本和索引集中保存在常驻服务中，会话环境只通过 HTTP 上的只读 MCP 工具查询代码和配置。本文分别从业务体验和技术实施角度，介绍方案功能、准确性机制、安全边界、性能、管理方式与成本，并结合合成样本测试和游戏客户的试用结果说明实际表现。

01 一、业务团队何时需要代码问答 Agent

02 二、业务人员实际能得到什么

03 三、参考架构与运行机制

04 四、如何判断答案是否可信

05 五、性能和容量表现如何

06 六、安全边界与防护措施

07 七、项目管理与成本

08 八、适用范围与采用判断

一、业务团队何时需要代码问答 Agent

策划确认技能规则、测试核对触发条件、运营检查活动奖励、客服解释玩家反馈，这些工作都可能需要回到代码和配置中寻找事实。如果此类问题频繁转给研发，只读代码问答 Agent 可以缩短“业务描述—代码定位—结果解释”的链路。系统处理重复的事实查询，研发则专注于证据不足、存在歧义或需要设计判断的问题。

对业务人员而言，理想的使用方式是直接提出业务问题，而不是先理解仓库目录和代码符号。系统负责把业务语言转换成检索动作，读取源码、JSON、Excel 或 CSV 配置，再用业务语言回答，并把文件和关键符号放入研发复核区。

使用者希望完成的工作	系统提供的能力	仍需研发参与的情况
确认规则、数值和配置来源	查询当前代码和项目内配置	证据不足、实现存在多种解释
核对触发条件和边界	定位符号、读取调用关系和相关文件	需要运行游戏引擎或做数值模拟
处理玩家反馈涉及的机制	用业务语言解释，并附技术出处	需要设计判断或跨系统数据
在同一入口完成查询和反馈	通过 CardKit 展示分析状态、流式答案、证据区、追问和反馈入口	需要人工审批或执行变更

这套方案只面向事实查询。它不运行游戏引擎，不修改项目文件或配置，不提交代码，也不比较多个分支。

为什么不直接使用通用桌面 Agent

通用桌面 Agent 可以完成代码检索，但常见做法是把仓库下载到个人终端，并开放文件系统、Shell、代码执行或 Git 工具。这些能力适合研发，却超过了业务人员的查询需要：

风险	具体影响
代码副本和凭证分散	更多终端持有完整仓库或拉取凭证，增加泄露风险和权限回收成本
工具权限超过需求	错误工具调用可能修改文件、执行代码或产生不应提交的变更
版本和证据难以判断	本地分支、未提交修改或过期副本可能混入答案
模型与日志边界不一致	不同终端的模型端点、代理和日志配置难以统一核查

经过终端管控、最小权限配置和模型服务审查，桌面 Agent 仍可用于研发代码问答。但对策划、测试、运营和客服，集中式只读服务更容易统一代码范围、版本、工具权限和审计策略。

二、业务人员实际能得到什么

2.1 统一查询源码与项目配置

这里的“代码”泛指能够作为事实依据的源码、配置和文档，不限定编程语言。本文的性能测试样本以 C# 为主，但实际查询范围取决于索引器的解析能力和项目接入清单。规则和数据还可能分散在 JSON、Excel、CSV、README、设计文档或自定义脚本中，因此只查询一种语言或文件类型通常无法回答完整问题。

系统支持一个项目配置多个仓库。查询未指定仓库时，会在项目清单允许的仓库中检索并合并结果；清单外的仓库名会被拒绝。Git 仓按清单指定的 ref 定时同步，未指定时跟随远端默认分支；无法通过 Git 接入的仓库由运维推送快照，答案反映最近一次成功推送。因此，两类仓库不能一概称为“实时主分支”。

2.2 中文问题可以检索英文代码符号

业务人员使用中文概念和玩家表述，代码符号多为英文，项目里还可能存在缩写、历史代号和内部命名。直接用中文搜索代码，通常只能命中注释，甚至没有结果。

索引主机会离线扫描候选文本，把真实出现的中文业务词与英文符号关联。候选范围包括代码、配置、README 和设计文档；代码和配置来源的置信度高于文档来源。术语表只为 Agent 增加检索词，不参与最终事实判断，答案仍需回到源码或配置表核对。

一个约 1.4 万个文件的中文开源游戏框架首次生成了 2,634 个词条和 4,881 条关联记录。按当时 Bedrock 上 Opus 4.8 的价格折算，模型费用约 372 美元。全量生成只适合作为可选构建任务，不应放入在线问答流程。模型生成的术语映射还需要确定性校验；当前校验并不核对引用行，也不验证英文符号是否确实出现在文件中。

2.3 在同一张卡片中完成查询、复核、追问和反馈

在本文记录的问答中，端到端耗时中位数约为 49 至 56 秒。这个时间包含多轮模型调用、工具往返、网络、会话调度和流式收尾，不能理解成单次模型调用或“模型调度”通常需要几十秒。

为了让业务人员不必切换到开发工具，本方案把一次问答的交互集中在同一张 CardKit 卡片中：

接到问题后立即建卡，显示分析状态和计时；
模型开始输出后，正文和 Markdown 表格按增量持续更新；
生成研发复核区时先展开，完成后自动折叠，业务正文保持可读；
收尾时补充图表、追问入口和反馈入口，用户可以继续确认问题或提交反馈。

静态等待页在任务完成前无法提供新信息；普通流式输出只能不断向后追加文本。本方案使用动态 CardKit：网关可以更新计时和处理阶段，逐步补全正文和表格，展开或折叠证据区，并在完成后增加追问与反馈操作。用户看到的是一张随 Agent 调研过程逐步完善的任务卡片，而不是一条不断变长的文本流。

[图 1 一次问答的卡片更新过程]

这项设计的价值不只是缓解等待焦虑，而是让提问、查看业务答案、展开代码证据、继续追问和提交反馈形成一个完整闭环。流式展示本身不会缩短端到端耗时。

三、参考架构与运行机制

3.1 参考架构由哪些组件组成

这套架构的核心是把会话执行环境与代码数据面分开。会话 microVM 不挂载仓库，也没有本地文件读取工具；代码定位、调用关系、全文搜索、源码和配置表读取均通过只读 MCP 接口完成。

[图 2 生产部署结构]

组件	职责
bot-gateway	接收飞书事件、去重、路由会话并流式更新答案卡片
AgentCore Runtime	提供会话隔离的 microVM 运行环境，在其中运行 Claude Agent SDK
index-service	保存代码副本和每仓索引，通过 HTTP 提供定位、搜索和文件读取

3.2 会话复用与扩容

每个项目使用独立的飞书机器人、网关进程和 Runtime。AgentCore 根据 session ID 将后续请求路由到同一个 microVM。网关在此基础上维护空闲环境池：新飞书对话优先绑定空闲的 runtimeSessionId，没有可用环境时再创建新会话并启动 microVM。同一标识下的调用由网关串行执行。

这里的“空闲环境复用”是网关层实现，不是 AgentCore 自动把新 session 分配到旧 microVM。即使复用运行环境，每次调用仍会创建新的 SDK 会话。网关把历史问答显式加入本轮提示词，模型不会自动继承其他飞书对话的上下文。Agent 在 microVM 中运行，只能调用 index-service 提供的工具。同一项目的会话共享索引服务中的代码副本，因此新建 microVM 时不需要再次拉取代码。

3.3 代码副本和索引更新

问答系统新增的完整代码副本只保存在索引主机本地磁盘。代码更新有两条路径：

Git 仓定时同步项目清单指定的 ref。
本地仓由运维推送快照；首次推送完整建图，后续由常驻进程增量更新。

[图 3 代码更新与索引刷新]

这种设计让扩容无需重复拉取代码，但索引有预处理成本。测试样本实际建图 1,753 个文件，其中 1,752 个为 C#，首次构建约 24 秒。当前实现在部署或仓库接入阶段等待索引完成，再启动查询服务；这段时间不在用户问答路径中。

四、如何判断答案是否可信

只读工具解决了权限问题，答案质量还取决于检索和证据。技术团队需要同时建设代码检索、证据展示和异常监控，帮助使用者判断答案是否适用于当前项目。

4.1 用索引缩小候选范围，再读取真实文件

全文搜索可以找到字符串出现的位置，却不能直接回答“谁调用了这个方法”或“修改这个符号会影响哪些模块”。CodeGraph 预先解析代码并建立符号、调用关系图，用于缩小候选范围，再读取真实文件。最终结论仍以本轮实际读取的源码或配置为依据。

4.2 在答案中显示证据和不确定性

系统提示要求 Agent 只把本轮读取过的源码和配置作为事实依据。检索为空时，答案明确说明未找到；存在多种解释时，先确认问题范围；证据不足时，标注不确定性并转交研发。技术出处放在折叠区，业务正文保持可读。

运行时会记录工具调用和部分空结果次数，网关则统计证据区引用文件数和结构化用户反馈。未调用工具且没有证据引用的长答案会被标记为异常。当前机制用于发现可疑回答；现有数据尚未形成可发布的准确率指标。

五、性能和容量表现如何

5.1 何时值得建设索引

测试项目为 16 GB、75,595 个文件，其中 C# 文件 1,752 个，其余主要是资源和元数据。它模拟“大体积、低代码占比”，不是客户真实工程。测试机为 AWS EC2，ARM 8 核、30 GiB 内存、通用型 EBS，运行 Ubuntu 24.04；每种方法查询同一个已知类名，执行 5 次并取中位数。

方法	冷缓存	热缓存
grep -r 全仓扫描	127.4 秒	7.68 秒
ripgrep 全仓扫描	69.1 秒	0.49 秒
CodeGraph 索引查询	1–5 毫秒	1–5 毫秒

热缓存下的 ripgrep 并不慢。问题在于生产环境不能假定所有文件都已进入页缓存；新实例、内存压力和仓库更新都可能产生冷缓存或部分冷缓存。对交互式问答而言，几十秒的偶发扫描会形成长尾。

5.2 用完整问答流程评估实际体验

搜索工具的速度不等于完整问答体验。端到端耗时还包括建卡、microVM 调度、多轮模型与工具往返以及流式收尾。我们记录了四批配对测试：两条路径使用相同的问题、模型、代码仓和业务提示，但系统提示、可用工具和计时入口并不完全一致。基线从本地 claude -p 开始计时，索引方案从飞书端开始计时。

[图 4 四批端到端平均耗时对比]

四批基线路径平均耗时分别为 210、137、265 和 128 秒，索引路径分别为 58、36、52 和 47.5 秒。换成更直观的说法：在这组测试中，索引路径耗时为 36 至 58 秒，基线路径为 128 至 265 秒，用户等待时间降到原来的约五分之一至三分之一。由于两条路径的系统提示、可用工具和计时入口并未完全对齐，这组结果用于说明完整系统路径的耗时差异，不用于拆分或比较单个组件的性能。

5.3 索引完成后，优化重点在哪里

以下 113 次历史问答来自四个项目。问题类型和难度不同，因此这些数据用于观察实际问答耗时，而不是比较代码规模。现有记录中，不同项目的端到端中位耗时接近：

代码规模	问答中位耗时
1.3 万行	49 秒
30 万行	53 秒
50 万行	51 秒
86 万行	56 秒

耗时项	实测结果
工具调用	中位 7 次，合计 0.26 秒，最长 1.1 秒
模型调用链路	按本文日志口径，约占总耗时的 98%
冷启动影响	中位耗时由 52 秒增至 64 秒

在这组记录中，工具延迟不是主要瓶颈。优化应优先减少首轮检索词偏差、无效工具往返和完成任务所需的总轮次，而不是继续压缩毫秒级索引查询。

另一次 15 路并发 CodeGraph 查询中，15 个请求均返回 HTTP 200 和非空结果，索引健康状态未变化。

六、安全边界与防护措施

本节聚焦代码问答链路中的四类控制：减少完整代码副本、限制写入和执行能力、隔离项目访问，以及降低敏感信息进入答案或日志的概率。模型服务、网络、IAM 和人员权限仍按企业现有安全流程评估。

[图 5 代码访问的三类边界]

6.1 只向 Agent 暴露只读工具

Agent 侧不启用 Bash、本地读写和提交工具。index-service 只注册白名单内的只读工具，最多 9 个：7 个用于代码定位和文件读取，2 个用于术语表查询。在当前工具配置下，Agent 不具备修改、提交或执行项目代码的工具入口。

6.2 集中访问减少代码副本和 Git 凭证暴露

集中式索引把完整代码副本统一保存在索引主机。会话按需读取文件，无法通过 Shell 打包整个仓库，也拿不到拉取仓库所需的 Git 凭证。如果仓库本身包含密钥、连接串等敏感信息，文件工具仍可能读到，因此仓库扫描、密钥轮换和权限控制继续沿用常规安全流程。

代码访问链路位于 VPC 内，索引接口端口只向指定安全组开放。Runtime 没有公网 IP，当前部署使用 NAT 提供所需的出站访问。这不是唯一实现方式：Amazon Bedrock 和 AgentCore 均支持通过 VPC Endpoint/AWS PrivateLink 建立私有连接。本文描述的是当前部署选择，不能概括为“访问 Bedrock 必须经过 NAT”。这里控制的是代码访问入口和索引接口的入站范围，不是完整的出站隔离。

6.3 根据项目信任关系选择隔离方式

同一信任域内的多个项目可以共用索引主机和安全组，并通过进程、端口和仓库清单进行逻辑隔离。互不信任的项目使用独立索引主机和安全组，从主机和网络层面分开访问边界。

Agent 读取的代码片段仍会进入模型上下文，也可能显示在研发复核区。集中式架构可以减少代码副本和越权访问机会。

6.4 已实施的提示词注入防护

本方案在 Agent 启动和代码查询两个阶段实施了基础的提示词注入防护。启动时设置 setting_sources=[]，关闭用户、项目和本地目录中的文件系统配置来源，包括相关 settings.json、CLAUDE.md 和 Skills，避免仓库中的 Agent 配置或项目指令被自动加载。

查询过程中，工具返回的代码、注释和配置统一作为数据进入模型上下文，系统提示明确要求忽略其中可能出现的行为指令。该策略与只读工具白名单、输出脱敏和异常监控共同形成组合防护，降低仓库内容影响 Agent 行为的风险。

七、项目管理与成本

7.1 项目与版本管理

项目接入前，技术团队需要明确：

可见仓库清单，以及 Git 仓对应的 ref。
无法通过 Git 接入时的快照推送责任和更新频率。
项目是否属于同一信任域，能否共享索引主机。
哪些文件类型可进入索引和模型上下文。
代码、配置和未来线上配置的来源优先级。

代码能说明规则如何实现，却未必包含线上当前生效值。热更新参数、功能开关和分环境覆盖如果只保存在配置中心，仅查看仓库可能得到默认值或过期快照。当前系统尚未接入配置中心；后续可将其作为只读数据源，回答同时标明代码默认值、线上值、环境和读取时间，并通过项目、环境和字段白名单限制范围，密钥类配置不得进入模型。

7.2 已记录的模型费用

截至 2026 年 6 月 25 日，近 30 天统计包含 843 次问答。按当时 Bedrock 上 Opus 4.8 的价格折算，单次问答的模型费用平均为 0.167 美元，中位数为 0.146 美元。费用大致一半来自输出 token，另一半来自提示词缓存读取。EC2、AgentCore、EBS、网络和监控等基础设施费用未计入其中。

术语表的首次全量生成是另一项可选成本：前述约 1.4 万个文件的项目按当时价格折算约 372 美元。纯英文项目可能没有可用的中文映射，不一定值得执行这项任务。

八、适用范围与采用判断

该方案已在游戏客户环境中试用，策划、测试、运营和客服通过真实项目代码进行查询。试用发现了客户自定义脚本格式的适配需求。完成初步试用后，客户开始结合自身脚本和业务需求继续迭代，并自行扩展解析能力。

8.1 适合采用的条件

存在大量或持续增长的只读代码和配置事实查询需求；查询越频繁，自动化承接的收益越明显。
可以根据实际调用量扩展 Runtime 会话池和索引服务容量。
可以明确仓库清单、版本来源和代码同步责任。
业务人员需要易读答案，研发可以处理歧义和设计判断。
项目处于同一信任域，或愿意为不同信任域部署独立主机。

8.2 需要其他能力补充的场景

需要运行游戏引擎、做数值模拟或验证运行时行为。
需要修改配置、提交代码或比较多个分支。
需要把互不信任的项目放在同一索引主机上。
需要线上实时配置，但尚未接入配置中心。

8.3 延伸阅读

➡️ 下一步行动：

相关产品：

Amazon Bedrock — 用于构建生成式人工智能应用程序和代理的端到端平台
Amazon Bedrock AgentCore — 加快代理投入生产的速度
Amazon VPC — 隔离云网络
Amazon EC2 — 安全且可调整大小的计算容量
Amazon EBS — 高性能数据块存储

相关文章：

立即咨询 → 从 AI 规划到落地实施，我们的专家团队为你全程护航。

*前述特定亚马逊云科技生成式人工智能相关的服务目前在亚马逊云科技海外区域可用。亚马逊云科技中国区域相关云服务由西云数据和光环新网运营，具体信息以中国区域官网为准。

本篇作者

AWS 架构师中心：云端创新的引领者

探索 AWS 架构师中心，获取经实战验证的最佳实践与架构指南，助您高效构建安全、可靠的云上应用

亚马逊AWS官方博客