artifact-analysis

用途

artifact-analysis 用于把一组本地路径（或 beagle 项目的常规知识位置）转化为带引用的、结构化的洞察、上下文、决策与原始细节提取。它面向需要可审计输出的场景：调用方希望先看到扫描计划，再看到每个切片的发现文件，最后得到带引用支撑的综合报告。

典型触发场景包括：用户要求“分析这些文档”“扫描项目以获取上下文”“提取 .beagle/concepts/ 中的内容”。此外，其他 beagle 技能也可以程序化方式调用它，作为 grounding 的伴随技能。

主要能力

• 生成扫描计划 plan.md：在任何子代理运行之前写出，包含意图、解析后的路径、切片划分、每切片简报、跳过模式、应用的预算以及综合方法。它是审计轨迹，而非评审关卡，技能不会暂停等待用户确认。
• 切片调度：在代理支持子代理时，最多并发运行 3 个子代理处理互不重叠的切片；否则由自身顺序处理相同切片，输出一致。每个切片在 output_dir 下写出 findings/<slice-slug>.md。
• 综合报告 report.md：将发现折叠进固定的七个章节，并附路径锚定引用。
• 返回前验证：执行 references/failure-modes.md 中的编号检查清单，任何失败项按该文件规定记入 Gaps & Limitations。
• 自动发现：当 paths 缺失或为空时，扫描 beagle 的常规知识位置，包括 .beagle/concepts/、.planning/、docs/，以及匹配 README*、BRIEF*、OVERVIEW*、CONTEXT*、CLAUDE.md、AGENTS.md 的顶层文件。
• 引用机制：每条声明都带引用，必填字段为 path（尽量相对于扫描根目录）与 excerpt（文档中的逐字引用字符串）；可选字段包括 lines、heading、document_type。行内引用使用 [^n] 脚注，完整引用位于报告底部的编号 Sources 章节。
• 略读策略：分片文档先读 index.md，再读索引指向的相关子文件；大文档（单文件超过约 50 页或约 2000 行）先读目录、执行摘要与章节标题，仅对与意图相关（或意图缺失时结构重要）的章节拉取全文；短文档端到端读取。发现文件记录哪些章节被略读、哪些被完整读取。
• 跳过模式：敏感、二进制与 vendor/build 路径按默认拒绝列表静默跳过，每个子代理在 paths_skipped frontmatter 字段记录被跳过的路径。

使用方式

输入字段包括：intent（字符串，可选，说明调用方在找什么及原因）、paths（字符串列表，可选，默认自动发现）、output_dir（绝对路径，可选，默认派生）、refresh（布尔值，可选，默认 false，为 true 时允许覆盖同一 output_dir 中的先前运行）。

工作流为四步，顺序不可跳过：

1. 写出 plan.md——解析路径（含自动发现）、意图摘要、每切片简报、跳过模式以及发现如何综合。
2. 调度切片——支持子代理时最多 3 个并发子代理处理互不重叠的切片，否则顺序处理；每个切片写出 findings/<slice-slug>.md。
3. 综合 report.md——将发现折叠进七个固定章节，附路径锚定引用。
4. 返回前验证——满足硬性关卡，执行检查清单，失败项记入 Gaps & Limitations。

硬性关卡：plan.md 写出后才进入下一步；子代理调度后，要么走了空语料路径，要么 plan.md 中列出的每个切片都有 findings/<slice-slug>.md 落盘；report.md 写出后，标题需匹配 references/report-template.md（七个章节加 ## Sources）；返回调用方前，检查清单全部勾选或失败项已记录。

输出位置：若调用方传入 output_dir 则原样使用，否则派生默认路径 .beagle/analysis/<slug>/。slug 派生规则稳定：意图存在时从意图字符串派生（小写、去标点、空白折叠为单连字符、在词边界截断至 60 字符）；意图缺失时从首个扫描路径的 basename 派生；前缀 YYYY-MM-DD-。重跑保护：写入前检查 output_dir 是否已含 plan.md 或 report.md，若存在且 refresh 不为 true，则拒绝并指明现有文件夹；refresh 为 true 时先将先前内容归档到 <output_dir>/.archive-<timestamp>/。

报告固定七章节：## Documents Found、## Key Insights、## User / Market Context、## Technical Context、## Ideas & Decisions（每条标记 accepted、rejected 或 open 并附理由）、## Raw Detail Worth Preserving、## Gaps & Limitations。Gaps & Limitations 即使扫描看似完整也必需。

适用场景

• 用户要求对本地文档进行带引用的结构化阅读。
• 其他 beagle 技能程序化调用作为 grounding 伴随技能。
• 调用方需要可审计输出：提取前写好的计划、每切片的发现文件、带引用支撑的综合报告。

限制

• 不用于代码库查找（如“这个函数定义在哪”“grep 这个符号”），应搜索代码库。
• 不用于网络研究，应使用 web-research。
• 不用于两个实现的比较评估或来源可信度裁定，应使用 llm-judge。
• 不用于改写或编辑被扫描文档，应使用 humanize-beagle 或直接编辑文件。
• 不处理 PDF、图片 OCR 或格式转换；第一版仅读取纯文本与 markdown。
• 不处理付费墙或需认证的远程来源，它是本地文件系统原语。
• 不进行对调用方问题的教练、挑战或重塑，那属于调用方职责。
• 不缓存或跨调用复用先前发现，不支持长时间运行或定时扫描。
• 目前仅支持英语分析。
• 语气中性：不指导调用方哪些文档重要，不裁定文档质量或声明可信度，不重塑意图，不采取特定姿态，不在发现或报告中发表评论。

失败模式

• 部分成功：一个或多个子代理失败时，技能继续处理成功部分，并在 Gaps & Limitations 中枚举每个失败切片，包括最后已知简报与 stub 文件原因。
• 空语料：路径解析（自动发现加显式路径）得到零个可读文档时，写出 plan.md 与最小 report.md（Gaps & Limitations 下仅一条“no documents found”），不生成子代理，干净返回调用方。
• 静默失败检测：每个子代理返回前至少写出带 status frontmatter（ok、empty、failed）的 stub findings/<slice-slug>.md；调度后文件缺失即静默失败，记入 Gaps & Limitations。
• 与 web-research 不同，artifact-analysis 不因缺少工具而快速失败；文件系统搜索（read、glob、grep）假定存在于代理环境中，若确实缺失，将作为子代理失败在部分成功下呈现，而非中止整个运行。

预算默认值

可调旋钮而非硬编码不变量：并行子代理 1-3；切片重叠无（强制）；略读阈值（大）超过约 2000 行或约 50 页。调用方可通过传入更具体的 paths 列表覆盖范围。

伴随调用契约

其他 beagle 技能通过一个小型文档化契约调用本技能。最小调用仅传 intent；完整调用增加 paths、output_dir 与 refresh。已知调用方包括 prfaq-beagle、brainstorm-beagle、strategy-interview。

参考文件

references/subagent-brief.md、references/citation-schema.md、references/report-template.md、references/failure-modes.md、references/companion-contract.md、references/skip-patterns.md。