project-knowledge-hierarchy

Imported from wuchubuzai2018/expert-skills-hub (skills/project-knowledge-hierarchy/SKILL.md). Install upstream with npx skills add wuchubuzai2018/expert-skills-hub --skill project-knowledge-hierarchy. Copyright stays with the author.

Project Knowledge Hierarchy

介绍

项目知识库分层模型将项目知识分为 4 个层级，从上到下依次为：

• 项目层 (Project Layer) - 业务方向、核心流程、架构设计、决策记录
• 技术层 (Technology Layer) - 中间件、数据库设计、编码规范、第三方库、接口文档
• 资产层 (Assets Layer) - 产品需求、技术方案、测试用例、Bug记录
• 原始层 (Raw Assets) - 会议纪要、网页、聊天记录、录音转写等原始信息

前三层（项目层 → 技术层 → 资产层）遵循单向依赖原则：上层文档可引用下层文档，禁止反向依赖。 原始层不属于 docs/ 三层结构的正式目录，而是上层文档的信息源头；原始材料经提炼后才能进入正式层级。

详细说明见 references/raw-layer.md。

参考文件路由表

为保持主文件精简，下列内容按需加载：

执行步骤Workflow

Step 1: 询问目录位置

首先询问用户文档目录的创建位置：

请确认文档目录的创建位置，默认在当前工程的 docs 目录下创建。

根据用户回答确定目标路径，如用户无输入，默认在 docs/ 目录下创建。

Step 2: 检查已有目录

在创建前检查目标路径是否已存在文档结构：

# 检查目标目录是否已存在
if [ -d "$TARGET_DIR" ]; then
  echo "检测到已有目录结构，将仅创建缺失的目录和文件，不会覆盖已有内容。"
fi

如果目录已存在，进入增量模式：只创建缺失的子目录，不覆盖已有的 index.md。

原始层注意：原始层不在 docs/ 三层结构内（详见 references/raw-layer.md）；本步骤只检查 docs/，原始层存储位置由项目自定。

Step 3: 选择生成模式

根据用户需求和项目类型选择模式：

询问用户：

请选择生成模式：完整模式（推荐，含原始层）/ 单层模式 / 自定义模式 / 原始层模式？

如用户无明确选择，默认使用完整模式。

完整模式默认包含原始层：原始层是项目知识的源头，长期项目通常都需要；完整模式自动建好，后续随时可往里放原始材料。

Step 4: 创建目录结构

根据用户的系统环境，创建目录（使用 -p 确保幂等，已有目录不受影响）：

# 示例：创建完整四层结构（中文目录名）
mkdir -p docs/01-项目层/{01-项目概览,02-核心流程,03-架构设计,04-决策记录}
mkdir -p docs/02-技术层/{01-中间件配置,02-数据库设计,03-编码规范,04-第三方库,05-接口文档}
mkdir -p docs/03-资产层/{01-产品需求,02-技术方案,03-测试用例,04-Bug记录}

原始层位置：四种推荐方案（docs/00-原始层/ / 仓库独立目录 / 外部知识库）详见 references/raw-layer.md 存储位置建议。

Step 4.2: 原始层专用目录初始化（创建按来源类型的子目录）

原始层目录创建后，应额外按来源类型分子目录（推荐做法，正常执行）：

  # 在原始层根目录下创建按来源类型分的子目录
mkdir -p docs/04-原始层/{01-会议记录,02-网页资料,03-聊天记录,04-录音转写,05-其他杂项}

子目录含义与命名规范：

按日期分子目录是另一种合法做法（如 docs/raw/2026-Q3/、docs/raw/2026-Q4/），适用于来源类型单一的项目。

Step 4.3: 创建原始层层说明 README.md

原始层不建 index.md，但必须建 README.md 作为层说明（这是与三层的关键区别），正常执行：

模板与子目录、命名规范说明见 references/raw-layer.md（内含完整可复制的 README 模板代码块）。AI 按以下流程生成：

1. 复制 references/raw-layer.md 内「原始层层说明 README.md 模板」代码块
2. 按项目实际选择的子目录调整「子目录结构」表格
3. 按项目实际来源类型调整「文件命名规范」表格
4. 删除模板中的占位说明段落（如「### 使用方式」）
5. 将 README.md 放在原始层根目录下，不要放在某个子目录下

Step 4.1: 创建目录索引 index.md

每个目录（包括三层根目录、每个子目录）都必须创建 index.md 作为目录索引，模板见下文 目录索引模板。AI 在初始化阶段必须为每个目录生成对应的 index.md，即使是空目录也要保留空索引表，便于后续追加。

原始层例外：原始层下的目录不创建 index.md，但应在原始层根目录创建 README.md 作为层说明（详见 references/raw-layer.md）。

Step 5: 初始化 index.md 文件

仅在 index.md 不存在时创建，避免覆盖用户已有内容。本步骤只处理 docs/ 三层结构，原始层跳过本步骤。

docs/index.md（顶层总览）

模板详见 templates/root-index.md。AI 在初始化时按以下流程生成：

1. 复制 templates/root-index.md 内的模板内容
2. 替换占位符（YYYY-MM-DD、[作者/作者组]）
3. 确认三层目录链接与项目实际层级一致

各层 index.md 模板（层根目录）

模板详见 templates/layer-index.md。AI 在初始化时为每个层级根目录生成：

1. 复制 templates/layer-index.md 内的模板内容
2. 替换占位符（[层级编码]、[层级名称]、YYYY-MM-DD、[作者/作者组]）
3. 按该层级实际子目录填写「目录说明」表格
4. 按该层特点撰写「归档指引」（通常 1-3 条）

各目录内容说明

完整子目录职责一览（三层 × 全部子目录）详见 references/directory-structure.md「子目录职责一览」一节。原始层目录由项目自定，详见 references/raw-layer.md 存储位置建议。

目录索引模板（子目录 index.md）

每个子目录（如 01-项目概览/、02-数据库设计/ 等）都必须创建 index.md，作为该目录的文档清单入口。模板与字段说明详见 templates/subdir-index.md。

AI 在初始化与维护时的执行流程：

1. 复制 templates/subdir-index.md 内的模板内容
2. 替换占位符（[层级]、[子目录序号]、[子目录名称]、YYYY-MM-DD、[作者/作者组]）
3. 用一句话准确描述该子目录的归档范围
4. 删除示例行后，按实际文档条目填写「文档清单」表格（列固定为：编号 / 标题 / 状态 / 日期 / 文档）

强制约束：AI 在每次新增、修改或废弃具体文档时，必须同步更新对应目录 index.md 中的「文档清单」表格，确保索引与文件保持一致。

文档元数据规范（YAML 头部）

所有非 index.md 的具体业务文档，必须在文档开头附带 YAML 格式的元数据（位于 Markdown 起始的 --- 代码块中）。

完整模板（含字段定义、层级编码、占位符说明、完整示例）详见 templates/document.md。

字段定义（速查）

核心 6 字段（必须）

标准推荐字段（强烈推荐，借鉴自 OKF）

AI 默认应在生成文档时一并输出这两个字段，除非用户明确表示不需要。仅当用户要求"只要最小集"时，才退化为仅 6 字段。

扩展可选字段（按需启用）

借鉴自 OKF v0.2 的 resource / sources / stale_after，仅在场景需要时启用。完整说明见 references/okf-intro.md。

层级编码对照

AI 执行流程

1. 新建业务文档时，先复制 templates/document.md 的标准模板（核心 6 字段 + 推荐 2 字段）
2. 替换所有占位符（特别注意 文档编号 全局唯一）
3. 主动为 描述 与 标签 生成合理内容：
   • 描述：从文档标题与首段提炼单句摘要（≤ 80 字）
   • 标签：从主题、所属模块、涉及技术栈抽取 3-6 个分类标签
4. 编写正文
5. 在所属子目录 index.md 的「文档清单」表格中追加对应行
6. 当 状态 或 日期 变更时，同步更新所属 index.md 中的记录

强制约束：AI 在生成任何业务文档（不是 index.md）时，必须先输出完整的 YAML 元数据块（含 描述 与 标签），再编写正文。若用户提供的文档缺失元数据，应主动补全（含 描述 与 标签）并提示用户确认。仅当用户明确要求"只要最小集"时，才退化为仅 6 字段。