kb-creator

使用时机

• 为项目生成结构化且可导航的知识库。
• 将冗长的文档（.txt、.docx、.pdf、较长的 .md 文件）转换为主题知识库。
• 从零开始为系统编写文档，并作为战略合作伙伴陪伴用户。

不适用场景：

• 已存在包含 10 个完整规范文件的 knowledge-base/（建议改为更新特定文件）。
• 用户要求一份特定文档（这是完整的知识库技能，而不是单个文件技能）。

---

运行模式

此技能在启动时会自动检测模式：

模式 A — 基于现有源文档（静默）

自动触发条件：docs/ 文件夹存在且包含源文件（.txt、.docx、.pdf 或非 README 的 .md 文件）。

行为：读取 docs/ 中的所有源文件，进行分析，并在项目根目录的 knowledge-base/ 中生成完整的规范知识库，不提问。自动完成。

模式 B — 从零开始（交互式）

自动触发条件：docs/ 文件夹不存在、为空或仅包含 README，且根目录中不存在 knowledge-base/。 显式触发条件：用户说“从零开始吧”“构建知识库”“我没有之前的文档”。

行为：作为战略合作伙伴开展工作——分析背景、发现缺口、提出 3-5 个战略性问题、提供带优缺点的方案，并逐个文件迭代和验证。

---

关键规范

输出位置（两种模式均适用）

知识库的所有文件都放在项目根目录的 knowledge-base/ 中。绝不与 docs/ 混放（docs/ 用于存放源文档）。

规范文件（必需的 10 个）

知识库必须包含以下 10 个文件，且文件名必须完全一致：

#	文件	内容
01	01_vision_y_objetivos.md	目的、各参与方的目标、范围、范围之外的内容
02	02_descripcion_general.md	技术栈、整体架构、外部集成
03	03_actores_y_roles.md	系统参与方、RBAC 表、权限、公开路由
04	04_modelo_de_datos.md	实体、ERD、关系、种子数据
05	05_reglas_de_negocio.md	按领域编码的规则（使用 RN-XX 一类的代码）
06	06_funcionalidades.md	按史诗组织的用户故事 / 功能
07	07_flujos_principales.md	端到端流程（身份验证、核心领域等）
08	08_arquitectura_propuesta.md	模式、目录结构、安全性、环境变量
09	09_decisiones_y_supuestos.md	已记录的设计决策 + 推断的假设
10	10_preguntas_abiertas.md	发现的不一致之处 + 按优先级排列的开放问题

此外，还需在 knowledge-base/README.md 中提供一个索引 README.md。

每个文件预期的内部结构请参见 assets/canonical-templates.md。

可选补充文件（允许）

如果领域需要，可以添加以 1X_ 或 2X_ 为前缀、采用 kebab-case 命名的补充文件。例如：

• 11_pagos_mercadopago.md（使用特定支付网关的电商项目）
• 12_devops_y_despliegue.md（基础设施复杂的项目）
• 13_observabilidad.md（遥测需求不简单的系统）

补充文件绝不能替代这 10 个规范文件，只能作为补充。

模式 A 工作流（静默）

模式 A → source: "ingest"（见下文的状态集成）

1. glob docs/*.{txt,docx,pdf,md} — 列出来源（排除 README）。
2. 阅读所有来源。
3. 对每个规范文件，从来源中提取相关内容，并按照 assets/canonical-templates.md 进行结构化。
4. 如果某个来源涵盖额外领域（例如，使用特定 PSP 的支付），则创建额外文件 1X_*.md。
5. 编写 10 个规范文件 + 额外文件 + README.md。
6. 最后附上汇总表：文件 → 行数 → 涵盖主题。
7. 如果由编排器编排：根据生成的文档推断 6 个 discovery 字段，并执行状态钩子（见 assets/state-contract.md §4）。来源："ingest"。

此模式下不要提问。 如果某个来源含糊不清，请在 10_preguntas_abiertas.md 中记录疑问并继续。如果无法有把握地推断某个 discovery 字段，请在 10_preguntas_abiertas.md 中记录不确定性——绝不要编造值。

模式 B 工作流（交互式）

模式 B → source: "interactive"（见下文的状态集成）

1. 分析可用上下文（仓库名称、用户消息、可见文件）。
2. 用一段话总结你对项目的理解。
3. 列出主要不确定事项（3-5 项）。
4. 提出 2-3 种初步方案，并说明各自的优缺点。
5. 提出3-5 个策略性问题（见 assets/strategic-questions.md），包括映射到 system_type 和 scale 的 discovery 问题 P0-sys 和 P0-scale。
6. 等待用户回复后再生成文件。
7. 然后，提出知识库（KB）的初始结构并进行验证。
8. 逐个迭代文件，边编写边征求反馈。
9. 如果由编排器编排：记录用户回复中的 6 个 discovery 字段，并执行状态钩子（见 assets/state-contract.md §4）。来源："interactive"。

按模式调整语气

• 模式 A：高效、客观、简洁。
• 模式 B：资深架构师 + 产品经理。质疑薄弱的决策。用 **假设：** 标记假设。提出替代方案。识别风险。

---

状态集成（由编排器编排）

此钩子是有条件执行且可独立运行的：仅当项目根目录中已存在 .jr-orchestrator-state.json 时才会执行（由 jr-orchestrator 编排的运行）。如果该文件不存在，行为与当前完全相同——不会创建任何状态文件。

执行时机：写入 knowledge-base/ 后立即执行（工作流的最后一步，在向用户返回结果之前）。

写入内容：仅写入 state.kb——绝不触及 step、owner、roadmap、skills 或 agents。

模式 → source 映射：

模式	state.kb.source
模式 A（静默，来自 docs/）	"ingest"
模式 B（交互式，从零开始）	"interactive"
混合运行：如果运行从 docs/ 开始（触发模式 A），则解析为 "ingest"，即使通过提问补全了空缺也是如此。主导来源决定 source。

完整算法、模式 A 的推断规则和低置信度规则：见 assets/state-contract.md。

---

代码示例

模式 A：结束时的汇总表

## KB generada en knowledge-base/

| Archivo | Líneas | Temas cubiertos |
|---------|--------|-----------------|
| 01_vision_y_objetivos.md | 84 | Propósito, 3 actores, alcance v5.0 |
| 02_descripcion_general.md | 132 | FastAPI + React, REST, 14 endpoints |
| ...

模式 B：策略性问题示例

**Pregunta 2 de 4 — Alcance del MVP**

¿Cuál es el alcance MÍNIMO viable para considerar el sistema "lanzable"?

- (a) Solo flujo de compra (catálogo + carrito + checkout simulado).
- (b) Flujo completo con pago real integrado.
- (c) Pago + panel admin con métricas.

**Por qué importa**: define qué entra en la primera versión y qué se posterga. Una respuesta vaga acá te genera scope creep en sprint 2.

---

命令

# Instalar la skill
npx skills add https://github.com/JuanCruzRobledo/kb-creator

# Invocar en el agente (carga automática por contexto):
"crear base de conocimiento del proyecto"
"generar KB desde los docs"
"armemos la documentación desde cero"

---

资源

• 模板：见 assets/canonical-templates.md — 10 个规范文件预期采用的内部结构。
• 策略性问题：见 assets/strategic-questions.md — 模式 B 的问题库（包括用于编排式 discovery 的 P0-sys 和 P0-scale）。
• 状态契约：见 assets/state-contract.md — state.kb 的 schema 切片、有条件写入算法、模式 A 推断规则、低置信度规则。