artifact-analysis

工件分析

将一组本地路径（或 beagle 项目约定的知识位置）转换为有引用依据、结构化的洞见、背景、决策和原始细节提取结果。

交付物始终保存在磁盘上：一份供调用方审阅的书面扫描计划、每个切片对应的一份发现文件，以及一份带路径定位引用的综合报告。不会以内联文本返回任何内容；每项结论都必须附有来源路径和逐字摘录。

适用场景

• 用户要求读取本地文档——“分析 docs 文件夹”、“扫描项目以了解背景”、“提取 .beagle/concepts/ 中的内容”。
• 另一个 beagle 技能以编程方式调用此技能，作为依据补充工具（参见 references/companion-contract.md）。
• 调用方需要可审计的输出：提取前写好的计划、每个切片对应的发现文件，以及有引用依据的综合报告。

不适用场景

• 代码库查找（“这个函数定义在哪里”、“搜索这个符号”）。请改为搜索代码库。
• 网络研究。请使用 web-research。
• 对两种实现进行比较评估，或判定来源可信度。请使用 llm-judge。
• 重写或编辑已扫描的文档。请使用 humanize-beagle (../../../beagle-docs/skills/humanize-beagle/SKILL.md)，或直接编辑文件。
• PDF / 图片 OCR / 格式转换。首个版本仅读取纯文本和 markdown。
• 需要付费或身份验证的远程来源。这是一个基于本地文件系统的基础工具。
• 引导、质疑或重塑调用方的问题。这属于调用方的职责。

工作流

按顺序分为四个步骤。每个步骤都不可跳过。

硬性门槛

仅当通过条件成立时才进入下一步——请根据 output_dir 下的文件（以及工具输出）进行确认，而不要依赖记忆。

之后	通过条件
写入 plan.md 后	plan.md 存在，且包含意图、已解析路径、切片、每个切片的简述、跳过模式、已应用的预算以及综合方法（字段与**扫描计划（plan.md）**相同）。
分派子 Agent 后	要么已采用空语料库路径（不启动子 Agent；plan.md 记录可读文档数量为零），要么 plan.md 中列出的每个切片都有对应的 findings/<slice-slug>.md 文件。
写入 report.md 后	report.md 存在；标题与 references/report-template.md 一致（七个章节加上 ## Sources）。
返回调用方之前	references/failure-modes.md → **验证清单（编排者在最后运行）**中的每一项均已勾选，或者按照该 failure-modes 文件的规定，在 report.md 的 ## Gaps & Limitations 下记录任何未通过的检查。

1. 写入 plan.md——记录已解析路径（包括任何自动发现的路径）、意图摘要（如有提供）、每个切片的简述、跳过模式，以及综合发现的方法。
2. 分派切片——如果 Agent 支持子 Agent，则针对已解析路径中互不重叠的切片启动 1–3 个并行子 Agent；否则，自行按顺序处理相同切片——输出必须一致。每个切片都要在 output_dir 下写入 findings/<slice-slug>.md。
3. 综合并写入 report.md——将发现整理到七个固定章节中，并附上带路径的引用。
4. 返回前进行验证——满足最后一行硬性门槛的要求；执行 references/failure-modes.md 中的编号清单（验证清单（编排者在最后运行））。任何未通过的检查都必须按照该文件的规定记录在 Gaps & Limitations 中——不得在清单检查未通过但未说明的情况下返回交付内容。

Receive paths + optional intent ──→ Auto-discover if paths empty
                                   ↓
                                 Write plan.md (no user-confirmation pause)
                                   ↓
                                 Dispatch subagents (up to 3 parallel)
                                   ↓
                                 Collect findings/<slice>.md files
                                   ↓
                                 Synthesize report.md
                                   ↓
                                 Return paths to caller

与 web-research 不同，artifact-analysis 不会暂停以等待计划审核门槛。本地扫描成本低；编写 plan.md 是为了便于审计，让读者几周后仍能了解每个子 Agent 收到了什么指示。与 web-research 不同，缺少工具时不会快速失败——默认 Agent 的环境中具备文件系统搜索能力（读取、glob、grep）。

输入

字段	类型	必需	默认值	用途
intent	字符串	否	—	调用方要查找的内容及原因。若未提供，技能会提取任何在结构上重要的信息。
paths	字符串列表	否	自动发现	目录和/或明确指定的文件。若未提供，则自动发现（见下文）。
output_dir	绝对路径	否	派生	plan.md、findings/ 和 report.md 的存放位置。
refresh	布尔值	否	false	为 true 时，允许覆盖同一 output_dir 中先前运行生成的内容。

该技能不会解析调用方特有的结构。调用方传入意图字符串和/或路径列表。

自动发现

当 paths 未提供或为空时，扫描 beagle 的常规知识目录：

• .beagle/concepts/ — 概念规范和分析文件夹。
• .planning/ — 路线图、状态和阶段产物。
• docs/ — 项目文档。
• 顶层匹配 README*、BRIEF*、OVERVIEW*、CONTEXT*、CLAUDE.md、AGENTS.md 的文件。

已解析路径（包括任何自动发现的路径）会原样列在 plan.md 中，以便调用方准确查看纳入了哪些文件。

意图模式

• 存在 intent — 提取内容以与意图相关的内容为目标。离题内容只有在属于值得保留的具体引述或指标时，才会放入 Raw Detail Worth Preserving。
• 不存在 intent — 通用显著信息提取模式。子 Agent 会提取任何在结构上重要的内容（见解、决策、技术约束、用户／市场背景），不使用解释性筛选。

输出位置

如果调用方传入 output_dir，则按原样使用。否则，按以下方式推导默认值：

.beagle/analysis/<slug>/

Slug 推导（保持稳定，以便在同一天对相同输入重新运行时生成相同文件夹）：

1. 如果存在 intent，则根据意图字符串生成 slug：转换为小写，去除标点，将空白字符合并为单个连字符，并在不截断单词的边界处截断至 60 个字符（在第 60 个字符之前的最后一个连字符处截断；如果第 60 个字符之前没有连字符，则直接截断至 60 个字符）。
2. 如果不存在 intent，则根据第一个已扫描路径的基本名称按相同规则生成 slug。
3. 前置 YYYY-MM-DD-。

重新运行保护。 写入任何内容前，检查 output_dir 是否已包含 plan.md 或 report.md。如果包含且 refresh 不为 true，则拒绝操作，并在消息中指出已有文件夹的名称。当 refresh: true 时，在开始新一轮操作前，将先前内容归档至 <output_dir>/.archive-<timestamp>/。参见 references/failure-modes.md。

在概念文件夹约定中嵌入工件分析的调用方（例如 prfaq-beagle），应显式传入 output_dir，以便分析结果与其使用方放在一起：.beagle/concepts/<concept-slug>/analysis/。

扫描计划（plan.md）

计划会在任何子 Agent 运行前写入。它是审计记录，而不是审核关卡——此技能不会暂停等待用户确认。

plan.md 包含：

• 意图 — 原样保留输入字符串；如果不存在 intent，则填写 "generic salient extraction"。
• 已解析路径 — 所有实际将要扫描的路径，并在每个条目旁注明该路径来自自动发现还是调用方指定。
• 切片 — 已解析路径如何分配给 1–3 个子 Agent。各切片互不重叠。
• 每个切片的说明 — 每个切片用一段话概述告知相应子 Agent 要提取的内容。根据规范机械生成，以便读者查看 plan.md 时能预判告知各子 Agent 的任务。
• 跳过模式 — 本次运行应用的拒绝名单（参见 references/skip-patterns.md）。
• 已应用的预算 — 本次运行的子 Agent 数量（1–3）和当前生效的略读阈值（参见下文“预算默认值”）。
• 综合方法 — 各切片的发现将如何整合到 report.md 中。

报告：Wrote plan.md，然后继续分派。无需暂停，也无需审核关卡。

子 Agent 分派

最多同时运行 3 个子 Agent，分别处理互不重叠的切片。每个子 Agent 都会收到一份根据 plan.md 机械生成的任务说明——计划与任务说明之间不会出现解释偏差。任务说明模板位于 references/subagent-brief.md。

每个子 Agent：

• 扫描分配给它的路径切片，并遵循略读策略（分片文档：先阅读索引；大型文档：先阅读目录／标题）和跳过模式。
• 在 output_dir 下写入 findings/<slice-slug>.md。
• 向协调器返回一行简短状态（路径 + 状态），绝不直接返回发现内容。

协调器会等待所有子 Agent 完成，然后在综合之前确认每个预期的发现文件都已存在。文件缺失即为静默失败，并记录在 Gaps & Limitations 中——参见 references/failure-modes.md。

快速浏览策略

子 Agent 不会从头到尾阅读所有内容，而是采用以下方式：

• 分片文档（包含 index.md 和多个子文件的文件夹）——先阅读 index.md，然后只阅读索引标记为相关的子文件。
• 大型文档（单个文件超过约 50 页或约 2000 行）——先阅读目录、执行摘要和章节标题；仅从与意图相关（或在意图缺失时结构上重要）的章节中提取完整内容。发现文件会记录哪些章节是快速浏览、哪些是完整阅读。
• 短文档（单个文件，篇幅适中）——从头到尾阅读。

跳过模式

敏感、二进制以及供应商／构建路径会自动跳过，无需调用方再次指定。默认拒绝列表位于 references/skip-patterns.md。每个子 Agent 都会在 paths_skipped frontmatter 字段中记录跳过的路径，以便审计记录准确显示排除了哪些内容。

引用

发现文件和 report.md 中的每项声明都附有引用。引用格式见 references/citation-schema.md。简要来说：

• 必填字段： path（尽可能相对于扫描根目录的路径）、excerpt（文档中的原文引用）。
• 可选字段： lines（行号范围或单行，仅在子 Agent 自然获取到行号时填写——绝不自行编造）、heading（最近的上级标题）、document_type。

行内引用使用 [^n] 脚注；完整引用位于报告底部带编号的 Sources 部分。

综合整理（report.md）

报告固定分为以下七个部分，顺序如下。每个部分都必须包含，即使内容很少，也要添加一个项目说明情况。

1. ## Documents Found — 列出每个纳入的路径，并用一行说明其相关性。
2. ## Key Insights — 按主题归纳语料中最有价值的观察结果。
3. ## User / Market Context — 文档中提及的用户、客户、竞争情况和市场数据。
4. ## Technical Context — 平台、限制、集成和依赖项。
5. ## Ideas & Decisions — 每项标注为 accepted、rejected 或 open，并说明理由。刻意保留被否决的想法，以免未来工作再次提出。
6. ## Raw Detail Worth Preserving — 摘要中容易丢失的具体引文、数据点、指标及其他细节。
7. ## Gaps & Limitations — 语料无法确定的内容；哪些路径为空、被跳过或无法读取；哪些子 Agent 执行失败。

即使扫描看似完整，也必须包含 Gaps & Limitations。如实说明语料包含与未包含的内容，是产品的一部分。技能复制的完整字面模板位于 references/report-template.md。

失败模式

• 部分成功 — 一个或多个子 Agent 失败。技能会使用已成功的结果继续，并在 Gaps & Limitations 下逐一列出失败的切片，包括最后已知的任务简述和存根文件的原因。
• 语料为空 — 路径解析（自动发现 + 显式路径）未找到任何可读取的文档。技能会写入 plan.md，并生成最简 report.md，其中在 Gaps & Limitations 下仅列出一条“未找到文档”。技能不会启动子 Agent，并会正常返回调用方。后续如何处理由调用方决定。
• 静默失败检测 — 每个子 Agent 都必须在返回前至少写入一个存根文件 findings/<slice-slug>.md，其中包含 status: frontmatter（ok、empty、failed）。派发后缺少文件 = 静默失败，并记录在 Gaps & Limitations 下。
• 重新运行保护 — 参见上文“输出位置”；详情见 references/failure-modes.md。

与 web-research 不同，artifact-analysis 不会因缺少工具而快速失败。默认认为 Agent 环境中提供了文件系统搜索工具（读取、glob、grep）。如果这些工具意外缺失，技能会将其作为部分成功中的子 Agent 失败报告，而不是中止整个运行。

完整规则和结构化错误格式见 references/failure-modes.md。

预算默认值

可调整的选项，并非硬编码的不变量：

选项	默认值
并行子 Agent 数量	1-3
切片重叠	无（强制执行）
粗略浏览阈值（大型文档）	> ~2000 行或 > ~50 页

需要缩小或扩大范围的调用方可传入更具体的 paths 列表进行覆盖——每个子 Agent 分配一个路径可强制采用更窄的切片；传入单个文件夹则由技能在内部划分。

配套调用约定

其他 beagle 技能通过一个简短且有文档说明的约定调用此技能。最简调用只传入 intent；完整调用还会传入 paths、output_dir 和 refresh。

三个已知调用方（prfaq-beagle、brainstorm-beagle、strategy-interview）的完整示例，以及成功和拒绝时的返回格式，见 references/companion-contract.md。调用方应严格遵守此约定，不要另行发明并行的调用方式。

语气

此技能是一个不带特定语气的基础组件。它不会：

• 指导调用方判断哪些文档重要。
• 评判文档质量或主张可信度（这是 llm-judge 的职责）。
• 将调用方的意图改写为不同的问题。
• 采取特定立场（强硬、苏格拉底式、温和）——这是调用方的职责。
• 在发现结果或报告中发表主观评论。

如果调用方是辅导类技能（prfaq-beagle、brainstorm-beagle），辅导会在此技能运行前后进行。在此技能内部，意图会被视为最终意图。

不在范围内

• 扫描付费墙或需要身份验证的远程来源。请先使用文件工具提取内容，再传入路径。
• 使用大模型评判文档质量或主张可信度。请使用 llm-judge。
• 辅导、挑战，或带有主观倾向地重塑意图。
• 重写或编辑扫描的文档。此技能按设计仅提供只读功能。
• 二进制文件 / 图片 OCR、PDF 文本提取或格式转换。首个版本仅读取纯文本和 Markdown。
• 多语言分析。目前仅支持英文。
• 缓存或跨调用复用先前的发现结果。
• 长时间运行或定时扫描。

参考文件

• references/subagent-brief.md — 编排器在分派每个子 Agent 时，从 plan.md 中机械填充的模板。
• references/citation-schema.md — 必需和可选的引用字段、脚注约定，以及格式正确的示例。
• references/report-template.md — 包含全部七个固定部分的 report.md 原始骨架。
• references/failure-modes.md — 部分成功、语料库为空、静默失败检测和重运行保护规则。
• references/companion-contract.md — 程序化调用格式，以及 prfaq-beagle、brainstorm-beagle 和 strategy-interview 的完整示例。
• references/skip-patterns.md — 应用于每次运行的默认拒绝列表（敏感文件、二进制文件/媒体、供应商/构建文件）。