# haystack - Doramagic AI Context Pack

> 定位：给用户宿主 AI 装载的开工前上下文。它不代表已经安装、运行或验证目标项目。

## 项目

- canonical_name: `deepset-ai/haystack`
- capability: Open-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.
- expected_user_outcome: Open-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.

## 基础边界

- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。
- 项目事实必须来自 repo evidence、Claim Graph 或明确来源。
- 遇到未验证能力时，必须标记为待验证，而不是补全为事实。
- publish_status: `publishable`
- blocking_gaps: none

---

## Doramagic Context Augmentation

下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。

## Human Manual 骨架

使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。

宿主 AI 硬性规则：
- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。
- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。
- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。

- **Haystack 简介**：importance `high`
  - source_paths: README.md, VERSION.txt
- **快速入门指南**：importance `high`
  - source_paths: docs-website/docs/overview/installation.mdx, docs-website/docs/overview/get-started.mdx
- **核心概念**：importance `high`
  - source_paths: docs-website/docs/concepts/concepts-overview.mdx, docs-website/docs/concepts/components.mdx, docs-website/docs/concepts/pipelines.mdx, docs-website/docs/concepts/data-classes.mdx
- **Pipeline 系统**：importance `high`
  - source_paths: docs-website/docs/concepts/pipelines/creating-pipelines.mdx, docs-website/docs/concepts/pipelines/debugging-pipelines.mdx, docs-website/docs/concepts/pipelines/serialization.mdx, docs-website/docs/concepts/pipelines/asyncpipeline.mdx
- **文档存储系统**：importance `high`
  - source_paths: docs-website/docs/concepts/document-store.mdx, docs-website/docs/document-stores/inmemorydocumentstore.mdx, docs-website/docs/document-stores/qdrant-document-store.mdx, docs-website/docs/document-stores/weaviatedocumentstore.mdx
- **文档转换与预处理**：importance `medium`
  - source_paths: docs-website/docs/pipeline-components/converters.mdx, docs-website/docs/pipeline-components/preprocessors.mdx, docs-website/docs/pipeline-components/preprocessors/documentsplitter.mdx
- **文本嵌入组件**：importance `high`
  - source_paths: docs-website/docs/pipeline-components/embedders.mdx, docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx, docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx
- **LLM 生成器**：importance `high`
  - source_paths: docs-website/docs/pipeline-components/generators.mdx, docs-website/docs/pipeline-components/generators/openaichatgenerator.mdx, docs-website/docs/pipeline-components/generators/anthropicchatgenerator.mdx

## Repo Inspection Evidence / 源码检查证据

- repo_clone_verified: false
- repo_inspection_verified: false
- repo_commit: `unknown`

宿主 AI 硬性规则：
- 没有 repo_clone_verified=true 时，不得声称已经读过源码。
- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。
- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。

## Doramagic Pitfall Constraints / 踩坑约束

这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。

### Constraint 1: 能力判断依赖假设

- Trigger: README/documentation is current enough for a first validation pass.
- Host AI rule: 将假设转成下游验证清单。
- Why it matters: 假设不成立时，用户拿不到承诺的能力。
- Evidence: capability.assumptions | github_repo:221654678 | https://github.com/deepset-ai/haystack | README/documentation is current enough for a first validation pass.
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 维护活跃度未知

- Trigger: 未记录 last_activity_observed。
- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Evidence: evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | last_activity_observed missing
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 3: 下游验证发现风险项

- Trigger: no_demo
- Host AI rule: 进入安全/权限治理复核队列。
- Why it matters: 下游已经要求复核，不能在页面中弱化。
- Evidence: downstream_validation.risk_items | github_repo:221654678 | https://github.com/deepset-ai/haystack | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 存在评分风险

- Trigger: no_demo
- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。
- Why it matters: 风险会影响是否适合普通用户安装。
- Evidence: risks.scoring_risks | github_repo:221654678 | https://github.com/deepset-ai/haystack | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 5: issue/PR 响应质量未知

- Trigger: issue_or_pr_quality=unknown。
- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。
- Why it matters: 用户无法判断遇到问题后是否有人维护。
- Evidence: evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | issue_or_pr_quality=unknown
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 6: 发布节奏不明确

- Trigger: release_recency=unknown。
- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。
- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。
- Evidence: evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | release_recency=unknown
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。