Recommendations【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2uiP0:Pin Module Blueprint CommitsDetailed explanation for item 1.P1:Fix Broken Relative Documentation LinksDetailed explanation for item 2.P2:Remediate Swift Core Blueprint ConfigurationDetailed explanation for item 3.测试用例还覆盖了 ## Recommendations 区段被其他 ## 标题或 --- 分隔符终止、嵌套代码围栏内的伪推荐项过滤等边界情况。 ### 3.4 场景 B通用 Issue 如果报告正文中没有可解析的 ## Recommendations 区段脚本返回 type: general_issue直接将 Issue 的标题与正文作为待修复的问题陈述。对应测试用例为 [Bug report: The parser fails on nested JSON arrays.](https://link.gitcode.com/i/d08230fb778e5b507378b4c32fc6021d)。 ### 3.5 阅读审计上下文 在拿到推荐项正文后还应回到合规报告的 ## Codebase Blueprint Compliance Audit、## Code Documentation Sync Audit、## Test Quality Assertions Audit 等审计区段阅读与该推荐项相关的详细发现具体文件路径、函数名、参数不匹配或弱断言示例为 Step 2 的修复提供精确依据。 --- ## 4. Step 2制定并实施最小化修复 1. **定位受影响文件**根据 Issue 或推荐项中引用的文件与代码库确定改动范围 2. **审阅现状**仔细检查相关源码、文档或蓝图blueprint文件 3. **实施最小必要改动**这是本技能强调的 **CRITICAL RULE关键规则**——**不得在目标 Issue/推荐项范围之外做任何无关改动、重构或格式调整**。审计报告中的推荐项本身就是具体、自包含的修复任务因此修复应当精准、收敛 4. **格式化与风格合规**执行仓库根目录下的 [scripts/fix_format.sh](https://link.gitcode.com/i/ad26ada6b6130e2a105b1ed9031fdd70) bash ./scripts/fix_format.sh该脚本覆盖仓库的全语言栈Node/Web 资产走 Prettieryarn format:all或yarn dlx prettier3.8.4 --config .prettierrc --write .、Python 走 Pyinkuv run pyink .、Dart 走dart format、Swift 走swift-format、Kotlin 走 ktfmt通过 Gradle。支持--check参数做只读校验CI 场景便于在提交前确认无格式回归 5.运行受影响包的本地测试如果修改了测试或脚本需要在受影响的包上执行本地测试确保未引入回归。5. Step 3选择落地方式并创建分支技能建议先与用户确认改动的落地位置与分支名优先使用ask_question或等价交互工具推荐分支名合规推荐项使用remediation/issue-${ISSUE_NUMBER}-${RECOMMENDATION_INDEX}通用 Issue 使用remediation/issue-${ISSUE_NUMBER}落地方式三选一使用独立的 git worktree遵循用户本地 worktree 习惯、在当前目录检出新分支、或原地直接应用改动确保工作区干净且与upstream/main同步避免基于过期基线提交。确定后将分支名记入BRANCH_NAME变量供后续步骤使用。6. Step 4提交改动暂存修改git add -u创建引用 Issue 编号的 Conventional Commits 提交合规推荐项git commit -m fix(compliance): remediate issue #${ISSUE_NUMBER} recommendation ${RECOMMENDATION_INDEX}通用 Issuegit commit -m fix(scope): remediate issue #${ISSUE_NUMBER} - ${CONCISE_SUMMARY}注意这里的提交信息允许包含 Issue 编号这与 PR 标题禁止出现通用编号的约束见第 8 节正好互补——Issue 引用信息在提交信息与 PR 正文中体现而 PR 标题保持面向读者。7. Step 5创建 Pull Request 并通知 Issue按需执行此步骤是可选/按请求执行的技能建议先与用户确认是否提交 PR优先使用ask_question推荐默认以Draft PR--draft提交让 CI 先跑完检查同时保留最终审查余地也可选择直接提交为 ready-for-review或先跳过 PR 创建以便用户本地检查改动编写 PR 标题遵循 Conventional Commits用一句精炼的话描述具体修复内容例如fix(swift): create missing top-level README in swift/core。禁止在 PR 标题中包含通用 Issue/推荐项编号起草 PR 描述将描述写入临时文件pr_description.md结构遵循.agents/skills/a2ui-remediate-problem/references/pr-description-template.md详见第 8 节推送并创建 PRgit push -u origin ${BRANCH_NAME} PR_URL$(gh pr create --draft \ --repo a2ui-project/a2ui \ --head ${BRANCH_NAME} \ --base main \ --title ${PR_TITLE} \ --body-file pr_description.md)说明若用户希望立即进入可审查状态省略--draft若从 fork 推送gh pr create会自动解析 fork 的 head 分支或可显式传入--head username:${BRANCH_NAME} 5.清理临时文件删除pr_description.md 6.在原 Issue 上评论通知维护者gh issue comment ${ISSUE_NUMBER} \ --repo a2ui-project/a2ui \ --body Automated remediation triggered! Created PR (${PR_URL}) on branch \${BRANCH_NAME}\ to address recommendation ${RECOMMENDATION_INDEX}.8. PR 描述规范让审查者一眼看懂为什么.agents/skills/a2ui-remediate-problem/references/pr-description-template.md定义了修复 Agent 生成 PR 描述的强制规范共三层8.1 PR 标题三原则描述性且可执行标题必须清楚描述具体修复内容如fix(swift): create missing top-level README in swift/core或docs(spec): sync component schema with core typesConventional Commits 格式type(scope): concise summary不含通用编号不要把issue #2178 recommendation 3这类编号写进 PR 标题——Issue 引用只出现在 PR 正文中。8.2 写作指南聚焦意图Why而非机制How说明合规报告中要解决什么问题、为什么该代码/文档改动能解决它客观平实避免夸张措辞与空话简洁、客观地陈述改动Markdown 规范文件路径、CLI 命令、变量名与符号用反引号包裹如agent_sdks/python/a2ui_agent正文中引用合规报告 Issue如Addresses #2178若#引用并非要生成 GitHub Issue 链接应用反引号包裹。8.3 强制 PR 描述结构## Summary [1-2 句话概述修复引用原合规报告 Issue 与推荐项索引如 Addresses recommendation 3 from compliance report issue #2178 by creating swift/core/README.md.] ## Changes - [列出新增、修改或删除的具体文件] - [主要代码、蓝图或文档改动的概述] ## Impact Risks - [潜在的副作用、公共 API 变更或依赖影响若无声明 No breaking changes or external dependency impacts] ## Testing - [分步列出执行的验证检查如单元测试运行、linter 输出、静态检查] --- ### How to Inspect or Modify This Branch Locally bash gh pr checkout PR_NUMBER git commit -am fix: additional adjustments for recommendation ${RECOMMENDATION_INDEX} git push四段式结构Summary / Changes / Impact Risks / Testing加上本地检视分支指引保证了审查者无需追问即可获得完整上下文。 --- ## 9. 贯穿全流程的 GitHub CLI 参考 技能在抓取 Issue、创建 PR、评论 Issue 等环节重度依赖 gh CLI。完整命令速查见 [.agents/skills/a2ui-audit/references/gh-reference.md](https://link.gitcode.com/i/b8b747abd8d00e1ef8df47fc53295643)其中与修复流程最相关的几组命令 - **认证与默认仓库**gh auth status 检查登录状态gh repo set-default 设置默认仓库以省略 --repo 参数 - **Issue 操作**gh issue view 123 / gh issue view 123 --comments 读取 Issue 与讨论gh issue comment 123 --body ... 发布通知评论 - **PR 操作**gh pr create --draft 创建草稿 PRgh pr checkout 123 检出 PR 分支gh pr checks 123 查看 CI 状态 - **CI 监控**gh run list、gh run view 123456 --log 可诊断提交后 CI 失败。 一个重要的环境细节如果 GITHUB_TOKEN 环境变量是 dummy 值使用 gh 命令前需以 env -u GITHUB_TOKEN 前缀取消该环境变量例如 env -u GITHUB_TOKEN gh auth status若 token 看起来是有效 token 则不要这样做。该约定同时适用于 gh issue view 与 gh pr create 等全部命令。 --- ## 10. 从源码看解析器设计为何它能稳健处理真实报告 extract_recommendation.py 的测试用例[test_extract_recommendation.py](https://link.gitcode.com/i/3004f921d20394a9c012b19a8c25ffd4)揭示了真实审计报告中的若干棘手形态与对应解法 - **## Recommendations 区段的起止判定**区段以 ## Recommendations 开始遇到下一个 ## 标题或 --- 分隔线结束[parse_recommendations](https://link.gitcode.com/i/b601e6e14f9d4bd3d45679c8f5ace36c) - **嵌套代码围栏**test_parse_recommendations_with_nested_code_blocks 验证了报告推荐项内嵌 markdown【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Recommendations
Recommendations【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2uiP0:Pin Module Blueprint CommitsDetailed explanation for item 1.P1:Fix Broken Relative Documentation LinksDetailed explanation for item 2.P2:Remediate Swift Core Blueprint ConfigurationDetailed explanation for item 3.测试用例还覆盖了 ## Recommendations 区段被其他 ## 标题或 --- 分隔符终止、嵌套代码围栏内的伪推荐项过滤等边界情况。 ### 3.4 场景 B通用 Issue 如果报告正文中没有可解析的 ## Recommendations 区段脚本返回 type: general_issue直接将 Issue 的标题与正文作为待修复的问题陈述。对应测试用例为 [Bug report: The parser fails on nested JSON arrays.](https://link.gitcode.com/i/d08230fb778e5b507378b4c32fc6021d)。 ### 3.5 阅读审计上下文 在拿到推荐项正文后还应回到合规报告的 ## Codebase Blueprint Compliance Audit、## Code Documentation Sync Audit、## Test Quality Assertions Audit 等审计区段阅读与该推荐项相关的详细发现具体文件路径、函数名、参数不匹配或弱断言示例为 Step 2 的修复提供精确依据。 --- ## 4. Step 2制定并实施最小化修复 1. **定位受影响文件**根据 Issue 或推荐项中引用的文件与代码库确定改动范围 2. **审阅现状**仔细检查相关源码、文档或蓝图blueprint文件 3. **实施最小必要改动**这是本技能强调的 **CRITICAL RULE关键规则**——**不得在目标 Issue/推荐项范围之外做任何无关改动、重构或格式调整**。审计报告中的推荐项本身就是具体、自包含的修复任务因此修复应当精准、收敛 4. **格式化与风格合规**执行仓库根目录下的 [scripts/fix_format.sh](https://link.gitcode.com/i/ad26ada6b6130e2a105b1ed9031fdd70) bash ./scripts/fix_format.sh该脚本覆盖仓库的全语言栈Node/Web 资产走 Prettieryarn format:all或yarn dlx prettier3.8.4 --config .prettierrc --write .、Python 走 Pyinkuv run pyink .、Dart 走dart format、Swift 走swift-format、Kotlin 走 ktfmt通过 Gradle。支持--check参数做只读校验CI 场景便于在提交前确认无格式回归 5.运行受影响包的本地测试如果修改了测试或脚本需要在受影响的包上执行本地测试确保未引入回归。5. Step 3选择落地方式并创建分支技能建议先与用户确认改动的落地位置与分支名优先使用ask_question或等价交互工具推荐分支名合规推荐项使用remediation/issue-${ISSUE_NUMBER}-${RECOMMENDATION_INDEX}通用 Issue 使用remediation/issue-${ISSUE_NUMBER}落地方式三选一使用独立的 git worktree遵循用户本地 worktree 习惯、在当前目录检出新分支、或原地直接应用改动确保工作区干净且与upstream/main同步避免基于过期基线提交。确定后将分支名记入BRANCH_NAME变量供后续步骤使用。6. Step 4提交改动暂存修改git add -u创建引用 Issue 编号的 Conventional Commits 提交合规推荐项git commit -m fix(compliance): remediate issue #${ISSUE_NUMBER} recommendation ${RECOMMENDATION_INDEX}通用 Issuegit commit -m fix(scope): remediate issue #${ISSUE_NUMBER} - ${CONCISE_SUMMARY}注意这里的提交信息允许包含 Issue 编号这与 PR 标题禁止出现通用编号的约束见第 8 节正好互补——Issue 引用信息在提交信息与 PR 正文中体现而 PR 标题保持面向读者。7. Step 5创建 Pull Request 并通知 Issue按需执行此步骤是可选/按请求执行的技能建议先与用户确认是否提交 PR优先使用ask_question推荐默认以Draft PR--draft提交让 CI 先跑完检查同时保留最终审查余地也可选择直接提交为 ready-for-review或先跳过 PR 创建以便用户本地检查改动编写 PR 标题遵循 Conventional Commits用一句精炼的话描述具体修复内容例如fix(swift): create missing top-level README in swift/core。禁止在 PR 标题中包含通用 Issue/推荐项编号起草 PR 描述将描述写入临时文件pr_description.md结构遵循.agents/skills/a2ui-remediate-problem/references/pr-description-template.md详见第 8 节推送并创建 PRgit push -u origin ${BRANCH_NAME} PR_URL$(gh pr create --draft \ --repo a2ui-project/a2ui \ --head ${BRANCH_NAME} \ --base main \ --title ${PR_TITLE} \ --body-file pr_description.md)说明若用户希望立即进入可审查状态省略--draft若从 fork 推送gh pr create会自动解析 fork 的 head 分支或可显式传入--head username:${BRANCH_NAME} 5.清理临时文件删除pr_description.md 6.在原 Issue 上评论通知维护者gh issue comment ${ISSUE_NUMBER} \ --repo a2ui-project/a2ui \ --body Automated remediation triggered! Created PR (${PR_URL}) on branch \${BRANCH_NAME}\ to address recommendation ${RECOMMENDATION_INDEX}.8. PR 描述规范让审查者一眼看懂为什么.agents/skills/a2ui-remediate-problem/references/pr-description-template.md定义了修复 Agent 生成 PR 描述的强制规范共三层8.1 PR 标题三原则描述性且可执行标题必须清楚描述具体修复内容如fix(swift): create missing top-level README in swift/core或docs(spec): sync component schema with core typesConventional Commits 格式type(scope): concise summary不含通用编号不要把issue #2178 recommendation 3这类编号写进 PR 标题——Issue 引用只出现在 PR 正文中。8.2 写作指南聚焦意图Why而非机制How说明合规报告中要解决什么问题、为什么该代码/文档改动能解决它客观平实避免夸张措辞与空话简洁、客观地陈述改动Markdown 规范文件路径、CLI 命令、变量名与符号用反引号包裹如agent_sdks/python/a2ui_agent正文中引用合规报告 Issue如Addresses #2178若#引用并非要生成 GitHub Issue 链接应用反引号包裹。8.3 强制 PR 描述结构## Summary [1-2 句话概述修复引用原合规报告 Issue 与推荐项索引如 Addresses recommendation 3 from compliance report issue #2178 by creating swift/core/README.md.] ## Changes - [列出新增、修改或删除的具体文件] - [主要代码、蓝图或文档改动的概述] ## Impact Risks - [潜在的副作用、公共 API 变更或依赖影响若无声明 No breaking changes or external dependency impacts] ## Testing - [分步列出执行的验证检查如单元测试运行、linter 输出、静态检查] --- ### How to Inspect or Modify This Branch Locally bash gh pr checkout PR_NUMBER git commit -am fix: additional adjustments for recommendation ${RECOMMENDATION_INDEX} git push四段式结构Summary / Changes / Impact Risks / Testing加上本地检视分支指引保证了审查者无需追问即可获得完整上下文。 --- ## 9. 贯穿全流程的 GitHub CLI 参考 技能在抓取 Issue、创建 PR、评论 Issue 等环节重度依赖 gh CLI。完整命令速查见 [.agents/skills/a2ui-audit/references/gh-reference.md](https://link.gitcode.com/i/b8b747abd8d00e1ef8df47fc53295643)其中与修复流程最相关的几组命令 - **认证与默认仓库**gh auth status 检查登录状态gh repo set-default 设置默认仓库以省略 --repo 参数 - **Issue 操作**gh issue view 123 / gh issue view 123 --comments 读取 Issue 与讨论gh issue comment 123 --body ... 发布通知评论 - **PR 操作**gh pr create --draft 创建草稿 PRgh pr checkout 123 检出 PR 分支gh pr checks 123 查看 CI 状态 - **CI 监控**gh run list、gh run view 123456 --log 可诊断提交后 CI 失败。 一个重要的环境细节如果 GITHUB_TOKEN 环境变量是 dummy 值使用 gh 命令前需以 env -u GITHUB_TOKEN 前缀取消该环境变量例如 env -u GITHUB_TOKEN gh auth status若 token 看起来是有效 token 则不要这样做。该约定同时适用于 gh issue view 与 gh pr create 等全部命令。 --- ## 10. 从源码看解析器设计为何它能稳健处理真实报告 extract_recommendation.py 的测试用例[test_extract_recommendation.py](https://link.gitcode.com/i/3004f921d20394a9c012b19a8c25ffd4)揭示了真实审计报告中的若干棘手形态与对应解法 - **## Recommendations 区段的起止判定**区段以 ## Recommendations 开始遇到下一个 ## 标题或 --- 分隔线结束[parse_recommendations](https://link.gitcode.com/i/b601e6e14f9d4bd3d45679c8f5ace36c) - **嵌套代码围栏**test_parse_recommendations_with_nested_code_blocks 验证了报告推荐项内嵌 markdown【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考