企业官网建设流程全解析

• 网络安全
• 渗透测试
• 人工智能
• 大模型
• AI Agent
• 自主智能体

本篇技术指南剖析 PentestGPT 仓库中.agents/skills/grill-with-docs/SKILL.md这一组合型 Agent 技能：它本身是极简的路由入口，真正的工作由grilling与domain-modeling两个技能接力完成——先对方案进行逐分支、一次一题的"拷问式"访谈，再在共识达成的同时把领域术语写入CONTEXT.md、把关键架构决策记入docs/adr/。读完你将掌握这套"先想清楚再动手"的设计评审流程、领域建模与 ADR 的书写规范，以及它如何与 PentestGPT 的 Agentskills 安装与校验机制协同工作。

一、技能定位：一个"路由器"式的组合技能

在.agents/skills/目录下，grill-with-docs的完整定义只有 7 行（见 .agents/skills/grill-with-docs/SKILL.md）：

--- name: grill-with-docs description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go. disable-model-invocation: true --- Run a `/grilling` session, using the `/domain-modeling` skill.

从结构看，它刻意保持了"薄路由、厚实现"的形态：

• frontmatter 的name与目录名一致：grill-with-docs。这是 Agentskills 规范的硬性要求——unified_agent/skills.py 中load_skill()会校验name必须与所在目录名完全相同，否则抛出SkillError。
• disable-model-invocation: true表示"仅由用户手动调用"：与 writing-great-skills 中"model-invoked / user-invoked"的分类对应。禁用模型自主调用后，该技能的 description 不再常驻上下文窗口，换来零 context load，代价是调用它的认知负担落在使用者身上。
• 正文只有一句指令：Run a /grilling session, using the /domain-modeling skill.它不直接实现任何追问逻辑，而是声明"先跑grilling访谈，同时带上domain-modeling来维护领域模型"。

这种一个技能命名并串联其他技能的做法，正是 writing-great-skills 中所说的router skill：当用户手动触发的技能多到记不住时，用一个入口把它们组织起来。grill-with-docs与同类入口 grill-me（仅指令Run a /grilling session.）一对比，差异就非常明显：grill-me只做访谈，grill-with-docs在访谈之上叠加了文档产出义务。

二、执行路径拆解：grilling 访谈 + domain-modeling 沉淀

grill-with-docs的正文把执行权委托给两个技能，形成一条两阶段的流水线：

1. /grilling阶段——拷问式访谈：对计划或设计逐方面追问，直到双方达成共识。
2. /domain-modeling阶段——领域建模与文档化：在访谈过程中，同步挑战术语、设计边界场景，并当场把术语写进CONTEXT.md、把架构决策写进docs/adr/。

这条流水线的核心价值在于"边评审、边留档"：方案在被拷问的过程中，共识每前进一步，领域语言和架构决策就固化一步，评审结束即文档就绪，不存在事后补文档的返工。

2.1 grilling：逐分支、一次一题地拷问方案

grilling 的指令定义了访谈的三个纪律：

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.

• 一次只问一个问题："Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering."（一次性抛多个问题会让用户困惑，必须等到反馈再继续。）
• 逐分支走完设计树：沿着设计决策的依赖关系逐个解决，而非零散提问。
• 能查代码就不问人："If a question can be answered by exploring the codebase, explore the codebase instead."——这是把"拷问"的成本尽量压到代码检索上，只有代码无法回答的问题才消耗用户注意力。
• 每个问题附推荐答案：在grill-with-docs的 description 中，"A relentless interview" 点明了强度基调，而 grilling 要求每个问题都给出推荐答案，让访谈从"开放问答"变成"有倾向性的决策讨论"，大幅压缩共识收敛的轮次。

2.2 domain-modeling：边访谈边打磨领域模型

domain-modeling 是这套组合里的"文档引擎"，它定义了主动的建模纪律：挑战术语、发明边界场景、并在术语/决策结晶的当下就写下来。它特别强调：仅仅"读一遍CONTEXT.md获取词汇"不算这个技能，这个技能适用于"正在改变模型"的场景。

文件结构约定

单上下文仓库（多数仓库）：

/ ├── CONTEXT.md ├── docs/ │ └── adr/ │ ├── 0001-event-sourced-orders.md │ └── 0002-postgres-for-write-model.md └── src/

多上下文仓库则在根目录放置CONTEXT-MAP.md，指向各上下文自己的CONTEXT.md与docs/adr/（例如src/ordering/CONTEXT.md与src/ordering/docs/adr/）。

关键原则是懒创建（create files lazily）：只有有东西可写时才建文件。没有CONTEXT.md就在第一个术语确定时创建；没有docs/adr/就在第一个 ADR 需要时创建。

访谈中的四个建模动作

• 对照词汇表挑战术语：用户用到与CONTEXT.md既有语言冲突的术语时立即指出——"你的词汇表把 'cancellation' 定义为 X，但你似乎指的是 Y——到底是哪个？"
• 锐化模糊语言：遇到含糊或被滥用的词时提出精确的规范术语——"你说 'account'，是指 Customer 还是 User？这是两个不同的东西。"
• 讨论具体场景：讨论领域关系时用特定场景做压力测试，逼出概念边界的精确定义。
• 与代码交叉验证：用户描述某个机制时检查代码是否一致，发现矛盾就指出——"你的代码是整单取消 Order，但你刚说支持部分取消——哪个是对的？"

CONTEXT.md 书写规范（见 CONTEXT-FORMAT.md）

词汇表按如下格式组织，每条术语给出定义与_Avoid_排除词：

# {Context Name} {One or two sentence description of what this context is and why it exists.} ## Language **Order**: {One or two sentence description of the term} _Avoid_: Purchase, transaction **Invoice**: A request for payment sent to a customer after delivery. _Avoid_: Bill, payment request

规则要点：

• 有主见：同一概念存在多个词时，挑一个最好的，其余列入_Avoid_；
• 定义紧凑：一两句话，定义"它是什么"，而非"它做什么"；
• 只收领域特有术语：通用编程概念（timeouts、error types 等）即使项目大量使用也不收录——收录前自问：这是本上下文特有的概念，还是通用编程概念？只有前者才属于；
• 天然成簇时分组：术语存在自然聚类就用子标题分组，单一聚类的平铺列表也可以；
• CONTEXT.md必须零实现细节：不把它当规格书、草稿纸或实现决策仓库，它只是一份词汇表。

多上下文仓库的CONTEXT-MAP.md则列出各上下文的位置与事件流关系，例如：

# Context Map ## Contexts - [Ordering](https://link.gitcode.com/i/af371d9e0b81840e80f4c6fb892ece83) — receives and tracks customer orders - [Billing](https://link.gitcode.com/i/af371d9e0b81840e80f4c6fb892ece83) — generates invoices and processes payments ## Relationships - **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking

技能会按优先级推断结构：存在CONTEXT-MAP.md就读它找上下文；只有根CONTEXT.md就是单上下文；两者都没有，就在第一个术语确定时懒创建根CONTEXT.md。

ADR 书写规范（见 ADR-FORMAT.md）

ADR 存放在docs/adr/，按序号递增命名（0001-slug.md、0002-slug.md），docs/adr/目录同样懒创建。模板极简：

# {Short title of the decision} {1-3 sentences: what's the context, what did we decide, and why.}

ADR 可以只是一个段落——价值在于记录"做了这个决定、为什么"，而非填满各节。可选节（Status 前置元数据、Considered Options、Consequences）仅在确有价值时加入。

何时提议创建 ADR？三个条件必须同时满足（缺一则跳过）：

1. 难以逆转——事后改主意的成本有意义；
2. 脱离上下文会令人惊讶——未来的读者会疑惑"他们为什么这么做？"；
3. 真实权衡的结果——存在真实备选方案，你因具体理由选了其中一个。

符合资格的决策包括：架构形态（monorepo、事件溯源）、上下文间集成模式、带来锁定效应的技术选型（数据库、消息总线、认证供应商、部署目标）、边界与范围决策（显式的"不做"和"做"同样有价值）、对显而易见路径的有意偏离、代码中不可见的约束、以及拒绝理由不显而易见的被否备选方案。

三、技能栈的运行时支撑：Agentskills 校验与安装机制

grill-with-docs能够作为可被/触发的技能运行，依赖仓库内置的 Agentskills 管理代码 unified_agent/skills.py：

• 双宿主发现目录：Claude Code 从<ws>/.claude/skills/读取，Codex 从<ws>/.agents/skills/读取。install_skills()会把同一份SKILL.md以符号链接（默认mode="symlink"）或复制（mode="copy"）方式安装进两个目录，实现"一份技能、双 Agent 可用"。本仓库当前实际生效的是.agents/skills/一侧。
• frontmatter 校验：load_skill()要求文件以---开头的 YAML frontmatter 开始，解析并校验name（仅小写字母/数字/单连字符，≤64 字符，且必须等于目录名）、description（必填，≤1024 字符）。grill-with-docs的 frontmatter 完全满足这些约束。
• 可移植性 lint：lint_skill()会标记 Claude-only 语法（如$ARGUMENTS、!动态 shell 注入、${CLAUDE_*}变量），这些在 Codex 上会被忽略——grill-with-docs的正文纯文本指令不含任何此类构造，因此双宿主下行为一致。
• 测试保障：tests/test_skills.py 覆盖了合法技能加载、目录名必须匹配、非法名拒绝（Deploy、a--b、-x、超长名、下划线等）、description 必填与 1024 上限、缺 frontmatter 拒绝、Claude-only 语法告警、symlink/copy 两种安装模式及幂等重装等路径。

仓库根目录的 skills-lock.json 记录了这批技能的来源清单：17 个技能全部来自mattpocock/skills仓库的skills/engineering/与skills/productivity/目录，并带computedHash哈希校验——grill-with-docs的锁定条目与磁盘文件一一对应，属于工程技能（engineering）分组。

四、在 PentestGPT 中的落地场景：领域词汇表与架构决策的实例

虽然grill-with-docs本身是一个通用设计评审技能，但 PentestGPT 仓库恰好提供了它产出物的完整实例，可以反推这套方法论在本项目中的实际形态：

• CONTEXT.md实例：pentestgpt_agent/CONTEXT.md 是框架的领域词汇表，标题为 "Autonomous Pentest Run"，严格按 CONTEXT-FORMAT 的## Language结构组织，收录了 Supervisor、Executor、Memory Kernel、Provider Adapter、Decision Cycle、Agent Episode、Task、Attempt、Evidence、Observation、Trace、Finding 等一串领域术语，且每条都给了精确的定义（例如 "Evidence: exact target output captured by one eligible action receipt"）。它完全符合"词汇表 + Invariants/Retrieval policy"的形态，CONTEXT.md本身不含实现细节。
• 文档化决策的痕迹：仓库中的 docs/architecture.md、PENTESTGPT_AGENT_NEW_MIGRATION_REPORT.md 等记录了对 Supervisor/Executor 框架、SQLite 记忆内核、确定性校验边界的架构决策，正是 domain-modeling 所说"难以逆转、脱离上下文会令人惊讶、存在真实权衡"的 ADR 候选主题。
• 与双 Agent 运行时的配合：AGENT.md 与 CLAUDE.md 都声明"每个 episode 是新鲜的，SQLite 与精确的 trace receipts 才是记忆"，领域语言的一致性由pentestgpt_agent/CONTEXT.md这一份词汇表维护——这正是 domain-modeling 中"单上下文仓库"的标准布局。

在实际使用中，你可以在设计大型重构（例如为pentestgpt_agent增加新任务类型或新的内存语义）前手动触发grill-with-docs，让 Agent 先对方案逐分支拷问，再同步把新术语写入pentestgpt_agent/CONTEXT.md、把架构决策写入docs/adr/。

五、使用方式与前置条件

• 调用方式：grill-with-docs是 user-invoked 技能（disable-model-invocation: true），只能通过手动输入/grill-with-docs触发，Agent 不会自主调用它。由于仓库未安装.claude/skills/侧链接，Claude Code 用户如需在本地使用，可通过 unified_agent/skills.py 的install_skills()（mode="symlink"）把它同步进.claude/skills/；Codex 用户直接使用现有的.agents/skills/即可。
• 触发时机：在"方案尚未动工、先做压力测试"时使用（对应 grilling 的触发条件），且当你希望评审过程留下可追溯的领域词汇表与架构决策时，选择grill-with-docs而非只做访谈的 grill-me。
• 配套入口：首次使用工程技能前，可参考 setup-matt-pocock-skills 完成 issue tracker、triage 标签词汇、领域文档布局的初始化，其中"Domain docs"一节确认的正是CONTEXT.md/docs/adr/的单上下文或多上下文布局。

六、小结

grill-with-docs的极简 7 行定义背后是一套完整的方法论闭环：grilling提供"逐分支、一次一题、先查代码"的拷问纪律，domain-modeling提供"术语结晶即落盘、三条件齐备才写 ADR"的文档纪律，二者叠加让"设计评审"与"文档沉淀"在同一次会话中完成，且产出物严格遵循 CONTEXT-FORMAT.md 与 ADR-FORMAT.md 两份规范。在 PentestGPT 仓库中，pentestgpt_agent/CONTEXT.md就是这套方法论的真实产物，而 unified_agent/skills.py 与 tests/test_skills.py 则保证了这类技能文件的规范性、可移植性与可安装性——理解它，等于同时掌握了"如何拷问方案"和"如何让共识变成文档"两套工程能力。

• 网络安全
• 渗透测试
• 人工智能
• 大模型
• AI Agent
• 自主智能体