V8 仓库 Gemini CLI 提示词体系实战GEMINI.md 组装、Prompt 模板与子代理编排【免费下载链接】v8The official mirror of the V8 Git repository项目地址: https://gitcode.com/gh_mirrors/v81/v8本文面向希望用 AI 编码助手gemini-cli开发 V8 的工程师讲解agents/prompts/目录的提示词工程方案如何用语法把common.md与模板拼装成本地GEMINI.md系统指令如何用/memory show验证导入结果并结合仓库中的构建、调试、测试命令与子代理subagent配置形成一套可复用的 V8 开发智能体工作台。读完本文你将能独立搭建并维护自己的 V8 Prompt 工作区。一、目录定位agents/prompts/是什么在 V8 仓库的 agents/prompts/README.md 中明确说明该目录存放面向 V8 的通用 Promptcommon prompt以及用于教会 Agent 特定工具的模板 Prompttemplate prompts一切设计意图都是配合 gemini-cli 使用。从仓库实际内容看agents/prompts/下共三个文件/子目录agents/prompts/README.md使用说明即本文主体agents/prompts/common.md核心的 V8 工作区系统指令包含构建、调试、测试、提交规范与常见陷阱等大量可执行内容agents/prompts/templates/模板目录内含README.md与modular.md用于把提示词拆分成可按需引用的片段。整套体系的定位是提示词即代码把 V8 开发所需的工程知识命令、目录结构、编码规范固化进文本让 Agent 在首次进入仓库时即可获得完整上下文而不是靠模型猜V8 的构建方式。二、组装系统指令创建本地GEMINI.md2.1 用语法导入 PromptREADME 给出的核心用法非常简洁在仓库根目录创建一个**本地、不纳入版本管理untracked**的GEMINI.md文件然后用语法引入相关提示词。例如agents/prompts/common.md这是 gemini-cli 的标准 workspace 机制GEMINI.md相当于该仓库的系统指令入口路径负责把对应文件的全部内容展开进上下文。值得注意的是README 强调GEMINI.md是本地、untracked的文件——即它属于开发者个人配置不应提交进仓库这与仓库是只读镜像、个人配置各自维护的定位一致。2.2 用/memory show验证导入由于 gemini-cli 的导入是文件展开机制很难肉眼判断某个引用是否真的被加载。README 给出了一条可验证的命令在 gemini-cli 中运行/memory show如果common.md的内容例如其中的构建命令、目录说明出现在 memory 输出中就说明导入成功。这是一个非常实用的排障手段当 Agent 表现不知道 V8 怎么构建时先检查 memory 里有没有对应的 Prompt 内容而不是盲目重写指令。2.3 多文件组合结合 agents/prompts/templates/README.md 可以看到GEMINI.md可以同时引入多个文件且模板既可叠加在基础 Prompt 之上也可单独使用agents/prompts/common.md agents/prompts/templates/example.mdagents/prompts/templates/example.md第一段写法表示基础指令 模板增强第二段则表示某个模板可独立支撑一个场景。这种设计把常驻的系统指令与按需加载的专项知识解耦避免把所有内容塞进一个巨型文件导致上下文浪费。三、common.mdV8 工作区系统指令的核心内容agents/prompts/common.md 是agents/prompts/common.md实际加载的内容也是这套提示词体系的信息密度最高处。它被设计为给 Agent 的 V8 速查手册下面按原文档脉络逐节展开。3.1 关键命令速览common.md 开头就给出了 Agent 最常用的五条命令对应仓库中实际存在的 tools/dev/gm.py 与 tools/run-tests.py用途命令构建Debugtools/dev/gm.py quiet x64.debug tests构建Optimized Debugtools/dev/gm.py quiet x64.optdebug tests构建Releasetools/dev/gm.py quiet x64.release tests运行全部测试tools/run-tests.py --progress dots --exit-after-n-failures5 --outdirout/x64.optdebug运行 C 测试tools/run-tests.py --progress dots --exit-after-n-failures5 --outdirout/x64.optdebug cctest unittests运行 JavaScript 测试tools/run-tests.py --progress dots --exit-after-n-failures5 --outdirout/x64.optdebug mjsunit格式化代码git cl format几个细节值得注意gm.py是 GN Ninja 的封装quiet关键字用于抑制编译进度输出、节省 token但错误仍会照常报告见原文档Make sure to pass thequietkeyword unless told to otherwiserun-tests.py的--progress dots表示用点号做最小化进度输出避免刷屏--exit-after-n-failures5表示累计 5 个失败即提前终止适合 Agent 场景下快速暴露问题测试默认指向x64.optdebug构建产物因此构建配置与测试配置必须匹配是后面常见陷阱一节强调的原则。3.2 角色设定与三条铁律common.md 在命令之后给出了 Agent 的角色提示hints你是一名 C 专家开发者V8 面向终端用户运行不可信代码任何正确性 bug 都可能演变成终端用户的安全问题因此代码必须绝对正确、无 bugV8 为 Web 提供 JavaScript 与 WebAssembly 运行时做优化时必须追求最佳性能。这三条是 V8 开发的精神内核正确性优先安全、性能至上运行时职责被写进 Prompt 意味着每次对话都会强化这一约束。在 agents/prompts/templates/modular.md 中这三条 hints 被原样保留说明它是所有 V8 相关 Prompt 的公共底座。3.3 目录结构速览src/的二十余个核心子目录common.md 用很大篇幅列出了 V8 源码目录结构这是 Agent 在代码库中定位文件的地图。核心目录及职责整理如下路径均在 src/ 下目录职责src/api/V8 公开 C API 实现声明在include/src/ast/解析后 JavaScript 的抽象语法树AST含节点、作用域、变量src/base/底层基础工具、数据结构与全项目平台抽象层src/baseline/Sparkplug 基线编译器直接从字节码生成机器码以获得快速性能提升src/bigint/BigInt 运算实现src/builtins/JavaScript 内建函数实现如Array.prototype.mapsrc/codegen/代码生成宏汇编器直接生成机器码、CodeStubAssembler 高层代码生成、safepoint 表与源码位置表等机器码元数据定义、compiler.cc编译器入口含各架构子目录且需尽量保持同步src/common/公共定义与工具src/compiler/TurboFan 优化编译器含 Turboshaft CFG 编译器src/d8/d8shell 实现用于 CLI 运行 V8src/debug/调试器与调试协议实现src/deoptimizer/反优化器把优化帧转换回未优化帧src/execution/执行环境定义Isolate、帧定义、微任务、栈保护、分层tiering、on-stack 参数处理src/handles/面向 GC 安全对象引用的 Handle 实现src/heap/垃圾回收器与内存管理src/ic/内联缓存Inline Caching实现src/init/V8 初始化代码src/inspector/inspector 协议实现src/interpreter/Ignition 字节码编译器与解释器src/json/JSON 解析器与序列化器src/libplatform/平台抽象层任务运行器与工作线程src/logging/日志实现src/maglev/Maglev 中档优化编译器src/numbers/各类数值运算实现src/objects/V8 内部对象与 JavaScript 对象的表示与行为src/parsing/解析器与扫描器实现src/profiler/进程内 profiler堆快照、分配跟踪、采样 CPU profilersrc/regexp/正则表达式实现含需保持同步的架构子目录src/runtime/运行时可由 JavaScript 调用的 C 函数src/sandbox/沙箱实现将 V8 内存操作限制在单个受保护虚拟内存分配内防止沙箱内对象损坏波及沙箱外对象src/snapshot/快照实现启动快照只读、启动堆、启动上下文与用于用户脚本代码缓存的代码序列化器src/strings/字符串辅助实现字符谓词、Unicode 处理、哈希与字符串构建src/torque/Torque 语言实现src/tracing/追踪tracing实现src/trap-handler/陷阱处理器实现src/wasm/WebAssembly 实现src/zone/简单的 bump-pointer 区域region-basedzone 分配器此外还有三个顶层目录test/绝大部分测试与测试代码include/V8 的全部公共 API供 Blink 等外部嵌入方使用out/构建产物目录通常按构建配置分子目录存放。这份地图的价值在于Agent 遇到性能问题知道去compiler/或maglev/找遇到对象表示去objects/遇到GC 崩溃去heap/从而避免盲目全局搜索。仓库内 agents/skills/v8-structure/SKILL.md 与 agents/skills/v8-understanding/SKILL.md 是对此的更深入展开可配合阅读。3.4 构建gm.py与三种构建配置common.md 指出依赖装好之后V8 用gm.pyGN 与 Ninja 的封装构建并给出三个使用示例# 列出所有可用构建配置与目标 tools/dev/gm.py # 以 release 模式为 x64 构建 d8 shell tools/dev/gm.py quiet x64.release # 以 debug 模式为 x64 构建 d8 tools/dev/gm.py quiet x64.debug三种构建配置的语义如下release面向性能优化、剥离调试信息用于基准测试benchmarkingdebug包含完整调试信息并启用断言assertions速度较慢但调试必备optdebug优化与调试信息兼得的折中方案适合日常开发。sync参数用于构建前同步依赖--sync构建前执行gclient sync -D--syncforce构建前执行gclient sync -D --force --reset强制重置。原文档特别强调除非被告知否则始终传quiet关键字以免编译进度浪费 token错误信息仍会正常输出。3.5 调试d8 GDB 与诊断 Flags调试推荐使用debug或optdebug构建用 GDB 或 LLDB 做原生代码调试# 用 gdb 运行 d8 的示例 gdb --args out/x64.debug/d8 --my-flag my-script.jsV8 提供丰富的诊断 flagscommon.md 列出的最常用四个Flag作用--trace-opt记录被优化的函数--trace-deopt记录函数何时、为何被反优化--trace-gc记录垃圾回收事件--allow-natives-syntax允许在 JavaScript 中调用 V8 内部函数如%OptimizeFunctionOnNextCall(f)用于测试全部 flags 可通过out/x64.debug/d8 --help查看。从源码佐证绝大多数 V8 flags 定义在 src/flags/flag-definitions.h该文件是DEFINE_*宏与DEFINE_IMPLICATION推导规则的中枢例如lite_mode会隐式推导出jitless与optimize_for_size而d8shell 专属 flags 位于 src/d8/d8.cc 的Shell::SetOptions函数中——这与原文档描述完全一致。此外原文档给出一个非常实用的 Torque 调试技巧排查 Torque 代码问题时查看out/build-config/gen/torque-generated/下生成的 C 文件可以看到实际执行的底层 CodeStubAssembler 代码。这印证了 V8 的 Torque → CSA C 的生成式编译流程参考 docs/torque/architecture.md。3.6 测试run-tests.py与三类测试套件主要测试脚本是 tools/run-tests.py需要指定构建输出目录与要跑的测试。三个关键测试套件unittestsV8 内部组件的 C 单元测试cctest另一种较老的 C 单元测试格式已弃用正在迁移到 unittestsmjsunit针对 JavaScript 语言特性与内建函数的 JS 测试。# 对 x64.optdebug 构建运行全部标准测试 tools/run-tests.py --progress dots --exit-after-n-failures5 --outdirout/x64.optdebug # 运行指定测试套件如 cctest tools/run-tests.py --progress dots --exit-after-n-failures5 --outdirout/x64.optdebug cctest # 运行指定测试文件 tools/run-tests.py --progress dots --exit-after-n-failures5 --outdirout/x64.optdebug cctest/test-heap原文档强调必须传--progress dots以最小化进度输出。测试失败时输出会给出 stderr 与可复现命令例如 mjsunit/maglev/regress-429656023 --- stderr --- # # Fatal error in ../../src/heap/local-factory.h, line 41 # unreachable code # ...stack trace... Received signal 6 Command: out/x64.optdebug/d8 --test test/mjsunit/mjsunit.js test/mjsunit/maglev/regress-429656023.js --random-seed-190258694 --nohard-abort --verify-heap --allow-natives-syntax复现方式有两种一是继续用run-tests.py按测试名重跑tools/run-tests.py --progress dots --outdirout/x64.optdebug mjsunit/maglev/regress-429656023二是直接运行输出中给出的命令直接运行时可以附加额外 flags 辅助调试也可以换一个构建类型例如 release 失败时换 debug 构建跑。该例还展示了--random-seed、--nohard-abort、--verify-heap等典型组合是 Agent 复现崩溃类问题的标准模板。3.7 编码与提交规范[component]: Short description of the change Longer description explaining the why of the change, not just the what. Wrap lines at 72 characters. Bug: 123456提交规范要点风格始终遵循周边代码的风格约定除此之外遵循 Chromium 的 C 风格指南格式化提交前用git cl format自动格式化commit message 格式首行[组件]: 简短描述如compiler、runtime、api空行后写为什么的长描述解释 why 而非 what72 字符换行最后Bug:行关联问题跟踪器对追溯至关重要。3.8 常见陷阱与最佳实践清单common.md 用一整节总结了 Agent 在 V8 里写代码时必须遵守的纪律这是避免AI 改坏 V8的关键提交前务必格式化创建 commit 前运行git cl format不要编辑生成文件out/下文件由构建过程生成改动应落在源文件Torque 改.tq、协议定义改.pdl测试配置与构建匹配例如构建了x64.debug就从out/x64.debug跑 mjsunit先研究周边代码约定添加新代码前先研究所在文件/目录的既有模式、命名约定与架构选择不要改动无关代码保持 diff 最小只改目标代码想清理附近代码应另开 patchsuggest it to me for a separate patch相关函数放一起新增函数尽量插在相近函数附近不要猜头文件名不知道类或函数定义在哪就搜索而非猜测头文件名注意前置声明很多类型只做了 forward declaration要用就得找到定义注意内联函数定义许多函数在.h中声明为inline、实现在-inl.h文件中出现缺少定义的编译错误通常是漏#include了-inl.h且-inl.h只能被其他-inl.h和.cc文件包含。四、模板机制templates/目录的定位agents/prompts/templates/README.md 定义了模板的使用方式见 2.3 节而 agents/prompts/templates/modular.md 则是一个完整的模块化 V8 工作区模板范例展示了比裸common.md更进阶的组织形态保留common.md的三条 hintsC 专家、正确性/安全、性能新增Subagents Setupgemini-cli 环境运行vpython3 agents/scripts/install_for_gemini_cli.py在.gemini/agents/生成子代理文件Jetski 环境运行vpython3 agents/scripts/install_for_jetski.py在.agents/agents/创建符号链接将详细知识下沉到专业化子代理Researcher/Builder/Tester/Debugger见agents/agents/下对应目录按需调用以Skills Rules链接形式引用专项知识如 v8-commands、v8-testing、v8-setup、git-cl、torque、v8-best-practices 等强调强制编排Mandatory Orchestration任何 V8 任务主 Agent 必须充当 Orchestrator调用agents/agents/中定义的专用子代理并遵守 framework 与 execution-constraints 两条规则以保证效率、并行性与一致性。也就是说common.md是单文件、全量注入的轻量方案templates/modular.md是模块化、按需编排的进阶方案两者由同一个GEMINI.md机制驱动可按需求选择。五、子代理与安装脚本提示词体系的延伸虽然 README 本身简短但结合仓库可以还原出完整闭环——模板中提到的安装脚本与子代理是这套 Prompt 工程的上游与下游安装脚本生成侧agents/scripts/install_for_gemini_cli.py遍历agents/agents/下每个子目录读取agent.json与config.yaml把system_prompt_sections拼装为正文把tool_names映射为 gemini-cli 工具名如view_file→read_file、run_command→run_shell_command、list_dir→list_directory、search_web→google_web_search生成带 YAML frontmatter 的.repo_root/.gemini/agents/name.md若根目录尚无GEMINI.md还会自动写入[Modular Rules](https://link.gitcode.com/i/e5c72a1dd51d2f7f53d07379a4ab5611)一行——即默认采用模块化模板作为入口agents/scripts/install_for_jetski.py面向 Jetski 环境在./agents/下创建符号链接指向agents/内的 agents、skills、rules、plugins 等同样会在缺少GEMINI.md时写入 modular.md 引用。子代理定义内容侧以 agents/agents/builder/ 为例agent.json声明名称与描述Specializes in building V8.config.yaml的system_prompt_sections给出指令You are a build assistant. Your goal is to compile V8 for specified configurations. You can read files and search code to understand build errors.tool_names授权run_command、view_file、grep_search、list_dir、mcp_*等工具。同理还有 researcher、tester、debugger 三个子代理分别负责代码探索、测试运行与 GDB 崩溃调查。配套规则agents/rules/framework.md强制编排、环境感知jetski vs gemini-cli、工作流专项化调试/性能等、允许后台 Clippy 在 side worktree 自主工作但不得改动用户活动 worktreeagents/rules/execution-constraints.md禁止工具死循环、精准读取文件、不用浏览器、强制编排、避免交互式分页器用--no-pager或PAGERcat、上传 CL 前用git diff --name-only origin/main..HEAD校验 diff 等 11 条执行纪律。由此可以推断agents/prompts/是这套V8 智能体开发环境的入口与说明书——GEMINI.md引用它它引用common.md/模板模板又指向子代理与规则形成从系统指令到执行单元的完整链路。六、已知问题与贡献指南6.1 已知问题Import 作用域限制README 明确记录了一个已知问题对应 gemini-cli 的 issue #4098所有导入必须限定在当前 Prompt 文件所在的作用域内。具体规则是a/prompt.md可以导入a/prompt2.md或a/b/prompt3.md但不能导入c/prompt4.md跨目录导入不被支持。这对组织 Prompt 有直接影响如果你想把agents/prompts/templates/里的模板从其他位置的GEMINI.md引用必须注意路径层级关系必要时把共享片段放到能被合法引用到的目录。6.2 贡献指南修改common.md必须格外谨慎它被广泛使用broadly used任何改动都会影响所有以此为基座的 Agent 工作区新增想分享的 Prompt 应放入templates/目录即新增内容走模板化路线而不是直接改动公共底座。这套约定保证了公共基础稳定、专项能力增量扩展与 2.3 节基础指令 按需模板的设计哲学一脉相承。七、结语agents/prompts/README.md篇幅不长但它描述的是一套完整、可落地的 V8 × gemini-cli 提示词工程方案用GEMINI.md语法组装系统指令用/memory show验证加载以common.md提供构建/调试/测试/提交的权威速查以templates/modular.md组织模块化工作区与子代理编排。对于希望把 AI 助手变成合格 V8 开发者的团队或个人这套结构本身就是最佳实践范本——先固化知识再交给 Agent 执行。【免费下载链接】v8The official mirror of the V8 Git repository项目地址: https://gitcode.com/gh_mirrors/v81/v8创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 V8 仓库 Gemini CLI 提示词体系实战：GEMINI.md 组装、Prompt 模板与子代理编排
V8 仓库 Gemini CLI 提示词体系实战GEMINI.md 组装、Prompt 模板与子代理编排【免费下载链接】v8The official mirror of the V8 Git repository项目地址: https://gitcode.com/gh_mirrors/v81/v8本文面向希望用 AI 编码助手gemini-cli开发 V8 的工程师讲解agents/prompts/目录的提示词工程方案如何用语法把common.md与模板拼装成本地GEMINI.md系统指令如何用/memory show验证导入结果并结合仓库中的构建、调试、测试命令与子代理subagent配置形成一套可复用的 V8 开发智能体工作台。读完本文你将能独立搭建并维护自己的 V8 Prompt 工作区。一、目录定位agents/prompts/是什么在 V8 仓库的 agents/prompts/README.md 中明确说明该目录存放面向 V8 的通用 Promptcommon prompt以及用于教会 Agent 特定工具的模板 Prompttemplate prompts一切设计意图都是配合 gemini-cli 使用。从仓库实际内容看agents/prompts/下共三个文件/子目录agents/prompts/README.md使用说明即本文主体agents/prompts/common.md核心的 V8 工作区系统指令包含构建、调试、测试、提交规范与常见陷阱等大量可执行内容agents/prompts/templates/模板目录内含README.md与modular.md用于把提示词拆分成可按需引用的片段。整套体系的定位是提示词即代码把 V8 开发所需的工程知识命令、目录结构、编码规范固化进文本让 Agent 在首次进入仓库时即可获得完整上下文而不是靠模型猜V8 的构建方式。二、组装系统指令创建本地GEMINI.md2.1 用语法导入 PromptREADME 给出的核心用法非常简洁在仓库根目录创建一个**本地、不纳入版本管理untracked**的GEMINI.md文件然后用语法引入相关提示词。例如agents/prompts/common.md这是 gemini-cli 的标准 workspace 机制GEMINI.md相当于该仓库的系统指令入口路径负责把对应文件的全部内容展开进上下文。值得注意的是README 强调GEMINI.md是本地、untracked的文件——即它属于开发者个人配置不应提交进仓库这与仓库是只读镜像、个人配置各自维护的定位一致。2.2 用/memory show验证导入由于 gemini-cli 的导入是文件展开机制很难肉眼判断某个引用是否真的被加载。README 给出了一条可验证的命令在 gemini-cli 中运行/memory show如果common.md的内容例如其中的构建命令、目录说明出现在 memory 输出中就说明导入成功。这是一个非常实用的排障手段当 Agent 表现不知道 V8 怎么构建时先检查 memory 里有没有对应的 Prompt 内容而不是盲目重写指令。2.3 多文件组合结合 agents/prompts/templates/README.md 可以看到GEMINI.md可以同时引入多个文件且模板既可叠加在基础 Prompt 之上也可单独使用agents/prompts/common.md agents/prompts/templates/example.mdagents/prompts/templates/example.md第一段写法表示基础指令 模板增强第二段则表示某个模板可独立支撑一个场景。这种设计把常驻的系统指令与按需加载的专项知识解耦避免把所有内容塞进一个巨型文件导致上下文浪费。三、common.mdV8 工作区系统指令的核心内容agents/prompts/common.md 是agents/prompts/common.md实际加载的内容也是这套提示词体系的信息密度最高处。它被设计为给 Agent 的 V8 速查手册下面按原文档脉络逐节展开。3.1 关键命令速览common.md 开头就给出了 Agent 最常用的五条命令对应仓库中实际存在的 tools/dev/gm.py 与 tools/run-tests.py用途命令构建Debugtools/dev/gm.py quiet x64.debug tests构建Optimized Debugtools/dev/gm.py quiet x64.optdebug tests构建Releasetools/dev/gm.py quiet x64.release tests运行全部测试tools/run-tests.py --progress dots --exit-after-n-failures5 --outdirout/x64.optdebug运行 C 测试tools/run-tests.py --progress dots --exit-after-n-failures5 --outdirout/x64.optdebug cctest unittests运行 JavaScript 测试tools/run-tests.py --progress dots --exit-after-n-failures5 --outdirout/x64.optdebug mjsunit格式化代码git cl format几个细节值得注意gm.py是 GN Ninja 的封装quiet关键字用于抑制编译进度输出、节省 token但错误仍会照常报告见原文档Make sure to pass thequietkeyword unless told to otherwiserun-tests.py的--progress dots表示用点号做最小化进度输出避免刷屏--exit-after-n-failures5表示累计 5 个失败即提前终止适合 Agent 场景下快速暴露问题测试默认指向x64.optdebug构建产物因此构建配置与测试配置必须匹配是后面常见陷阱一节强调的原则。3.2 角色设定与三条铁律common.md 在命令之后给出了 Agent 的角色提示hints你是一名 C 专家开发者V8 面向终端用户运行不可信代码任何正确性 bug 都可能演变成终端用户的安全问题因此代码必须绝对正确、无 bugV8 为 Web 提供 JavaScript 与 WebAssembly 运行时做优化时必须追求最佳性能。这三条是 V8 开发的精神内核正确性优先安全、性能至上运行时职责被写进 Prompt 意味着每次对话都会强化这一约束。在 agents/prompts/templates/modular.md 中这三条 hints 被原样保留说明它是所有 V8 相关 Prompt 的公共底座。3.3 目录结构速览src/的二十余个核心子目录common.md 用很大篇幅列出了 V8 源码目录结构这是 Agent 在代码库中定位文件的地图。核心目录及职责整理如下路径均在 src/ 下目录职责src/api/V8 公开 C API 实现声明在include/src/ast/解析后 JavaScript 的抽象语法树AST含节点、作用域、变量src/base/底层基础工具、数据结构与全项目平台抽象层src/baseline/Sparkplug 基线编译器直接从字节码生成机器码以获得快速性能提升src/bigint/BigInt 运算实现src/builtins/JavaScript 内建函数实现如Array.prototype.mapsrc/codegen/代码生成宏汇编器直接生成机器码、CodeStubAssembler 高层代码生成、safepoint 表与源码位置表等机器码元数据定义、compiler.cc编译器入口含各架构子目录且需尽量保持同步src/common/公共定义与工具src/compiler/TurboFan 优化编译器含 Turboshaft CFG 编译器src/d8/d8shell 实现用于 CLI 运行 V8src/debug/调试器与调试协议实现src/deoptimizer/反优化器把优化帧转换回未优化帧src/execution/执行环境定义Isolate、帧定义、微任务、栈保护、分层tiering、on-stack 参数处理src/handles/面向 GC 安全对象引用的 Handle 实现src/heap/垃圾回收器与内存管理src/ic/内联缓存Inline Caching实现src/init/V8 初始化代码src/inspector/inspector 协议实现src/interpreter/Ignition 字节码编译器与解释器src/json/JSON 解析器与序列化器src/libplatform/平台抽象层任务运行器与工作线程src/logging/日志实现src/maglev/Maglev 中档优化编译器src/numbers/各类数值运算实现src/objects/V8 内部对象与 JavaScript 对象的表示与行为src/parsing/解析器与扫描器实现src/profiler/进程内 profiler堆快照、分配跟踪、采样 CPU profilersrc/regexp/正则表达式实现含需保持同步的架构子目录src/runtime/运行时可由 JavaScript 调用的 C 函数src/sandbox/沙箱实现将 V8 内存操作限制在单个受保护虚拟内存分配内防止沙箱内对象损坏波及沙箱外对象src/snapshot/快照实现启动快照只读、启动堆、启动上下文与用于用户脚本代码缓存的代码序列化器src/strings/字符串辅助实现字符谓词、Unicode 处理、哈希与字符串构建src/torque/Torque 语言实现src/tracing/追踪tracing实现src/trap-handler/陷阱处理器实现src/wasm/WebAssembly 实现src/zone/简单的 bump-pointer 区域region-basedzone 分配器此外还有三个顶层目录test/绝大部分测试与测试代码include/V8 的全部公共 API供 Blink 等外部嵌入方使用out/构建产物目录通常按构建配置分子目录存放。这份地图的价值在于Agent 遇到性能问题知道去compiler/或maglev/找遇到对象表示去objects/遇到GC 崩溃去heap/从而避免盲目全局搜索。仓库内 agents/skills/v8-structure/SKILL.md 与 agents/skills/v8-understanding/SKILL.md 是对此的更深入展开可配合阅读。3.4 构建gm.py与三种构建配置common.md 指出依赖装好之后V8 用gm.pyGN 与 Ninja 的封装构建并给出三个使用示例# 列出所有可用构建配置与目标 tools/dev/gm.py # 以 release 模式为 x64 构建 d8 shell tools/dev/gm.py quiet x64.release # 以 debug 模式为 x64 构建 d8 tools/dev/gm.py quiet x64.debug三种构建配置的语义如下release面向性能优化、剥离调试信息用于基准测试benchmarkingdebug包含完整调试信息并启用断言assertions速度较慢但调试必备optdebug优化与调试信息兼得的折中方案适合日常开发。sync参数用于构建前同步依赖--sync构建前执行gclient sync -D--syncforce构建前执行gclient sync -D --force --reset强制重置。原文档特别强调除非被告知否则始终传quiet关键字以免编译进度浪费 token错误信息仍会正常输出。3.5 调试d8 GDB 与诊断 Flags调试推荐使用debug或optdebug构建用 GDB 或 LLDB 做原生代码调试# 用 gdb 运行 d8 的示例 gdb --args out/x64.debug/d8 --my-flag my-script.jsV8 提供丰富的诊断 flagscommon.md 列出的最常用四个Flag作用--trace-opt记录被优化的函数--trace-deopt记录函数何时、为何被反优化--trace-gc记录垃圾回收事件--allow-natives-syntax允许在 JavaScript 中调用 V8 内部函数如%OptimizeFunctionOnNextCall(f)用于测试全部 flags 可通过out/x64.debug/d8 --help查看。从源码佐证绝大多数 V8 flags 定义在 src/flags/flag-definitions.h该文件是DEFINE_*宏与DEFINE_IMPLICATION推导规则的中枢例如lite_mode会隐式推导出jitless与optimize_for_size而d8shell 专属 flags 位于 src/d8/d8.cc 的Shell::SetOptions函数中——这与原文档描述完全一致。此外原文档给出一个非常实用的 Torque 调试技巧排查 Torque 代码问题时查看out/build-config/gen/torque-generated/下生成的 C 文件可以看到实际执行的底层 CodeStubAssembler 代码。这印证了 V8 的 Torque → CSA C 的生成式编译流程参考 docs/torque/architecture.md。3.6 测试run-tests.py与三类测试套件主要测试脚本是 tools/run-tests.py需要指定构建输出目录与要跑的测试。三个关键测试套件unittestsV8 内部组件的 C 单元测试cctest另一种较老的 C 单元测试格式已弃用正在迁移到 unittestsmjsunit针对 JavaScript 语言特性与内建函数的 JS 测试。# 对 x64.optdebug 构建运行全部标准测试 tools/run-tests.py --progress dots --exit-after-n-failures5 --outdirout/x64.optdebug # 运行指定测试套件如 cctest tools/run-tests.py --progress dots --exit-after-n-failures5 --outdirout/x64.optdebug cctest # 运行指定测试文件 tools/run-tests.py --progress dots --exit-after-n-failures5 --outdirout/x64.optdebug cctest/test-heap原文档强调必须传--progress dots以最小化进度输出。测试失败时输出会给出 stderr 与可复现命令例如 mjsunit/maglev/regress-429656023 --- stderr --- # # Fatal error in ../../src/heap/local-factory.h, line 41 # unreachable code # ...stack trace... Received signal 6 Command: out/x64.optdebug/d8 --test test/mjsunit/mjsunit.js test/mjsunit/maglev/regress-429656023.js --random-seed-190258694 --nohard-abort --verify-heap --allow-natives-syntax复现方式有两种一是继续用run-tests.py按测试名重跑tools/run-tests.py --progress dots --outdirout/x64.optdebug mjsunit/maglev/regress-429656023二是直接运行输出中给出的命令直接运行时可以附加额外 flags 辅助调试也可以换一个构建类型例如 release 失败时换 debug 构建跑。该例还展示了--random-seed、--nohard-abort、--verify-heap等典型组合是 Agent 复现崩溃类问题的标准模板。3.7 编码与提交规范[component]: Short description of the change Longer description explaining the why of the change, not just the what. Wrap lines at 72 characters. Bug: 123456提交规范要点风格始终遵循周边代码的风格约定除此之外遵循 Chromium 的 C 风格指南格式化提交前用git cl format自动格式化commit message 格式首行[组件]: 简短描述如compiler、runtime、api空行后写为什么的长描述解释 why 而非 what72 字符换行最后Bug:行关联问题跟踪器对追溯至关重要。3.8 常见陷阱与最佳实践清单common.md 用一整节总结了 Agent 在 V8 里写代码时必须遵守的纪律这是避免AI 改坏 V8的关键提交前务必格式化创建 commit 前运行git cl format不要编辑生成文件out/下文件由构建过程生成改动应落在源文件Torque 改.tq、协议定义改.pdl测试配置与构建匹配例如构建了x64.debug就从out/x64.debug跑 mjsunit先研究周边代码约定添加新代码前先研究所在文件/目录的既有模式、命名约定与架构选择不要改动无关代码保持 diff 最小只改目标代码想清理附近代码应另开 patchsuggest it to me for a separate patch相关函数放一起新增函数尽量插在相近函数附近不要猜头文件名不知道类或函数定义在哪就搜索而非猜测头文件名注意前置声明很多类型只做了 forward declaration要用就得找到定义注意内联函数定义许多函数在.h中声明为inline、实现在-inl.h文件中出现缺少定义的编译错误通常是漏#include了-inl.h且-inl.h只能被其他-inl.h和.cc文件包含。四、模板机制templates/目录的定位agents/prompts/templates/README.md 定义了模板的使用方式见 2.3 节而 agents/prompts/templates/modular.md 则是一个完整的模块化 V8 工作区模板范例展示了比裸common.md更进阶的组织形态保留common.md的三条 hintsC 专家、正确性/安全、性能新增Subagents Setupgemini-cli 环境运行vpython3 agents/scripts/install_for_gemini_cli.py在.gemini/agents/生成子代理文件Jetski 环境运行vpython3 agents/scripts/install_for_jetski.py在.agents/agents/创建符号链接将详细知识下沉到专业化子代理Researcher/Builder/Tester/Debugger见agents/agents/下对应目录按需调用以Skills Rules链接形式引用专项知识如 v8-commands、v8-testing、v8-setup、git-cl、torque、v8-best-practices 等强调强制编排Mandatory Orchestration任何 V8 任务主 Agent 必须充当 Orchestrator调用agents/agents/中定义的专用子代理并遵守 framework 与 execution-constraints 两条规则以保证效率、并行性与一致性。也就是说common.md是单文件、全量注入的轻量方案templates/modular.md是模块化、按需编排的进阶方案两者由同一个GEMINI.md机制驱动可按需求选择。五、子代理与安装脚本提示词体系的延伸虽然 README 本身简短但结合仓库可以还原出完整闭环——模板中提到的安装脚本与子代理是这套 Prompt 工程的上游与下游安装脚本生成侧agents/scripts/install_for_gemini_cli.py遍历agents/agents/下每个子目录读取agent.json与config.yaml把system_prompt_sections拼装为正文把tool_names映射为 gemini-cli 工具名如view_file→read_file、run_command→run_shell_command、list_dir→list_directory、search_web→google_web_search生成带 YAML frontmatter 的.repo_root/.gemini/agents/name.md若根目录尚无GEMINI.md还会自动写入[Modular Rules](https://link.gitcode.com/i/e5c72a1dd51d2f7f53d07379a4ab5611)一行——即默认采用模块化模板作为入口agents/scripts/install_for_jetski.py面向 Jetski 环境在./agents/下创建符号链接指向agents/内的 agents、skills、rules、plugins 等同样会在缺少GEMINI.md时写入 modular.md 引用。子代理定义内容侧以 agents/agents/builder/ 为例agent.json声明名称与描述Specializes in building V8.config.yaml的system_prompt_sections给出指令You are a build assistant. Your goal is to compile V8 for specified configurations. You can read files and search code to understand build errors.tool_names授权run_command、view_file、grep_search、list_dir、mcp_*等工具。同理还有 researcher、tester、debugger 三个子代理分别负责代码探索、测试运行与 GDB 崩溃调查。配套规则agents/rules/framework.md强制编排、环境感知jetski vs gemini-cli、工作流专项化调试/性能等、允许后台 Clippy 在 side worktree 自主工作但不得改动用户活动 worktreeagents/rules/execution-constraints.md禁止工具死循环、精准读取文件、不用浏览器、强制编排、避免交互式分页器用--no-pager或PAGERcat、上传 CL 前用git diff --name-only origin/main..HEAD校验 diff 等 11 条执行纪律。由此可以推断agents/prompts/是这套V8 智能体开发环境的入口与说明书——GEMINI.md引用它它引用common.md/模板模板又指向子代理与规则形成从系统指令到执行单元的完整链路。六、已知问题与贡献指南6.1 已知问题Import 作用域限制README 明确记录了一个已知问题对应 gemini-cli 的 issue #4098所有导入必须限定在当前 Prompt 文件所在的作用域内。具体规则是a/prompt.md可以导入a/prompt2.md或a/b/prompt3.md但不能导入c/prompt4.md跨目录导入不被支持。这对组织 Prompt 有直接影响如果你想把agents/prompts/templates/里的模板从其他位置的GEMINI.md引用必须注意路径层级关系必要时把共享片段放到能被合法引用到的目录。6.2 贡献指南修改common.md必须格外谨慎它被广泛使用broadly used任何改动都会影响所有以此为基座的 Agent 工作区新增想分享的 Prompt 应放入templates/目录即新增内容走模板化路线而不是直接改动公共底座。这套约定保证了公共基础稳定、专项能力增量扩展与 2.3 节基础指令 按需模板的设计哲学一脉相承。七、结语agents/prompts/README.md篇幅不长但它描述的是一套完整、可落地的 V8 × gemini-cli 提示词工程方案用GEMINI.md语法组装系统指令用/memory show验证加载以common.md提供构建/调试/测试/提交的权威速查以templates/modular.md组织模块化工作区与子代理编排。对于希望把 AI 助手变成合格 V8 开发者的团队或个人这套结构本身就是最佳实践范本——先固化知识再交给 Agent 执行。【免费下载链接】v8The official mirror of the V8 Git repository项目地址: https://gitcode.com/gh_mirrors/v81/v8创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考