knowledge-base-add-project

在知识库中添加或更新项目

在 projects/<category>/<project>/ 下添加新的上游项目，或刷新现有项目。知识库根目录的 README.md 是规范：其中的 Standard documents 部分是各固定文件内容的权威说明，Metadata 部分定义了前置元数据，而 Tracked projects 表格是索引。本技能描述的是工作流——不会重述这些规范，而是告诉你如何以幂等方式创建和更新条目。

定位知识库

在知识库仓库中操作。标准本地检出路径为 ~/code/knowledge-base；如果该路径不存在，则运行 git clone [email protected]:mmontes11/knowledge-base.git ~/code/knowledge-base。以下所有路径均相对于仓库根目录。

两种模式

• 添加 — 从上游创建全新的项目文件夹（也可以选择新建类别）。
• 更新 — 对现有项目进行幂等维护；每月的更新计划会触发此操作。

模式 A — 添加项目

1. 阅读目标类别的 projects/<category>/README.md，以及根目录 README.md 中的 Standard documents 和 Metadata 部分。
2. 选择类别（已有类别，或先添加新类别——见下文）和项目 slug = 上游仓库名称的小写 kebab-case 格式。
3. 创建 projects/<category>/<project>/，并根据上游内容填写根目录 README.md 规范要求的四份标准文档：
   • README.md、api-reference.md、releases.md、features.md — 必需的四份文档。
   • architecture.md — 仅当项目是复杂的多组件系统时才需要。完成前渲染每个 mermaid 图表：

     mermaid-render /tmp/d.mmd   # 干净且非空的 SVG/PNG 表示该代码块可在 GitHub 上渲染
     

4. 每份文档的前置元数据都要包含：upstream（规范仓库 URL）和 last_updated（UTC 日期）。
5. 链接，不要复制 — 每条事实性陈述都要链接到其上游来源；不要直接插入完整 schema、规范或生成的转储内容。
6. 在根目录 README.md 的 Tracked projects 表格中添加一行。
7. 提交 docs(<category>/<project>): <summary> 并直接推送到 main。

添加类别

1. 创建 projects/<category>/README.md，简要描述该领域（名称采用小写 kebab-case 格式）。
2. 在 Tracked projects 中添加该类别首个项目的行。

模式 B — 更新项目（维护任务）

每次运行都必须是幂等的：上游状态未变化时，不应产生任何差异。按以下顺序处理范围内的一个项目：

1. 阅读当前文件夹和前置元数据。
2. 获取上游准确信息：最新发布标签、所有比 releases.md 中最新条目更新的发布内容，以及 API/功能文档的变更。
3. releases.md — 在开头添加新条目，最多保留 10 条。
4. api-reference.md — 仅当 API 表面发生变化时更新（新增、移除或重命名 Kind 或表面）。
5. features.md — 仅当功能文档或发布说明发生变化时更新。
6. architecture.md — 仅当该文件存在且组件集合或组件交互发生变化时更新；重新渲染每个 mermaid 图表（mermaid-render），并确认图表仍与当前组件一致。
7. README.md — 仅当描述、许可证或上游 URL 发生变化时更新。
8. 在每个已修改文件的前置元数据中更新 last_updated。
9. 每个项目只提交一次：docs(<category>/<project>): <summary>。
10. 直接推送到 main。如果本次任务由 Multica issue 触发，则在推送完成后将其标记为已完成。

卫生规范（两种模式均适用）

• 绝不包含凭据、令牌或特定集群的数据。
• 概述并添加链接；不要整段照抄上游文本（遵守上游许可和署名要求）。
• 每条事实性陈述都要链接到其来源。
• 保持差异小且易于说明——每次只处理一个项目。