Notion How-To Guide Database 实战在 Codex 中用结构化数据库沉淀可复用的团队操作手册【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本文基于本仓库notion-knowledge-captureSkill 的 How-To Guide Database 参考文档系统讲解如何在 Notion 中设计并维护一张专门承载操作指南How-To的知识库数据库。你将掌握该数据库的完整 Schema 设计、属性取值规范、从对话到结构化页面的创建流程、数据库的 API 级初始化方法以及让指南长期可信可用的最佳实践可直接落地到团队的工程 Wiki 体系。一、How-To Guide Database 的定位为常见任务服务的程序化文档库原文档开篇即明确了它的使命Procedural documentation for common tasks——即把如何完成某个常见任务这一类型的过程性知识以结构化、可检索、可更新的方式沉淀下来。它与知识捕获体系中的其他数据库分工明确共同构成一套完整的企业知识库知识类型对应数据库参考文档通用文档Documentation Databasedocumentation-database.md架构/技术决策Decision Log (ADR)decision-log-database.md常见问答FAQ Databasefaq-database.md团队专属内容Team Wikiteam-wiki-database.md步骤式指南How-To Guide Database本篇文章主题事故/项目复盘Learning Databaselearning-database.md在 database-best-practices.md 的数据库选择指南中Step-by-step guides逐步操作指南明确指向 How-To Guide Database。从 SKILL.md 的 Quick Start 可以看出该 Skill 的核心工作模式是先把对话或笔记识别为正确的知识类型decision、how-to、FAQ、learning、documentation再依据reference/目录下对应数据库 Schema 生成结构化页面。因此How-To Guide Database 是整个知识捕获体系中专门承接过程性、步骤性知识的那一张表。二、Schema 深度拆解7 个属性如何支撑一篇可执行的操作指南原文档给出了数据库的完整属性设计这是整篇指南的骨架属性类型可选值用途Titletitle-How to [Task]ComplexityselectBeginner, Intermediate, Advanced所需技能水平Time Requirednumber-预估完成分钟数Prerequisitesrelation链接到其他指南前置知识CategoryselectDevelopment, Deployment, Testing, Tools任务类别Last Testeddate-步骤最近一次验证时间Tagsmulti_select-技术/工具标签逐项说明其设计意图与在实操中的用法Titletitle 类型作为数据库的主标识属性命名约定为 How to [Task]如 How to Set Up Local Development Environment。一致的命名前缀让数据库在按标题排序、被 wiki 页面引用时都清晰可辨这与 database-best-practices.md 中用 Title 作为主标识、保持命名一致的原则完全吻合。Complexityselect 类型仅允许 Beginner / Intermediate / Advanced 三档把读者需要多高的技能门槛固化为可筛选的枚举值。团队新人可以据此快速筛选 Beginner 级别的上手指南。Time Requirednumber 类型以分钟为单位的纯数字用于让读者预估投入时间如部署指南填写 15-20。number 类型天然支持排序与区间过滤可支撑10 分钟内能完成的任务这类检索。Prerequisitesrelation 类型这是数据库实现知识依赖链的关键。通过 relation 关联其他指南页面实现先读 A 再读 B的依赖关系。relation 类型在创建时指向同一数据库或其他数据库的页面因此前置条件可以在创建后动态调整不会产生硬编码的死链。Categoryselect 类型Development / Deployment / Testing / Tools 四个固定类别对应团队日常最典型的任务域。类别枚举化之后按类别分组视图Group by Category即可一键呈现所有部署类指南。Last Testeddate 类型记录该过程被验证的日期。这个字段是操作手册区别于普通文档的灵魂——工具链、依赖版本会变只有最近验证过的步骤才值得信任。结合 documentation-database.md 中Needs Review: Filter where Last Reviewed 90 days ago的视图思路可以用 Last Tested 过滤出超过某阈值如 180 天未验证的指南驱动周期性复测。Tagsmulti_select 类型多选标签用于标记技术/工具维度如 docker、k8s、python与 Category 的任务域维度互补。标签是检索友好的自由分类手段建议liberally宽松地打标以提升可发现性。从 evaluations/README.md 对conversation-to-wiki.json的评估描述可以看到这套 Schema 落地时的关键行为包括从对话中提取步骤、坑点与最佳实践将内容识别为 How-To Guide 类型用Overview、Prerequisites、Steps、Troubleshooting结构组织并保留命令、配置等技术细节——这正是上述 7 个属性共同支撑的可执行品质。三、创建 How-To 指南从对话到结构化页面的完整流程3.1 属性填充规范原文档给出了创建页面时的属性填充示例这是直接可复制的数据载荷{ Title: How to Set Up Local Development Environment, Complexity: Beginner, Time Required: 30, Category: Development, Last Tested: 2025-10-01, Tags: setup, environment, docker }注意其中Prerequisites未出现在示例中——它是 relation 类型需要在创建后或创建时通过 relation 数组指向已存在的其他指南页面因此示例省略了它。Time Required是纯数字分钟数Last Tested使用 ISO 日期字符串。3.2 端到端工作流对话 → 指南 → 可发现结合 SKILL.md 的 Workflow 与 examples/how-to-guide.md 的完整实例一篇 How-To 指南的诞生遵循五步定义捕获目标明确目的、受众、新鲜度以及这是新建还是更新。从对话中判断内容类型是否为 how-to区别于 decision、FAQ。定位目标数据库依据reference/下的*-database.md指南选择正确的数据库此处即 How-To Guide Database确认必需属性title、tags、owner、status、date、relations。若有多个候选库向用户确认。提取并结构化从对话中抽取事实、步骤、前置条件、坑点与边界情况将内容组织为 Overview prerequisites、编号步骤、验证步骤、Troubleshooting、相关资源等小节。在 Notion 中创建/更新使用Notion:notion-create-pages并传入正确的data_source_id数据库 ID与属性更新已有页面则先Notion:notion-fetch再Notion:notion-update-page。链接与暴露在 hub 页面和关联记录上添加 relation/backlink并补充简短的摘要/changelog如需后续任务则在任务数据库中创建并关联。以 examples/how-to-guide.md 中的生产环境部署实例为参照一篇合格指南的正文骨架应包含Overview含 Time Required 与 Complexity 元信息→ Prerequisites 勾选清单 → 编号部署步骤含真实命令→ 验证清单可量化指标→ Troubleshooting症状 → 对策→ Best Practices → Related Docsmention-page 链接。示例中的元数据行**Time Required**: 15-20 minutes | **Complexity**: Intermediate即对应数据库中的 number 与 select 属性说明正文头部元信息与数据库属性是一一对应、双向同步的关系。3.3 底层工具调用链上述流程实际由 Notion MCP 工具驱动调用顺序为Notion:notion-search → 检索目标位置如 deployment documentation Notion:notion-fetch → 拉取数据库 Schema 与既有页面拿到精确属性名/类型 Notion:notion-create-pages → 以 data_source_id 定位数据库并创建页面 Notion:notion-update-page → 在 wiki 首页等位置插入链接暴露新指南其中notion-fetch尤其重要——database-best-practices.md 明确要求Before creating pages, always fetch database to get schema因为它会返回精确的属性名与类型避免因属性名拼写不一致导致创建失败。四、从零初始化数据库用 Notion API 定义 How-To Guide Database如果团队尚未建立该数据库可以参照 database-best-practices.md 与 documentation-database.md 中的Notion:notion-create-database用法为 How-To Guide Database 构造等价的建库载荷。下面是根据 How-To 属性集适配的完整示例属性定义方式与仓库文档中 documentation 库的示例保持一致{ parent: {page_id: wiki-page-id}, title: [{text: {content: How-To Guides}}], properties: { Title: {title: {}}, Complexity: { select: { options: [ {name: Beginner, color: green}, {name: Intermediate, color: yellow}, {name: Advanced, color: red} ] } }, Time Required: {number: {format: number}}, Prerequisites: {relation: {database_id: how-to-database-id, single_property: {}}}, Category: { select: { options: [ {name: Development, color: blue}, {name: Deployment, color: purple}, {name: Testing, color: orange}, {name: Tools, color: gray} ] } }, Last Tested: {date: {}}, Tags: {multi_select: {options: []}} } }几点实操提示Prerequisites 的 relation 指向relation类型需要指定目标database_id。若前置条件需要跨库引用例如关联到 Documentation 数据库中的概念文档应指向对应数据库这体现了知识互联的设计哲学。为枚举值配色Notion select 选项支持颜色语义化如绿色简单、红色困难documentation-database.md的示例中也使用了 color 字段blue/green/gray/yellow/red 等在建库时一并配置可显著提升视图可读性。建库后务必 fetch 验证创建完成后用Notion:notion-fetchid 传数据库 URL 或 ID拉取实际 Schema确认属性名与类型与设计一致再进行页面创建。五、Best Practices让操作手册长期可信可用的五条纪律原文档给出的最佳实践是这套体系的运行守则逐条展开并结合仓库证据说明其必要性使用一致的命名Use consistent naming标题一律以 How to... 开头。命名一致不仅是美学问题更直接支撑 SKILL.md 工作流中以明确、可发现的标题创建页面的质量标准也让按标题排序的视图干净有序。测试流程后再发布Test procedures发布前逐条验证步骤真实可执行。这与Last Tested属性互为表里——属性是验证结果的记录本条是验证动作的纪律。包含时间预估Include time estimates借助Time Required属性让读者规划时间。示例指南中的**Time Required**: 15-20 minutes表明该信息应同时呈现在页面正文中。链接前置条件Link prerequisites用Prerequisitesrelation 明确依赖关系让先读什么一目了然避免读者在缺失上下文时误操作。定期更新Update regularly工具链或系统变更后重新验证并刷新Last Tested。这与 database-best-practices.md 中定期审视属性、创建常用视图、为常见场景维护视图的建议形成完整闭环——可以建立Last Tested 距今超过 180 天的筛选视图来驱动复测。此外database-best-practices.md 的五条核心原则Keep It Simple、Consistent Naming、Include Metadata、Enable Discovery、Plan for Scale在本库中均有对应属性精简约 7 项简单、Title/Status/Tags/Owner 齐备命名与元数据、relation 与 views 支撑检索可发现、Category 枚举为未来扩展预留筛选维度可扩展。六、运行前置条件接入 Notion MCPHow-To Guide Database 的使用依赖 Notion MCP 服务。从 agents/openai.yaml 可以看到该 Skill 声明的依赖类型为mcp、传输方式streamable_http、服务地址https://mcp.notion.com/mcp。按 SKILL.md 的说明若 MCP 调用失败Notion MCP 未连接需要先完成三步配置# 1. 添加 Notion MCP 服务 codex mcp add notion --url https://mcp.notion.com/mcp # 2. 启用远程 MCP 客户端二选一 # 方式 A在 config.toml 中设置 [features].rmcp_client true # 方式 B命令行直接启用 codex --enable rmcp_client # 3. 使用 OAuth 登录 codex mcp login notion登录成功后需要重启 Codex之后再回到知识捕获工作流的第一步继续执行。这一点在仓库中专门强调过重启前 Agent 应正常结束当前回答并提示用户重启后可继续。七、质量验证评估一个 How-To 指南是否合格evals READMEevaluations/README.md提供了如何验证该 Skill含 How-To 捕获能力的评估方法可作质量标尺内容提取准确捕获对话要点保留具体技术细节命令、配置而非泛泛占位符。内容类型识别正确识别为 how-to并使用与 reference 文档匹配的结构Overview、Prerequisites、Steps、Troubleshooting。Notion 集成检索到合适的目标位置wiki、相应数据库用清晰标题创建页面放置于正确 parent 之下元数据完整。质量标准内容可执行、面向未来复用技术准确性保留组织方式利于发现排版提升可读性。其中conversation-to-wiki.json评估场景专门覆盖将部署讨论保存为 how-to 指南其成功判据示例包括使用带编号步骤的 How-To 格式组织内容保留对话中的确切 bash 命令创建标题格式为 How to [Action] 的页面放置于 Engineering Wiki → Deployment 区块。好的判据是具体且可测试的如保留确切的 bash 命令而不是创建了好的文档这类模糊描述。八、相关资源How-To Guide Database 参考文档本文主题文档Skill 主文档 SKILL.md完整工作流与 MCP 配置How-To 指南完整示例生产部署指南的端到端范本数据库最佳实践建库、取 Schema、库选择指南数据库家族参考documentation-database、faq-database、decision-log-database、team-wiki-database、learning-databaseSkill 依赖声明Notion MCP 服务配置Skill 评估说明How-To 捕获质量评估标准【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考