SuperAPI AI 工具集

standards-map

部署与运维

查看项目

更新于 10-16 06:07

技能介绍

Standards Map 是一个只读的对照分析技能,用于回答三个问题:项目对照最新 TheFocus.AI 标准处于什么状态?哪些最佳实践指南适用、部分适用或不适用,原因是什么?哪些是有意的产品例外,哪些是合规缺口?默认不会修改项目;如需迁移方案或实际修复,应在报告完成后交给 standardize-project。

用途与定位 它把“最新标准”与“目标项目现状”做一次带日期的快照式映射。报告中会按用途、主要能力、使用方式、适用场景和限制分段,并且区分 Meets、Exception、Soft gap、Gap、N/A 五类结论,避免把产品决策误判为技术债。

目标项目解析 先解析目标:优先使用用户指定的路径(绝对或相对);否则在看起来像项目(含 AGENTS.md、mise.toml、package.json 或 .git)的当前工作目录中查找;再否则询问并停止。所有读取都使用显式路径,避免在标准仓库与相邻项目之间误写。

标准来源与版本固定 标准来自 The-Focus-AI/standards。报告必须固定到具体版本(commit SHA + 日期),而不是凭记忆。解析顺序:STANDARDS_REPO 环境变量(且路径含 best-practices/GDE-009-technology-defaults.md);目标项目附近的 ../standards 或 ../../standards;$HOME/The-Focus-AI/standards;用户指定路径;否则从 GitHub 最新 main 获取(可用 gh api 取 SHA,或浅克隆到临时目录)。网络或认证失败时应说明并停止,不得凭模型记忆编造标准。报告需记录所用绝对路径或 github:The-Focus-AI/standards@<sha>、提交 SHA 与提交日期,以及本地克隆是否可能落后于 origin/main。

需读取的标准内容 必读:AGENTS.md(根导航与审计顺序)、best-practices/GDE-009-technology-defaults.md(mise、tasks、pnpm/TS 默认、fnox、skills 安装)、best-practices/GDE-008-skills.md(规范技能集与规划工作流)、STD-007 与 best-practices/GDE-003-fnox-secrets.md(机密与凭据)、STD-008 与 best-practices/GDE-006-local-environment.md(部署与本地环境)、best-practices/GDE-007-pi-extensions.md、标准仓库内的默认项目模板(仅作参考)、根 skills-lock.json(用于差异比对)。条件读取:Vercel/Next 相关看 GDE-010;Cloud Run/App Engine/gcloud 看 GDE-005;Gaia/habitats/GCE 代理集群看 GDE-004;Clerk/用户认证看 GDE-002;A2A/MCP 代理服务看 GDE-001。即使不适用,报告也需在 N/A 下列出这些指南并给出一行原因。

目标项目检查顺序 按标准审计顺序进行:代理指令(AGENTS.md、CLAUDE.md、.cursor/rules 等);工具链(mise.toml、包管理器文件、锁文件、脚本/任务);机密(fnox.toml、.fnox/ 是否存在,不读内容、.env* 风险、gitignore);pi(.pi/settings.json、所需包与 pi-extensions.md);技能(skills-lock.json 与标准锁/skills.md 对比,检查缺失、已弃用的 to-prd/to-issues、标题大小写键、错误来源);工作流(README、docs/agents/issue-workflow.md、任务追踪器、wayfinder 文档);部署形态(Dockerfile、Vercel、GH Actions、Pages、Cloud Run 或无);产品栈(语言、是否构建、认证、数据库、托管);Git 卫生(.gitignore、已提交机密风险、生成目录)。应收集具体证据(任务名、文件路径、技能数量),优先使用 mise 任务、读取文件和锁文件键,不打印机密值,只记录键名。

报告内容结构 报告优先写到目标项目的 reports/YYYY-MM-DD-standards-map.md,使用真实当天日期,必要时创建 reports/ 目录;若用户要求仅输出到 stdout 或不同路径则遵从,但仍可提供写文件选项。报告骨架包含:头部元数据(标题、日期、项目、标准来源、SHA、提交日期、模式为 map);产品一句话概述(What、Stack、Host、Backend、Org remote);标准版本说明;评分卡(工具链、机密、代理指令、技能锁、pi、工作流文档、部署、应用栈与默认值对比);标准面到项目文件的映射表;必需 mise 任务表(install、dev、lint、test、deploy、setup/secrets:*);指南逐项适用性(核心、条件适用、今日不适用及原因);技能映射表(Focus 自有、第三方、mattpocock 集);架构与默认栈对比(TypeScript、构建流水线、Neon/Postgres、Clerk、Vercel 等);按工作类型的路由表;软缺口与缺口优先级列表;可选心智模型图;建议下一步。若项目 AGENTS.md 与标准默认冲突,应指出冲突,不得默默以标准覆盖产品规则;写明的例外归入 Exception,未记录的漂移归入 Gap。

交付与提醒 交付后应在对话中总结:产品一句话、评分卡要点、主要缺口/例外、报告路径、所用标准 SHA,并在存在缺口时询问是否需要 standardize-project 收口。可选模式有:默认映射报告、技能差异模式(强调锁文件键/来源/哈希漂移)、仅指南模式(不列完整文件清单的适用性矩阵)、双项目对比模式(共享同一标准 SHA 的并排评分卡)。仍应生成带日期的报告,除非用户禁止写文件。

限制与注意事项 该技能只做映射,不做迁移;不得编造标准,必须解析真实标准树与 SHA;不得把有意的 vanilla JS/无构建/静态 Pages 等文档化选择当作缺口,应标记为 N/A 或 Exception;不得输出机密值,只写名称;不得对纯客户端静态 PWA 把 Vercel/Clerk/GCP 标为缺口;本地标准克隆可能过期,应注明相对 origin/main 的状态,无法检查时说明报告仅基于本地树;在 The-Focus-AI/ 下标准与项目并排时,目标路径必须保持显式,避免误改仓库。