完整知识包示例

这个示例展示一个完整 wiki-first 知识包如何组合 sources/、wiki/、compiled/、indexes/、runs/、schemas/ 和 evals/。如果你要看 document-first 的产品或运营文档，请参考品牌产品、内容运营和私域运营示例。

acme-product-brief/
├── KNOWLEDGE.md
├── sources/
│   ├── product-one-pager.md
│   └── customer-interview.md
├── wiki/
│   ├── index.md
│   ├── sources/product-one-pager.md
│   ├── concepts/offline-queue.md
│   ├── contradictions/pricing.md
│   └── synthesis/rag-boundary.md
├── compiled/
│   ├── facts.md
│   ├── boundaries.md
│   └── briefing.md
├── indexes/
│   └── source-map.json
├── evals/
│   └── discovery.validation.json
├── runs/
│   ├── compile-2026-05-01T10-30-00Z.json
│   ├── context-2026-05-01T10-45-00Z.json
│   └── health-2026-05-01.md
└── schemas/
    └── local-claim.schema.json

KNOWLEDGE.md

---
name: acme-product-brief
description: Acme Widget 的产品事实、批准定位、价格边界、客服语言和有来源声明。用于撰写 Acme 营销文案、销售回复、客服答案、合作伙伴简报，或检查 Acme 相关 claim 是否已批准。
type: brand-product
profile: wiki-first
status: ready
version: 1.0.0
language: zh-CN
trust: user-confirmed
grounding: recommended
runtime:
  mode: data
metadata:
  producedBy:
    kind: agent-skill
    name: brand-product-knowledge-builder
    version: 1.0.0
---

# Acme Product Brief

## Context map

- 常规任务先读 `compiled/briefing.md`。
- 事实 claim 读 `compiled/facts.md`。
- 价格、合规和客户 logo 先读 `compiled/boundaries.md`。
- 新问题或争议 claim 回到 `wiki/`。
- 引用和核验读取 `sources/` 锚点。

compiled/facts.md

# Facts

- Acme Widget 支持离线队列。 [source: sources/product-one-pager.md#L12]
- Acme Widget 面向现场服务团队。 [source: sources/product-one-pager.md#L4]

indexes/source-map.json

{
  "claims": [
    {
      "claim_id": "clm-acme-offline-queue",
      "text": "Acme Widget 支持离线队列。",
      "status": "confirmed",
      "source": {
        "path": "sources/product-one-pager.md",
        "anchor": "L12"
      },
      "compiled_into": [
        "wiki/concepts/offline-queue.md",
        "compiled/facts.md"
      ]
    }
  ]
}

evals/discovery.validation.json

{
  "pack_name": "acme-product-brief",
  "cases": [
    {
      "id": "support-offline-queue",
      "prompt": "帮我回复客户：Acme Widget 是否支持离线队列？",
      "expected": "select",
      "reason": "需要 Acme 产品事实。"
    },
    {
      "id": "generic-email-edit",
      "prompt": "帮我润色一封普通英文邮件。",
      "expected": "reject",
      "reason": "任务不需要 Acme 知识。"
    }
  ]
}

runs/compile-...json

{
  "run_id": "compile-2026-05-01T10-30-00Z",
  "trigger": "ingest",
  "status": "passed",
  "profile": "wiki-first",
  "runtime_mode": "data",
  "builder_skill": {
    "name": "brand-product-knowledge-builder",
    "version": "0.7.2",
    "digest": "sha256:..."
  },
  "inputs": [
    {
      "path": "sources/product-one-pager.md",
      "sha256": "..."
    }
  ],
  "outputs": [
    {
      "path": "wiki/concepts/offline-queue.md",
      "operation": "updated"
    },
    {
      "path": "compiled/facts.md",
      "operation": "updated"
    }
  ],
  "diagnostics": []
}

runs/context-...json

{
  "run_id": "context-2026-05-01T10-45-00Z",
  "query": "Acme Widget 能离线工作吗？",
  "status": "passed",
  "resolver": {
    "tool": "agentknowledge-ref",
    "version": "0.7.2",
    "strategy": "profile-aware"
  },
  "activated_packs": [
    {
      "name": "acme-product-brief",
      "activation": "implicit",
      "status": "ready",
      "trust": "user-confirmed",
      "profile": "wiki-first",
      "runtime_mode": "data",
      "grounding": "recommended",
      "selected_files": [
        "compiled/facts.md"
      ],
      "source_anchors": [
        "sources/product-one-pager.md#L12"
      ],
      "warnings": []
    }
  ],
  "token_estimate": 420
}

Companion Skill

维护这个知识包的 Skill 可以提供：

agentknowledge-ref validate ./acme-product-brief
agentknowledge-ref compile ./acme-product-brief --changed sources/product-one-pager.md
agentknowledge-ref eval ./acme-product-brief --suite evals/discovery.validation.json

这些命令不属于知识包核心。它们是维护层工具，输出应写入 runs/。