核心用法
该skill通过执行Python脚本,对指定阿里云产品进行端到端的文档与API质量审查。用户只需提供产品名称或产品代码(如"ECS"),脚本即可自动完成以下流程:
1. 产品解析:从最新OpenAPI元数据解析目标产品
2. 文档采集:获取默认版本的API文档,并从官方产品页面发现帮助文档链接
3. 质量评估:基于内置评审标准生成结构化报告
显著优点
- 自动化程度高:一键运行,无需人工遍历多个文档入口
- 输出结构化:生成JSON证据文件与Markdown报告,包含量化评分、证据引用和优先级建议
- 可复现性强:证据文件包含关键参数(地域/资源ID/时间范围),便于审计追溯
- 评审标准明确:引用独立的
review-rubric.md作为评分依据,减少主观偏差
潜在缺点与局限性
- 依赖外部元数据:若阿里云OpenAPI元数据更新延迟或结构变更,可能影响产品解析准确性
- 网络与权限依赖:需配置阿里云凭证(AccessKey),且受目标产品文档站点可访问性制约
- 评分标准固定:当前采用单一rubric,可能无法覆盖特定行业的合规要求
- 脚本维护成本:Python脚本需随阿里云文档结构调整持续更新
适合人群
- 阿里云产品经理与技术文档工程师
- 负责API治理与开发者体验的工程团队
- 需要定期审计多产品文档质量的企业架构师
常规风险
- 凭证泄露风险:需在执行前配置
ALICLOUD_ACCESS_KEY_ID等环境变量,建议使用最小权限原则 - 数据残留:输出目录
output/alicloud-platform-docs-api-review/可能包含敏感产品信息,需定期清理 - 误评风险:自动化评分可能遗漏语境相关的语义问题,建议关键产品结合人工复核