artifact-pyramids

Agentic AI 研究的工件金字塔

渐进式披露决定了我们如何为 Agent 提供上下文：启动时提供元数据，激活时提供说明，按需提供资源。工件金字塔将同一原则应用于 Agent 的产出。 它包含三个深度递增的层级，每层都可独立使用，并且都链接到下一层。

加载指南

生成工件金字塔时，请将以下参考资料作为必需集合加载（不得拆开加载）：

参考资料	文件
流水线阶段——层级定义、导航格式、生成流程	references/pipeline-stages.md
输出分类框架——与角色无关的内容约定、00-index/L1 边界	references/output-classification-framework.md
质量门——各层的验证检查清单	references/quality-gates.md
委派上下文模板——子 Agent 输出要求的确切文本	references/delegation-context-template.md

这四份资料定义了规范中相互补充的方面，其他资料都以此为前提。只加载其中一部分可能会违反内容约定（例如，将发现内容放入 00-index），或遗漏必需的导航功能。编写任何金字塔文件前，请加载完整集合。

下表中的参考资料说明了何时加载各文件；上述四份资料在生成金字塔时始终必需。其余参考资料（框架、示例、规范文章、思想脉络、出处信息、综合分析）均为补充资料——仅在任务需要概念深度或示例模式时加载。

金字塔

      ┌──────────────┐
      │  L1 SUMMARY  │  One file: research question, key findings,
      │    🎯        │  most important implications. Links to L2 files.
      └──────┬───────┘
      ┌──────┴───────┐
      │  L2 ANALYSIS │  Per-dimension files: market, competitive,
      │  COLLECTION  │  technical feasibility, risk. Self-contained,
      │   🧩        │  each links to L3 dossiers.
      └──────┬───────┘
      ┌──────┴───────┐
      │  L3 DOSSIERS │  Source excerpts, raw data tables, interview
      │    📦        │  transcripts, methodology notes. Reference
      └──────────────┘  library, pulled on demand.

金字塔按自顶向下的顺序使用，但通过递归式差距分析来生成：从摘要开始，嵌入指向分析文件的链接，编写链接到档案的分析文件，并在每轮结束后评估是否仍存在差距。

层级编号采用自顶向下的顺序——L1 是提炼程度最高的一层（入口点），L3 是最详细的一层（按需获取）。这与 Agent Skills 的输入模型相对应：元数据（L1）→ 说明（L2）→ 资源（L3）。

导航机制

每一层的每个文件底部都包含明确的 SOURCES 部分，其中列出绝对路径引用及其说明：

SOURCES (LAYER 2 NAVIGATION)
research/analysis/market-position.md
 -> Competitor mapping and market share analysis supporting Section 2
research/analysis/technical-feasibility.md
 -> Architecture evaluation supporting Section 3
research/dossiers/competitor-profiles.md
 -> Raw competitor data dossiers

这些不是脚注，而是供 Agent 使用者使用的导航功能。每条说明都回答了使用文件的 Agent 在加载前会提出的问题：如果深入查看，我会找到什么？

参考文件

参考资料	何时加载	文件
框架与对称性	需要完整的概念基础——不对称问题、多 Agent 路由、DIKW 关系	references/artifact-pyramid-framework.md
流水线阶段	正在构建或审查金字塔——各层的详细定义、导航格式、生产流程	references/pipeline-stages.md
质量门槛	需要验证某个产物是否符合其所在层的标准	references/quality-gates.md
完整示例	想查看涵盖全部三层的完整模拟演示	references/synthetic-example.md
思想脉络	软件架构文档（4+1 Views、C4、arc42、ADR）如何以不同名称独立发现渐进式披露——以及 Artifact Pyramid 如何在此基础上加以推广	references/intellectual-lineage.md
方法论到金字塔的映射	专业角色如何将领域特定方法论映射到通用金字塔结构，并遵循维度边界规则	references/methodology-to-pyramid-mapping.md
输出分类框架	与角色无关——任何专业人员都能用三个问题将输出映射到正确的层：谁会使用、使用频率如何、输出回答什么问题。包含各层的内容约定，以消除 00-index 与 L1 文件之间的重复。	references/output-classification-framework.md
复合金字塔综合	如何将多个子 Agent 金字塔合并为根级复合金字塔——编排流程、SOURCES 约定，以及 jobs-finder 流水线的完整示例	references/composite-pyramid-synthesis.md
委派上下文模板	正在将研究委派给子 Agent，需要在上下文字符串中准确加入文本，以确保输出符合 artifact-pyramid 格式	references/delegation-context-template.md
从扁平结构迁移到金字塔	正在将现有扁平 JSON 输出转换为 artifact-pyramid 格式——L1/L2/L3 结构、00-index 规则以及下游使用方的回退读取方式	references/flat-to-pyramid-migration.md
嵌套金字塔模式	正在设计一个随时间产出多个产物流的单一系统（多阶段、多周期）——将各周期嵌套在单个根金字塔下，避免内容分散	references/nested-pyramid-pattern.md

脚本

脚本	何时加载	文件
pyramid-status	想要审查现有研究目录的结构覆盖情况	scripts/pyramid-status.sh
extract-atoms	有原始源文本，需要提取候选原子主张	scripts/extract-atoms.py

模板

模板	何时加载	文件
项目脚手架	正在启动新的研究项目，需要索引骨架	assets/pyramid-template.md
产物清单	需要跟踪项目各层已有的内容	assets/artifact-inventory.md

快速入门

# Scaffold a new research project with all three layer directories
mkdir -p my-project/{01-summary,02-analysis,03-dossiers}
cp assets/pyramid-template.md ./my-project/00-index.md

# Check structural coverage of an existing project
scripts/pyramid-status.sh ./my-project

# Extract candidate atoms from source text
scripts/extract-atoms.py ./my-project/03-dossiers/source-1.txt

项目结构

my-project/
├── 00-index.md              # Project scaffold (from template)
├── 01-summary/              # L1: one file — key findings, implications, links to L2
├── 02-analysis/             # L2: per-dimension files (market, competitive, technical)
├── 03-dossiers/             # L3: source excerpts, transcripts, raw data, methodology
└── artifact-inventory.md    # Cross-layer tracking (from template)

编号前缀与金字塔从上到下的方向一致：01 是最常被使用的，03 则按需获取。

核心原则

1. 渐进式披露具有对称性。 同一套三级模型既适用于 Agent 消费的内容（元数据 → 指令 → 资源），也适用于它们产出的内容（摘要 → 分析 → 档案）。
2. 每一层都可独立使用。 产品经理 Agent 只读取 L1 摘要。数据科学家 Agent 读取单个 L2 分析文件。验证者读取 L3 档案。
3. 导航信息明确。 每个文件都包含一个 SOURCES 部分，其中列出绝对路径和说明——这不是脚注，而是供 Agent 使用的导航信息，用于回答“深入一层能找到什么？”
4. 深度随任务复杂度而变化。 简单的简报可能只需生成 L1 和 2 个分析文件。竞争格局分析可能需要三个层级各包含多个文件。
5. 质量门槛具有方向性。 只有达到目标层级的质量门槛后，材料才会从 L3（来源）向 L1（摘要）流转。
6. 03-dossiers/ 是扁平目录——不得包含子目录。 档案层是一个扁平的参考资料库。请使用带时期前缀或类别前缀的文件名（epoch-1-validation-edit-3.json）来组织文件，而不要使用嵌套目录。在 03-dossiers/ 中创建子目录会违反扁平文件约定，并破坏 SOURCES 导航路径。
7. 修改根目录级文件；低层级文件固定不变。 在多时期或多阶段系统中，随着新数据到来，00-index.md、01-summary/findings.md 和 02-analysis/ 中的轨迹文件会不断扩充。需要重写这些文件以反映当前状态。03-dossiers/ 中的文件以及 02-analysis/ 下按类别划分的分析文件只创建一次，之后不得修改——它们代表一个固定的时间点。

验证脚本的注意事项

scripts/pyramid-status.sh 目前通过匹配文件名来发现各层，而不是匹配规范目录名。因此，像 01-summary/findings.md、02-analysis/topic.md 和 03-dossiers/source.md 这样的合规目录树，如果嵌套文件名本身不符合脚本的层级模式，就可能被误报为缺少 L1/L2。即使各层约定并未要求 YAML frontmatter，该脚本也会将其缺失报告为质量问题。请仅将此脚本视为启发式工具；应独立验证规范目录、一个 L1 文件、每个维度对应的 L2 文件、扁平的 L3 文件、最终的 ## SOURCES 部分以及链接解析情况。

不适用场景

• 没有需要保留的研究成果的单轮问答
• 只产生临时输出的任务（一次性计算、快速查询）
• 源材料本身就是最终输出的工作流（无需综合整理）

可移植性

此技能有意保持与宿主环境无关。请使用 Agent 的常规机制来加载此处列出的参考资料、模板和脚本。不要假定存在特定的配置文件系统、任务编排器、记忆服务或响应移交格式。