SCzhengand修雨
809d026b7e
* ci(interface): 添加接口完整性和CLI烟雾测试检查 - 在Makefile中新增interface-integrity、update-interface-baseline、cli-smoke和mock-mcp-smoke目标 - 实现接口基线脚本以比较CLI公共命令树与基线文件 - 新增脚本确保二进制文件可渲染所有顶层命令的帮助信息 - 添加mock-mcp-smoke测试验证HTTP和stdio MCP请求/响应传输 - 在GitHub Actions CI工作流中加入interface-integrity、cli-smoke和mock-mcp-smoke检查 - 新增AI行为检查工作流，限制AI生成PR的改动范围和禁改保护文件 - 文档中补充PR质量门禁要求及接口变更流程说明 * feat(policy): 增加多项兼容性和完整性检查 - Makefile中新增reset-interface-baseline、schema-compatibility、update-schema-baseline、skill-command-integrity等目标 - CI流程新增schema-compatibility和skill-command-integrity步骤 - 文档中详细说明接口兼容性基线更新和重置流程及schema基线注意事项 - 实现interface-baseline工具支持兼容性重置和合并，多项接口兼容性检查逻辑完善 - 新增schema-compat工具用于标准化schema列表及兼容性检查与合并 - 新增skill-command-integrity检查确保技能中引用命令存在 - 为interface-baseline和schema-compat添加单元测试覆盖基本兼容性规则 * test(skill-command-check): 增加命令解析和解析结果测试用例 - 补充对 parseReference 函数的边界情况和跳过条件的测试 - 新增 resolveCommandReference 函数测试，覆盖有效、无效及跳过场景 - 增加 isPlaceholder 函数的测试，验证占位符识别准确性 refactor(skill-command-check): 优化命令路径解析和验证逻辑 - 使用 resolveCommandReference 统一处理命令解析结果，清晰区分有效、无效和跳过情况 - 新增 commandResolution 类型及常量，提升代码可读性和扩展性 - 调整 parseReference 增加对 shell 组合符 “ & ” 的跳过处理 docs(mono): 更新最佳实践和产品文档命令示例 - 优化《best_practices/07-minutes.md》中行动项与摘要拉取示例命令，提升准确性 - 修改产品文档中 ALIDOC 表格数据和多维表格记录相关命令，命令路径更规范统一 - 同步多端技能文档，确保命令示例一致且正确 * ci: check interface against PR merge-base * feat(policy): enforce CLI contract compatibility * ci: enforce PR coverage thresholds * ci: add fail-closed CI gate * ci: adapt schema compatibility gate to runtime catalog * fix(ci): close schema compatibility gate gaps * test(auth): skip POSIX mode assertion on Windows * test(auth): scope POSIX file-backend checks * fix(ci): enforce native platform coverage * test(ci): make skill paths portable --------- Co-authored-by: 修雨 <huyizhou.hyz@alibaba-inc.com>
4.4 KiB
Pull request quality gates
The repository defines five focused checks in addition to its existing CI:
- Interface Integrity enforces backwards compatibility. Every historical
command path and alias must still resolve, every historical command must
still render
-h, and historical flags must keep their type and shorthand. New commands, aliases, and flags are allowed. The same job compares the full completedws schema --allcontract with the PR merge-base, blocking removed products/tools/parameters, incompatible parameter or interface mappings, constraint drift, and safety-semantic drift. It also checks that executabledws ...references inskills/**/*.mdresolve to real commands. Help compatibility covers command/alias/flag spelling, flag type and shorthand; descriptive prose may evolve without breaking the gate. - Coverage runs unit tests on every pull request and prints both overall and
changed-code statement coverage. During the migration to the 80% repository
target, overall coverage may not regress from a profile generated from the
merge-base with the same test command, while changed production Go
statements must meet 80%. Linux, Windows, and macOS each generate a native
coverage profile for changed packages and enforce the threshold against
changed files buildable on that platform, so build-tagged source cannot be
hidden by an Ubuntu-only profile. Overall non-regression allows 0.1 percentage point of measurement
variance to avoid failing unchanged code on test-path noise. Set
COVERAGE_ENFORCE_OVERALL=trueonce repository coverage reaches 80% to make the overall target fail closed as well. - CLI Smoke builds the release binary and renders offline help for the root and every public top-level command.
- Mock MCP Smoke runs the existing HTTP and stdio MCP lifecycle tests
(
Initialize -> ListTools -> CallTool). - AI Behavior Check applies to pull requests labeled
ai-generated. It limits the change to 30 files and blocks release/CI infrastructure changes. It usespull_request_targetwithout checking out PR code, so the policy cannot be bypassed by changing the workflow in the same pull request. The evaluator writes anAI Behavior Checkcommit status to the PR head SHA so GitHub rulesets can require it.
Running the compatibility gates
Run:
make build
make interface-integrity
make authoritative-interface-integrity BASE_REF=<merge-base>
make schema-compatibility BASE_REF=<merge-base>
make skill-command-integrity
make cli-smoke
make coverage-gate BASE_REF=<merge-base>
# Run on the corresponding native runner with its generated profile:
make coverage-gate-platform BASE_REF=<merge-base> PROFILE=<coverage-profile>
CI derives the authoritative Interface snapshots from both the PR merge-base
and the latest reachable stable release tag. The complete Schema snapshot comes
from the PR merge-base, which contains the registry-first Schema introduced on
main. The candidate branch cannot bless a breaking change by editing a
fixture. Schema additions are allowed; historical products, tools, parameters,
parameter mappings, positional execution fields, constraints, and safety
semantics remain protected. Positional descriptions are documentation and may
change without breaking compatibility.
make update-interface-baseline still extends the local checked-in Interface
fixture used by make interface-integrity. Updates are monotonic: they add new
commands and flags without removing history.
For an intentional compatibility reset at a major-version boundary, run
make reset-interface-baseline. This replaces all CLI compatibility history
with the current command tree and must receive explicit human review.
Required GitHub repository settings
Create a ruleset for main that requires pull requests and code-owner review,
then mark these aggregate status checks as required:
CI GateMulti Profile E2EAI Behavior Check
CI Gate fails closed unless every first-layer CI job succeeds, including
lint, tests, native Linux/Windows/macOS coverage, policy,
Interface/Schema/Skill integrity, and smoke tests. Requiring the aggregate
check keeps repository rules stable when an internal job is renamed or split.
The ai-generated label must be applied by the PR-creation automation or by a
maintainer; GitHub cannot infer reliably whether a human-authored PR contains
AI-generated code.