企业官网建设流程全解析

agentic-awesome-skills 技能目录刷新完全指南：本地 Catalog 重建、索引生成与维护者同步流程

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills

本指南面向 agentic-awesome-skills 仓库的维护者与深度使用者，完整讲解如何基于本仓库的skills/权威源重建本地技能目录（catalog）、仅刷新skills_index.json索引、使用 Windows 启动器拉起本地 Web 应用，以及维护者在合并源码后如何正确对待生成产物、规避 CI 漂移。读完你将掌握从git pull到本地目录可用的完整操作链，并理解索引生成与 Web 资产同步的底层实现。

本地目录的构建链路：从权威源到可检索索引

在动手执行任何命令之前，先明确一个核心前提：本地目录（local catalog）是从本仓库检出的skills/权威源构建出来的。重新生成索引不会拉取新的上游技能，也不会发布网站。

从 package.json 的scripts定义可以看到整条生成链路的编排：

• validate：运行tools/scripts/validate_skills.py做技能规范性校验；
• plugin-compat:sync：运行tools/scripts/plugin_compatibility.py同步插件兼容性报告；
• index：运行tools/scripts/generate_index.py生成skills_index.json；
• bundles:sync：运行tools/scripts/sync_editorial_bundles.py同步编辑精选包；
• sync:metadata：同步仓库元数据；
• catalog：运行tools/scripts/build-catalog.js构建data/catalog.json；
• build:aas-v1-catalog：构建离线 AAS v1 目录；
• 这些步骤由chain串联，而npm run build就是chain的别名。

因此，索引与目录是派生产物（derived artifacts），它们的唯一事实来源是skills/下的技能源文件——每个技能目录下的SKILL.md及其 YAML frontmatter。理解了这一点，就能明白为什么原文档反复强调"仅刷新索引 ≠ 完整构建"。

刷新前置准备：Node、Python 依赖与干净检出

执行任何生成命令前，需满足两个环境前提：

1. Node 版本：必须满足根目录 package.json 中engines声明的node >= 22；
2. Python 依赖：生成脚本依赖 tools/requirements.txt 中的pyyaml>=6.0（索引生成器generate_index.py依赖yaml.safe_load解析技能 frontmatter）。

依赖安装命令：

# 安装根目录依赖（严格按锁文件安装） npm ci # 安装 Web 应用依赖（apps/web-app 子项目） npm run app:install

在干净的main检出上，先获取上游已接受的源码变更，且在更新前保存好自己未提交的无关工作：

git pull --ff-only origin main

--ff-only保证快进式更新，避免本地意外提交与上游历史分叉。之后就可以执行构建或启动命令。

完整刷新：npm run build 与 npm run app:dev

这是文档推荐的标准刷新路径，两条命令各有分工：

npm run build npm run app:dev

• npm run build运行完整的校验与生成链（即chain）：技能校验 → 插件兼容性同步 → 索引生成 → 编辑精选包同步 → 元数据同步 → 目录构建 → AAS v1 离线目录构建。它产出根目录的skills_index.json、data/下的目录与兼容性文件；
• npm run app:dev先执行npm run app:setup准备 Web 静态资源，再进入apps/web-app启动 Vite 开发服务器。

从 setup_web.js 的main()可以看到app:setup具体做了什么：

• 把根目录的skills_index.json复制为apps/web-app/public/skills.json（同时生成skills.json.backup备份）；
• 遍历skills/下每个技能的SKILL.md，复制到apps/web-app/public/skills/下作为 Web 端可检索的技能正文；
• 复制前会做符号链接与越界安全检查（copyIndexFile拒绝经符号链接复制索引、拒绝把索引复制到public之外），这是 Web 资产准备环节的安全防线。

也就是说，build决定"生成什么"，app:dev决定"把生成物端到本地 Web 服务供检索"。

仅刷新索引：npm run update:skills

如果只想更新索引而不做完整构建，使用索引专用命令：

npm run update:skills

从 package.json 的脚本定义可见其构成：

"update:skills": "node tools/scripts/run-python.js tools/scripts/generate_index.py && node tools/scripts/copy-file.js skills_index.json apps/web-app/public/skills.json && node tools/scripts/copy-file.js skills_index.json apps/web-app/public/skills.json.backup"

它做三件事：

1. 运行tools/scripts/generate_index.py重新生成skills_index.json；
2. 将其复制为apps/web-app/public/skills.json；
3. 同时更新skills.json.backup备份副本。

注意：它不会运行校验、目录构建、精选包同步等完整链路，因此"不是完整的 bundle/catalog 构建"。若你的变更涉及技能源文件本身，建议仍走npm run build完整链路。

索引生成器源码解读：generate_index.py 如何工作

若要真正理解"本地目录从何而来"，值得深入 generate_index.py 的实现：

• 遍历与发现：generate_index()递归遍历skills/目录，跳过隐藏目录与符号链接的SKILL.md，以包含SKILL.md的目录为单位生成一条技能记录（id、path、name、description、risk、source、date_added、plugin等字段）；
• frontmatter 解析：parse_frontmatter()逐行清洗 YAML（对含@的未加引号值自动加引号），再交给yaml.safe_load解析，字段合并时frontmatter 优先于目录推断；
• 分类判定：分类优先级为 frontmatter 显式category→ 目录结构推断 → 关键词打分推断（infer_category对 16 类规则与 family 前缀规则打分，低于阈值或得分接近时保守地返回uncategorized）→ 最后用CURATED_CATEGORY_OVERRIDES人工覆盖表修正；
• 重复 id 防护：生成完成后检查重复id，存在冲突直接抛ValueError终止生成，避免索引中出现歧义条目；
• 兼容镜像：mirror_canonical_index()会把根目录skills_index.json镜像复制到data/skills_index.json，供兼容性消费者使用。

这些细节解释了为什么"干净检出 + 权威源"是必要条件：任何对skills/源文件的损坏、重复 id 或缺失 frontmatter，都会在生成阶段暴露出来。

Windows 启动器：START_APP.bat 的职责边界

仓库根目录的 START_APP.bat 是 Windows 下的一键启动入口。从批处理源码看，它的实际行为是：

1. 用WHERE node检查 Node.js 是否安装，未安装则报错退出；
2. 进入apps/web-app检查node_modules是否存在；不存在则执行npm install并额外安装@supabase/supabase-js；若npx vite --version探测失败（依赖损坏）则删除node_modules重装；
3. 回到仓库根目录执行npm run app:setup准备技能数据；
4. 进入apps/web-app用npx -y vite --open启动并自动打开浏览器。

需要特别强调的是启动器的职责边界（这正是原文档警告的部分）：它不会执行 Git 拉取更新、不会通过 PowerShell 下载技能、也不会自动安装 Python。因此必须先手动准备好检出与前置依赖（Node ≥ 22、Python +pyyaml>=6.0），再运行启动器。对于可复现的依赖安装，仍然优先使用上文推荐的 npm 命令（npm ci、npm run app:install），而非启动器内部的npm install。

维护者注意事项：生成差异、受保护工作流与发布边界

生成差异不要混入普通源码 PR

更新本地目录后，git status会看到一批生成的派生文件（如skills_index.json、data/*.json等）。这些生成差异应作为证据供审查，但不应包含在普通源码 PR 中。这是本仓库的 PR 约定：PR 只提交源码变更，CI 会把生成产物编辑直接拦截并仅以信息性预览的形式报告漂移（详见 ci-drift-fix.md）。

源码合并后使用受保护的 canonical-sync 工作流

源码合并进main之后，应使用受保护的 canonical-sync 工作流 来发布生成产物，而不是手工提交。该工作流要求：

• main推送后 CI 对漂移是严格失败的，仓库必须与生成管线实际产出完全一致；
• 修复漂移时运行npm run sync:repo-state做本地规范同步，检查git status/git diff；
• 若只产生规范生成变更，交由受信任的main工作流以automation/canonical-repo-state机器人身份、指定分支与完全可复现的树来发布；不要创建普通的人工生成修复 PR；
• 若同步后仍有无关或不受管控的漂移，必须停下排查，机器人只允许发布规范/生成子集。

刷新本地目录 ≠ 发布

最后记住刷新本地目录的四条边界：

1. 不更新已安装的技能副本（installed skill copies）；
2. 不发布 npm 包；
3. 不部署 Pages 站点；
4. 不拉取上游新技能——索引只反映当前检出skills/中已接受的内容。

需要向他人分发或部署时，走仓库既有的发布流程（如 package.json 中的release:publish等脚本），而不是依赖本地目录刷新命令。

小结：一张刷新决策表

在干净检出上按"前置依赖 →npm run build→npm run app:dev"的顺序执行，即可获得与权威源完全一致的本地技能目录；把生成差异留给受保护的同步工作流，就能在享受本地检索能力的同时，保持main分支的清洁与可复现。

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills