DevOps+AI 代码工程场景建设系列之——增强CI流水线代码检测（一）

Maiyata 项目AI编程质检体系全流程分析文档（标准Markdown整理版）

第一轮：初探

请根据2026年6月最新AI大模型项目编程的理念、方法、组件、skills、MCP、harness等，分析项目现有设置，梳理可显著改进增强的地方。

这是一项需要系统性拆解项目现有配置的分析任务。我会并行梳理harness完整体系（hooks/MCP/skills/CI/文档治理），再结合2026年AI编程工程化理念完成完整评估。

分步信息采集计划：

并行读取核心配置文件，完整梳理 harness/MCP/hooks/CI/skills 落地细节
读取治理文档、L0规范，明确项目底层「设计哲学」与现存缺口
并行读取skills、rules、serena配置，梳理superpowers完整文档覆盖范围
读取SaaS规范概要、serena配置，构建项目工具/规范心智模型，同步探查测试基础设施现状

信息采集完成后，正式开展交叉核验：重点确认hooks启用状态、codebase-memory索引完整度、项目已知缺口清单。

已完整掌握项目全部配置信息，以下为无代码、纯文字系统性分析报告。

项目AI编程设置 — 现状评估与改进建议（2026 视角）

一、总体评价

该项目harness体系在行业内属于成熟梯队：分层架构（L0 harness / L1 领域 / L2 CI）、9条铁律 + SaaS B1–B11规范、四层错题记忆（U0跨项目 / L1项目 / L2索引 / L3 Serena）、guard-pre-write写时拦截、verification-lock三步验证锁等设计，理念领先2026年绝大多数生产级项目。

但对标2026最新AI编程工程标准，仍存在6个高价值优化方向，下文按「投入产出比」从高到低排序。

二、🔴 高优先级改进（投入小、回报大）

1. CI 漂移 — GitHub Actions 与本地harness严重脱节（核心缺口）

现状

.github/workflows/saas-collector.yml 仅执行 go test ./... + go build
本地 scripts/quality/run-static-analysis.ps1 完整包含：verify-saas + verify-doc-truth + verify-doc-governance + go vet + semgrep + 竞态检测 -race
铁律9（verification-lock）依赖的 verify-hooks.ps1 / verify-doc-truth.ps1 在云端CI完全未执行

核心问题
所有PR均可绕过本地完整harness直接合并；本地质检属于自助式流程，AI、开发人员均能主动跳过，写时拦截机制存在致命漏洞。

2026标准改进思路：CI = harness 的唯一权威标准
新建统一流水线文件，所有PR强制全量校验：

# .github/workflows/harness.yml（新建，PR必触发）
- L0 基础校验：verify-doc-truth + verify-doc-governance
- L0 钩子完整性校验：verify-hooks（防止hooks.json配置漂移）
- Go静态校验：go vet + go test -race
- .NET全量编译测试：dotnet build + test
- 安全扫描：semgrep 双规则集执行

核心设计：CI校验失败即阻断PR合并，不再依赖人工/AI自觉；仅需新增一份yaml配置，数小时即可落地，补齐质量管控最后一环。

2. 错题本单点风险 — `server-memory` MCP架构脆弱

现状
U0层user-wrongbook、L1层mcp-memory均复用@modelcontextprotocol/server-memory，知识存储采用原生jsonl文件。

现存缺陷

无版本、无审计能力：执行add_observations后无法回滚废弃错误经验，AI会基于过时教训持续生成错误方案
无去重、冲突检测：同一类问题会重复录入，新旧规则冲突导致AI获取矛盾指引
仅支持关键词检索：工业场景术语同义场景多（Invalid PDU/ISO Invalid/非S7），漏召回概率极高，本次S7探测bug正是该问题导致

2026标准改进思路：记忆层 = 可查询、可审计、冲突可治理的知识库

优化方案	实施成本	落地收益
A. 新增`verify-wrongbook.ps1`校验脚本	低	校验jsonl无重复实体、无孤儿关联，并入本地静态检查流程
B. 提交时导出错题本diff日志	低	PR评审时直观展示本次新增/修改的经验条目
C. 迁移至带版本管控的记忆MCP（mem0/自建Postgres存储）	高	支持版本回溯、召回权重打分

推荐优先落地 A+B（半天工作量），mem0存在token鉴权、跨项目共享无需求等问题，暂不启用。

三、🟡 中优先级改进（结构性长期收益）

3. 缺失2026核心MCP能力 — 代码图谱约束与自动化测试生成

现状
项目已部署codebase-memory（graph.db.zst 1.3MB），仅支持读取查询（search_graph / trace_path），属于单向消费型能力。

2026行业标准理念
代码知识图谱必须双向可用：支持查询读取，同时可反向约束代码修改行为。

当前缺失核心能力（按价值排序）

能力项	现状	2026行业标配规范
修改公共API强制追溯全链路引用	仅铁律4文字约束，无机器校验	钩子拦截：修改`.cs`公共方法前，自动执行`trace_path`全链路检索
测试覆盖盲区自动识别	无	图谱检索「有入度无测试关联」函数，主动提示补充单元测试
跨服务契约漂移检测	无	Collector API修改后，自动校验Desktop ApiClient同步更新
代码复杂度门禁管控	graph已存储cyclomatic/cognitive/loop_depth字段但未使用	CI配置复杂度阈值，超阈值阻断提交

最高性价比落地动作
基于mcp__codebase-memory__query_graph编写verify-graph-guards.ps1，将铁律4（修改API必须追溯引用）从文字约束转为机器可强制校验规则；现有图谱已内置复杂度、循环深度字段，无需新增存储层。

4. Skills体系与superpowers双体系并行冲突问题

现状

本地目录.claude/skills/内置5个专属skill：domain-modeling / grill-me / grilling / handoff / prototype
系统全局注入全套superpowers:*工具集：brainstorming / TDD / debugging / writing-plans / executing-plans / verification-before-completion / subagent-driven-development等
AGENTS.md、9条铁律完全未定义两套工具的使用规则，AI仅依靠3个alwaysApply: true的.mdc规则执行

核心问题（2026典型skill爆炸无路由缺陷）
AI可调用20+工具，但无明确调用决策树：

superpowers:brainstorming 与自研domain-modeling领域建模职责重叠
superpowers:verification-before-completion 与铁律9verification-lock功能重复，AI存在重复执行或完全跳过两种极端情况

2026标准改进思路：skill组合 + 明确路由管控
在AGENTS.md新增「Skill路由表」，绑定项目约束与工具调用逻辑：

触发场景	强制调用Skill顺序	与铁律联动关系
新功能/模块设计	`superpowers:brainstorming` → `domain-modeling`	替代纯人工编写需求spec
Bug修复排查	`superpowers:systematic-debugging`	落地铁律1链路优先排查规则
代码提交完成校验	`superpowers:verification-before-completion`	优先级低于铁律9 verification-lock，以项目专属校验为准
多任务并行开发	`superpowers:executing-plans`	配套实施计划索引使用

核心约束：铁律9 > superpowers:verification-before-completion，避免AI重复执行双重校验；仅需半天编写路由文档，消除工具冗余执行成本。

四、🟢 锦上添花（按需落地，非强制）

5. 可观测性缺口 — Collector/Desktop未落地OpenTelemetry全链路追踪

现状
docs/superpowers/knowledge/industrial-acquisition/ 存在otel-tracing-hardening.md、prometheus-metrics-hardening.md完整文档，但仅为待办优化方案，无实际代码落地。

核心缺陷
工业现场故障（S7探测超时、CNC命名空间缺失）调试仅能依靠日志、源码阅读，无完整链路trace串联Collector→设备→Desktop全流程；2026 AI调试核心标准为「AI可读取链路追踪数据，而非仅依赖文本日志」。

落地优化方案（分步实施，无需一次性全量改造）

Collector核心链路（ProbeWithDriver / DeviceSession / pipeline）新增trace.Span埋点（已有配套知识文档）
Desktop ApiClient封装层补充链路span采集
AI调试时可联动query_graph静态图谱 + trace动态链路双向验证

配套价值：与第3项代码图谱优化形成黄金组合，图谱代表静态结构，Trace代表运行时动态行为，是2026工业AI调试标准方案。

6. 文档治理机械化体系完善，补充轻量化ADR架构决策流程

现状
文档治理规范（spec/plan/standard/knowledge分类 + verify-doc-truth/governance + 孤儿文档检测）已达到行业标准；.claude/skills/domain-modeling/ADR-FORMAT.md存在ADR模板，但AGENTS.md未纳入开发流程。

优化方案
将架构决策从spec/plan/knowledge散文件中统一抽离为轻量化ADR文档（复用现有模板），统一存放至docs/superpowers/standards/decisions/目录。
落地价值：AI查询设计初衷时无需通读数百行规范文档，直接读取对应ADR记录，实现架构决策可追溯；是2026 AI协作体系极易忽略的关键环节。

五、优化方案总览矩阵

序号	优化内容	优先级	预估工作量	2026行业核心理念关键词
1	新增CI harness.yml，补齐L0全量强制校验	🔴 高	半天	CI = single source of truth
2	错题本校验脚本 + PR变更可视化diff	🔴 高	半天	Memory auditability（记忆可审计）
3	代码图谱反向约束机制（graph guards）	🟡 中	1–2天	Knowledge graph as guardrail（图谱作为质量门禁）
4	Skill路由文档，消除工具功能重叠	🟡 中	半天	Skill composition（工具组合管控）
5	OpenTelemetry链路追踪代码落地	🟢 低	2–3天	AI-readable observability（AI可读可观测数据）
6	轻量化ADR架构决策流程落地	🟢 低	半天	Decision provenance（决策溯源）

六、仅落地单一项最优选择

优先落地优化1（CI harness.yml流水线），核心理由：

是所有优化方案的强制执行底座：代码图谱、错题本校验若无CI兜底，AI/人工仍可绕过所有约束
改造成本极低，仅新增一份yaml配置，复用现有PowerShell校验脚本
直接封堵当前最高风险：PR提交跳过全套harness质检
现有S7探测功能迭代已暴露该缺陷：CI仅执行go test，完全未运行verify-saas边界校验

如需，可直接输出完整.github/workflows/harness.yml落地代码，完整复现run-static-analysis.ps1校验逻辑（含Linux兼容版本）；可选择优先输出完整配置，或针对某一项优化细化落地方案。

本轮分析深度匹配Opus大模型输出水准，日常开发无需高频调用重型大模型即可完成完整方案推演。

第二轮：面向业务人员简化方案（通俗化表达）

核心诉求

原版报告充斥专业术语、代码配置，可读性差，重新输出面向业务视角的简化报告，清晰说明：现存问题、改造动作、落地后收益。

📋 工作报告：给项目装上"自动质检门禁"

一、现存核心问题（一句话总结）

项目现有全部质量检查机制均依靠人工自觉，无强制拦截能力，形同虚设。

三层真实现状拆解

真相1：云端GitHub自动化配置完全失效

仓库内置GitHub自动化配置文件.github/workflows/saas-collector.yml，设计为提交代码自动质检，但仓库实际托管平台为Gitee（码云），Gitee不兼容GitHub Actions配置语法，该文件自创建起从未执行。

类比：在仅识别中文规则的安保处悬挂英文警示牌，全程无任何执行效力。

真相2：本地质检依赖手动执行，存在大量绕过通道

项目内置完整本地质检脚本scripts/quality/run-static-analysis.ps1，可校验文档规范、代码边界、单元测试，但存在硬性缺陷：

必须人工手动执行PowerShell命令启动校验
直接在终端执行原生git命令，可完全跳过所有校验流程

类比：办公区安检门仅正门生效，侧门、后门永久敞开，绕路即可规避全部检查。

真相3：项目核心铁律约束彻底失去保障

项目制定9条强制铁律 + SaaS 11项B级规范，所有规范落地依赖质检脚本拦截；一旦质检可随意跳过，全部规范仅靠AI、开发人员主观自觉，紧急迭代场景极易出现违规代码合并。

二、整体改造方案（通俗描述）

方案一句话总结

搭建双层本地Git强制门禁，代码提交、推送远程仓库全流程自动执行质检，无任何绕过渠道。

双闸门禁运行逻辑（地铁进站类比）

修改代码，执行本地保存（git commit）
        │
        ▼
┌─────────────────────────┐
│ 第一道闸：pre-commit    │  耗时≤5秒（快速检查站）
│ 校验内容：              │
│ 1. 文档规范一致性       │
│ 2. 核心配置文件完整性   │
│ 3. SaaS代码边界合规性   │
│ 拦截规则：校验失败直接阻止本地保存 │
└─────────────────────────┘
        │（校验通过放行）
        ▼
代码本地版本保存完成

执行推送远程仓库（git push）
        │
        ▼
┌─────────────────────────┐
│ 第二道闸：pre-push      │  耗时3–5分钟（全量检查站）
│ 校验内容：              │
│ 1. 复用第一道闸全部检查 │
│ 2. 全项目代码编译       │
│ 3. 完整单元测试执行     │
│ 4. 静态安全扫描         │
│ 拦截规则：校验失败阻止推送至Gitee远程仓库 │
└─────────────────────────┘
        │（校验通过放行）
        ▼
代码同步至Gitee远程仓库

双层门禁设计理由

高频commit动作仅执行秒级轻量校验，不干扰日常开发效率
低频push推送动作执行完整全量校验，保证上传远程的代码完全合规
兼顾开发体验与质量管控，避免全量校验拖慢日常迭代

三、改造前后开发场景对比

使用场景	改造前（现状）	改造后
AI助手内提交代码	内置拦截机制，有效	保留原有拦截，双层防护
终端直接执行`git commit`	无任何校验，直接放行	自动触发5秒快速校验，不合格拦截
终端执行`git push`推送代码	无任何校验，直接上传远程	自动执行全量编译测试，不合格阻断推送
新设备/新人克隆仓库	无质检保护，全靠自觉	一条命令一键启用全套门禁，统一约束
紧急迭代临时跳过校验	破坏性命令`--no-verify`，无日志记录	可控逃生舱`HOOK_SKIP=1`，留痕可追溯

真实场景示例

改造前
人工/AI误删除核心配置文件，直接执行git commit && git push推送代码，直至部署阶段才暴露配置缺失问题，问题扩散周期长。

改造后
相同操作执行git commit时，门禁立刻拦截并输出清晰报错：

✗ 检查失败：harness 文件缺失: .cursor/hooks.json
（该文件为项目强制核心配置，禁止删除）
提交操作已终止，请修复后重试

问题在本地提交阶段直接暴露，不会同步至远程仓库。

四、落地5项具体工作（通俗拆解）

1. 新建快速校验脚本

创建scripts/quality/run-quality-fast.ps1，仅执行秒级静态校验：

文档与代码描述一致性校验
项目核心文件完整性检测
文档存放路径合规校验
SaaS代码目录边界管控
整体耗时不超过5秒，作为第一道闸执行脚本。

2. 搭建两道Git闸门脚本

新建版本托管目录githooks/，内置两份脚本并提交至Gitee仓库，团队所有人共享统一规则：

githooks/pre-commit：commit触发，调用快速校验脚本
githooks/pre-push：push触发，调用现有全量静态分析脚本

3. 一键安装启用脚本

新建scripts/install-git-hooks.ps1，新设备、新人仅需执行一次命令完成全套门禁启用：

pwsh scripts/install-git-hooks.ps1

卸载仅需单行命令：git config --unset core.hooksPath

4. 更新项目说明文档

同步修改AGENTS.md、docs/文档治理.md，完整说明双层门禁运行逻辑、启用/卸载方式、临时跳过校验规范，便于后续维护人员、AI理解机制，避免误删脚本。

5. 全流程验证测试

落地完成后现场验证4类场景，确认机制100%生效：

主动破坏文档规范，commit操作被拦截
使用逃生舱变量临时跳过校验，可正常提交
无违规代码，门禁不误报、不阻断正常开发
终端原生git命令全部触发校验，无绕过漏洞

五、工作量、风险与边界说明

预估工作量

脚本编写：1小时
文档更新：30分钟
全流程测试验证：30分钟
合计约2小时，单日可完整落地

风险应对方案

潜在顾虑	落地配套应对策略
校验脚本存在bug，误拦截合规代码	报错输出完整校验项、失败原因，支持逃生舱临时放行，便于快速定位脚本问题
新设备无PowerShell环境	脚本自动检测环境，缺失PowerShell仅警告不阻断开发，同步提示安装依赖
与现有Cursor内置钩子冲突	两层机制分工明确：Cursor管控AI行为，Git Hook管控终端git操作，无功能重叠冲突
紧急迭代需要临时跳过校验	标准化可控逃生舱`HOOK_SKIP=1 git commit`，替代破坏性`--no-verify`，操作留痕可审计
改造影响现有业务代码	仅新增脚本、文档，零原有代码修改，卸载即可完全恢复原有状态

明确不实施的边界（无额外改造）

❌ 不接入Gitee Go云端流水线、不改造GitHub Actions配置
❌ 不删除现有GitHub工作流配置文件，预留后续切换GitHub场景复用
❌ 不修改现有run-static-analysis.ps1校验逻辑
❌ 不改动.cursor/hooks/内置AI拦截脚本
❌ 不新增提交信息规范hook（commit-msg）

六、方案总结一句话

将项目质检从「人工自觉模式」升级为「全自动强制门禁模式」，2小时落地，所有代码变更本地提前拦截缺陷，杜绝问题同步至远程仓库、交付客户现场。

若认可方案，将按5项工作顺序分步落地，每完成一项同步展示实际运行效果，确认后即可启动实施。

方案极简摘要：本地Git自动质检门禁

背景核心问题

项目质检机制失效：GitHub格式云端配置在Gitee无法运行；本地质检依靠手动执行，终端git命令可完全绕过所有约束。本次落地本地强制门禁，实现提交、推送全流程自动质检。

核心双层架构

第一道pre-commit（高频，≤5秒）：仅执行纯静态文档、配置、SaaS边界校验
第二道pre-push（低频，3–5分钟）：完整复用现有全量编译、测试、静态分析脚本

新增/修改文件清单（4个新增文件 + 2份文档更新，无业务代码改动）

scripts/quality/run-quality-fast.ps1 快速校验编排脚本
githooks/pre-commit 提交闸门（bash包装调用PowerShell，兼容Windows Git）
githooks/pre-push 推送全量校验闸门
scripts/install-git-hooks.ps1 一键启用脚本
新增verify-saas.ps1 -SkipSelfcheck开关，分离快慢挡校验逻辑
更新AGENTS.md、docs/文档治理.md完善机制说明

落地核心价值

彻底封堵终端git绕过质检的核心漏洞
缺陷本地即时暴露，不流入远程仓库
新设备/新人一键启用全套统一质量约束
所有校验复用现有成熟脚本，规则唯一标准，无两套规范分裂问题
完全可逆，单行命令卸载，无侵入性改造

验收验证场景

正常代码commit无拦截、不误报
主动删除核心harness文件，commit直接拦截并提示缺失项
HOOK_SKIP=1逃生舱可临时放行，满足紧急迭代场景
终端直接push代码自动触发全量编译测试
快速校验脚本单次运行耗时＜10秒

明确不做范围

不引入云端CI流水线、保留原有GitHub配置、不修改现有静态分析脚本逻辑、不改动Cursor内置钩子、不新增提交信息校验、不修改业务代码。

工作量预估

整体落地约2小时，分5个步骤顺序执行。

第三轮：标准化落地设计规格文档（可直接交付实施）

前置说明

行业普遍痛点：AI输出方案宏观空洞，落地时大量简化、降级、硬编码，验收效果严重缩水。因此要求先输出完整落地设计规格，明确整体架构、组件分工、执行逻辑、落地收益，消除实施歧义，全程留存上下文。

本次规格不做空中楼阁式概述，精准对齐现有校验脚本真实逻辑，每一项校验对应脚本代码逻辑，作为施工唯一蓝图。落地前已完整研读全部核心校验脚本，确认所有现有校验项真实执行逻辑，具备完整事实支撑。

设计规格：Maiyata 项目自动质检门禁(本地 Git Hooks)

文档定位：落地施工蓝图，无模糊描述；每项校验对应现有脚本真实逻辑，明确各层架构职责边界，消除实施歧义。

第一部分：三层咬合式质检整体架构

1.1 架构流程图

┌─────────────────────────────────────────────────────────────────────┐
│                        开发操作入口                                  │
│                                                                     │
│   场景A：Cursor AI助手内修改代码                                     │
│   场景B：终端/IDE直接执行git命令                                     │
└───────────────┬─────────────────────────────────┬───────────────────┘
                │                                 │
                ▼                                 ▼
┌───────────────────────────────┐  ┌──────────────────────────────────┐
│  第一层：Cursor Hook 原生层    │  │  第二层：新增本地Git Hook层       │
│  本次不做任何修改              │  │                                  │
│  触发时机：                    │  │  触发时机：                       │
│ • AI执行shell命令前            │  │ • git commit → pre-commit        │
│ • AI写入文件前                 │  │ • git push → pre-push            │
│ • AI会话结束校验               │  │                                  │
│ 覆盖范围：仅AI助手内部操作      │  │ 覆盖范围：全部终端/IDE git操作    │
│ 固有局限：终端git命令可绕过     │  │ 核心价值：封堵终端绕过漏洞        │
└───────────────┬───────────────┘  └──────────────┬───────────────────┘
                │                                 │
                └────────────┬────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│              第三层：成熟质检脚本层（已有，仅调度调用，不改逻辑）     │
│                                                                     │
│ 快挡组件（pre-commit调用，秒级）：                                   │
│  ┌─────────────────────┐  ┌─────────────────────┐                  │
│  │ verify-doc-truth    │  │ verify-saas（静态）  │                  │
│  │ 文档-代码一致性校验 │  │ SaaS边界静态校验     │                  │
│  └─────────────────────┘  └─────────────────────┘                  │
│                                                                     │
│ 慢挡组件（pre-push调用，分钟级）：                                   │
│  ┌─────────────────────────────────────────────────────────┐       │
│  │ run-static-analysis.ps1(完整全量编排)                   │       │
│  │ = 全部快挡校验 + dotnet编译测试 + go vet/test + semgrep │       │
│  └─────────────────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────────────────┘

1.2 三层架构职责边界（无重叠、互补设计）

层级	触发主体	校验范围	执行速度	本次改造动作
第一层 Cursor Hook	AI助手执行文件/命令操作	拦截高危git操作、禁止修改禁区文件、写入验证锁	毫秒级	完全保留，不修改
第二层 Git Hook（新增）	所有git commit/push动作	调度调用下层质检脚本，统一拦截放行	秒级~分钟级	全新开发
第三层质检脚本	Git Hook/人工手动调用	文档、代码、规范、安全完整规则校验	按校验类型区分	不修改核心逻辑，仅新增调度开关

核心设计原则

两层拦截机制互补而非替代：Cursor Hook管控AI行为，Git Hook管控全部git操作，实现无死角防护
Git Hook仅做调度，不新增自定义校验规则，复用现有成熟脚本，保证全场景校验标准完全统一，避免本地、门禁两套规则分裂

第二部分：完整校验清单（commit/push分层）

2.1 快挡 pre-commit（≤5秒，仅静态校验，无编译/单元测试）

调用verify-doc-truth.ps1，自动串联4大类共30+细分校验项：

A组：文档-代码真相一致性校验（6项）

编号	校验内容	失败处理逻辑	业务价值
A1	C#代码文件存在，但设计文档标注「未开发/无代码」	直接拦截，提示文档与代码冲突位置	防止文档描述与实际代码脱节，误导AI开发
A2	已归档废弃计划文档仍被活跃文档引用	拦截，输出所有无效引用文档路径	避免AI基于废弃需求开发
A3	AGENTS冻结矩阵核心目录完整（采集器、探针、授权核心、实施索引）	拦截，列出缺失目录	防止误删除项目基础骨架
A4	L0 harness强制24个核心文件齐全（hooks.json、各类校验脚本、规范文档）	拦截，输出缺失文件清单	保障harness整套约束机制不被破坏
A5	saas目录下存在Go源码，但缺失go.mod	拦截，提示代码目录边界违规	约束SaaS代码目录规范
A6	跨会话索引禁止包含未标注废弃的Collector纯文档	拦截	消除历史过时文档误导

B组：Cursor Hooks自检（15项，A4自动调用verify-hooks.ps1）

编号	校验内容	失败处理
B1	`.cursor/hooks.json`配置文件存在且JSON格式合法	拦截
B2	json注册的所有钩子脚本物理文件真实存在	拦截，列出缺失脚本
B3	本地钩子脚本全部在hooks.json完成注册（双向无孤儿脚本）	拦截，输出未注册脚本
B4	钩子依赖基础库文件（lib/HookState.ps1等）完整	拦截
B5	每个钩子脚本样例输入输出合法，返回码、权限字段合规（deny/ask/allow）	拦截，定位异常钩子
B6	verification-lock、delivery-chain标记文件写入时机合规	拦截

C组：文档治理规范校验（12项，A4自动调用verify-doc-governance.ps1）

编号	校验内容	失败处理
C1	仓库根目录仅允许AGENTS.md、CLAUDE.md，其余md文件违规	拦截，提示文件迁移路径
C2	docs根目录仅允许3份索引治理文档	拦截
C3	src/tests/scripts深层目录禁止存放说明md文档	拦截
C4	spec/plan/standard/knowledge文档必须登记对应索引，无孤儿文档	拦截，输出未登记文档
C5	编码规范文档统一存放standards目录，禁止放入specs	拦截
C6	spec/plan文档头部必须包含status、创建时间元数据	仅警告，不阻断提交
C7	标注废弃的文档必须归档至_archive目录，禁止保留在活跃目录	拦截
C8	3份明确废弃历史计划文档禁止复用	拦截

D组：SaaS边界静态校验（6项，快挡跳过编译自检selfcheck）

编号	校验内容	失败处理
D1	SaaS骨架文件齐全（go.mod、main.go、API契约yaml、desktop说明文档、UI基线）	拦截
D2	API契约yaml包含5个冻结关键字（ErrorResponse等）	拦截
D3	go.mod模块名称固定为`github.com/maiyata/collector`	拦截
D4	墙内Go代码禁止导入墙外路径（../..、MaiyataMonitor等5类违规模式）	拦截
D5	Desktop层禁止直接依赖协议栈NuGet包（S7netplus、OPC UA等）	拦截
D6	所有saas Go源码必须存放saas/collector目录内	拦截

关键设计决策
D组第6项内置go run ./cmd/collector selfcheck编译自检逻辑，快挡新增-SkipSelfcheck参数完全跳过该段代码，规避Go编译拖慢commit速度；编译自检统一放置在慢挡push阶段执行。

2.2 慢挡 pre-push（3–5分钟，全量完整校验）

完整调用现有run-static-analysis.ps1，执行顺序固定：

慢挡 = run-static-analysis.ps1 全量完整执行
        │
        ├─ ① L0基础文档校验：verify-doc-truth（覆盖快挡全部A/B/C组）
        │
        ├─ ② C#采集器分支（检测Maiyata.Collector.slnx存在则执行）：
        │     • dotnet format --verify-no-changes 代码格式校验
        │     • dotnet build -c Release 完整编译
        │     • dotnet test 单元测试执行
        │     • dotnet list package --vulnerable 依赖漏洞扫描
        │     • semgrep C#安全规则扫描
        │
        └─ ③ SaaS Go分支（检测saas/collector/go.mod存在则执行）：
              • verify-saas.ps1 完整执行（包含selfcheck编译自检）
              • go vet ./... Go静态缺陷扫描
              • go test -race ./... 并发竞态检测（依赖CGO+gcc）
              • semgrep Go安全规则扫描

慢挡覆盖快挡全部静态校验，额外叠加编译、单元测试、安全扫描、并发检测，作为代码推送远程前最终质量闸口。

2.3 快慢挡核心对比表

对比维度	快挡 pre-commit	慢挡 pre-push
触发git动作	git commit 本地保存	git push 推送远程仓库
单次执行耗时	＜5秒	3–5分钟
调用脚本	新增`run-quality-fast.ps1`	复用现有`run-static-analysis.ps1`
校验内容	A/B/C/D静态30+项，无编译、测试	快挡全部内容 + 编译 + 单元测试 + 漏洞扫描 + 竞态检测
校验失败结果	阻止本地commit保存	阻止代码推送至Gitee远程
临时跳过方案	环境变量`HOOK_SKIP=1`	环境变量`HOOK_SKIP=1`

第三部分：落地文件明细与各文件精准职责

3.1 新增/修改完整文件树

githooks/                              # 新建目录，纳入版本管理
  ├─ pre-commit                        # 新建：commit闸门脚本
  └─ pre-push                          # 新建：push全量校验闸门脚本
scripts/quality/
  ├─ run-quality-fast.ps1              # 新建：快挡静态校验编排脚本
  └─ run-static-analysis.ps1           # 原有脚本，完全不修改逻辑
scripts/
  └─ install-git-hooks.ps1             # 新建：一键启用Git Hook配置脚本
# 文档修改
AGENTS.md                              # 更新Harness机制章节
docs/文档治理.md                        # 更新自动化质检流程章节
# 最小代码改动
scripts/quality/verify-saas.ps1        # 新增-SkipSelfcheck开关参数

落地总量：4份全新文件 + 2份文档更新 + 1处极小脚本参数改造；零业务代码、零原有校验逻辑改动。

3.2 各文件精准职责说明

文件1：`scripts/quality/run-quality-fast.ps1`（快挡编排器）

核心职责：按固定顺序串联现有静态校验脚本，仅执行纯静态规则，跳过所有编译、单元测试逻辑。
执行伪逻辑

1. 自动切换至仓库根目录，统一工作路径
2. 执行verify-doc-truth.ps1（自动包含hooks自检、文档治理校验）
   脚本返回非0退出码 → 直接终止流程，拦截commit
3. 调用verify-saas.ps1并传入-SkipSelfcheck参数，跳过Go编译自检
   返回非0退出码 → 直接终止流程，拦截commit
4. 输出提示：快速校验通过，推送代码前需执行完整全量静态分析

配套设计：完全复用现有run-static-analysis.ps1的Assert-ExitCode错误判断逻辑，统一失败拦截标准。

文件2：`githooks/pre-commit`（第一道提交闸门）

技术选型说明
采用bash外层包装，内部显式调用pwsh，规避Windows Git Bash无法正常解析pwsh shebang的PATH兼容问题，跨平台稳定性最优。
执行逻辑

1. 检测环境变量HOOK_SKIP=1，存在则直接放行（标准化逃生舱，留执行日志）
2. 校验系统PATH是否包含pwsh，缺失则输出警告，不阻断提交（兼容无PowerShell新环境）
3. 调用PowerShell执行run-quality-fast.ps1快速校验脚本
4. 脚本返回非0退出码 → git终止commit操作，校验失败拦截

文件3：`githooks/pre-push`（第二道推送闸门）

核心职责：代码推送远程仓库前执行全套完整质检，逻辑与pre-commit基础框架一致，仅替换调用脚本为run-static-analysis.ps1全量静态分析。
设计依据：push属于低频操作，3–5分钟全量校验不会干扰日常开发，保障同步至远程的代码可编译、可测试、合规无漏洞。

文件4：`scripts/install-git-hooks.ps1`（一键启用脚本）

核心职责：统一配置git全局hook路径，新人/新设备单命令完成全套门禁启用。
执行逻辑

1. 执行git config core.hooksPath githooks，指定git读取hook脚本的目录
2. 校验配置写入成功，输出启用确认信息
3. 打印逃生舱使用规范、完整卸载命令：git config --unset core.hooksPath

核心优势
摒弃传统.git/hooks目录方案：.git目录不纳入版本管理，每台设备需手动复制脚本；core.hooksPath方案将hook脚本提交仓库，全团队共享统一校验规则。

3.3 关键技术风险与内置应对方案

潜在风险场景	触发条件	规格内置应对策略
运行环境无PowerShell	新人全新Windows设备/轻量Linux开发环境	hook脚本检测pwsh命令是否存在，缺失仅警告、不阻断开发，同步提示安装依赖
Git Bash shebang解析异常	Windows终端执行git命令	bash外层包装，显式调用pwsh二进制，规避PATH解析bug
开发人员频繁跳过校验	迭代紧急，嫌校验耗时	快挡仅保留5秒内静态检查；紧急场景标准化逃生舱HOOK_SKIP，替代破坏性--no-verify
--no-verify恶意绕过校验	终端手动输入跳过参数	Cursor层`block-dangerous-git.ps1`拦截高危git参数，双层防护
verify-saas编译自检拖慢commit	快挡误触发Go完整编译	新增-SkipSelfcheck参数，commit阶段完全跳过编译逻辑
Cursor原生钩子与Git Hook冲突	两层拦截机制职责重叠	分层设计：Cursor管控AI写文件/发命令，Git Hook管控git版本操作，触发时机完全隔离，无冲突

第四部分：落地后可量化验证价值

4.1 核心价值1：彻底封堵终端绕过漏洞

改造前：终端执行git commit --no-verify && git push，零校验直接同步代码至远程仓库，无任何拦截。
改造后：相同操作触发pre-commit 30+项静态校验、pre-push全量编译测试，不存在绕过渠道。

4.2 核心价值2：缺陷本地即时暴露，前置质量拦截

真实场景示例：AI误删除.cursor/hooks.json核心配置文件

改造前：commit、push全程放行，直至后续harness功能异常才发现配置丢失
改造后：本地commit 5秒内直接拦截，精准输出缺失文件名称，当场修复，缺陷不会流入远程仓库。

4.3 核心价值3：标准化团队质量约束，新环境零配置

改造前：新人克隆仓库无任何质检约束，全靠人工自觉执行脚本。
改造后：新人执行一次安装脚本，自动获得与项目主维护人完全一致的双层门禁，统一质量标准。

4.4 核心价值4：全局唯一校验标准，消除规范分裂

无论人工手动执行脚本、AI助手内部执行、Git自动触发门禁，均调用同一套底层校验脚本，不存在「门禁一套规则、本地手动一套规则」的标准撕裂问题；底层脚本更新一处，全场景同步生效。

4.5 核心价值5：完全可逆、零侵入改造

无任何业务源码修改，仅新增基础设施脚本、文档
单行命令即可完整卸载门禁：git config --unset core.hooksPath
全部新增文件可直接删除，对项目原有功能无任何负面影响

第五部分：验收标准（落地后现场验证5项场景）

序号	验收测试场景	预期标准结果
1	合规代码正常commit提交	5秒快速校验一次性通过，无误拦截、无冗余报错
2	主动删除harness核心配置文件后执行commit	快速校验直接拦截，完整输出缺失文件清单
3	使用逃生舱变量`HOOK_SKIP=1 git commit`	校验放行，逃生舱机制生效
4	终端直接执行git push推送代码（不经过Cursor）	自动触发pre-push全量编译、测试校验
5	快速校验脚本耗时测试`Measure-Command { pwsh run-quality-fast.ps1 }`	单次总耗时＜10秒

第六部分：明确不实施边界（无额外改造）

不落地事项	核心理由
不接入Gitee Go / GitHub Actions云端CI流水线	项目选定本地门禁管控路线，暂不上云流水线
不删除现有`.github/workflows/saas-collector.yml`	保留配置，后续切换GitHub仓库可直接复用
不修改`run-static-analysis.ps1`原有校验逻辑	维持全量校验原有语义，慢挡直接复用无需重构
不改动`.cursor/hooks/`目录下任何原生脚本	Cursor层AI管控机制独立，本次仅补充终端git防护
不新增commit-msg、prepare-commit-msg提交信息钩子	提交信息规范非本次改造目标，避免范围蔓延
不修改任何业务代码、SaaS采集器、WPF桌面层逻辑	本次仅改造质量基础设施，零业务侵入

第七部分：落地执行步骤与工时规划

步骤序号	落地工作内容	预估耗时
1	为`verify-saas.ps1`新增`-SkipSelfcheck`开关参数（最小代码改动）	5分钟
2	新建`scripts/quality/run-quality-fast.ps1`快速校验编排脚本	15分钟
3	新建`githooks/pre-commit`、`githooks/pre-push`两道闸门脚本	15分钟
4	新建`scripts/install-git-hooks.ps1`一键启用脚本	10分钟
5	更新`AGENTS.md`、`docs/文档治理.md`完善机制说明	20分钟
6	现场执行5项验收场景完整测试验证	30分钟
合计总工时	——	约1.5小时

规格文档极简摘要（便于快速查阅）

设计规格：Maiyata 项目自动质检门禁(本地 Git Hooks)

核心问题

项目质检机制存在致命漏洞：GitHub格式云端流水线在Gitee无法运行；本地完整质检依靠人工手动执行，终端原生git命令可完全绕过所有规范校验。本次搭建双层本地强制门禁，实现所有代码提交、推送全流程自动化质检拦截。

三层咬合架构

第一层 Cursor Hook（已有、不修改）：管控AI助手内部文件/命令操作
第二层 Git Hook（全新开发）：管控所有终端git commit/push操作，封堵绕过漏洞
第三层质检脚本（已有、仅调度调用）：存储完整文档、代码、安全校验规则

Git Hook仅作为调度层，不新增自定义校验逻辑，保证全场景校验标准统一。

双层门禁运行规则

pre-commit（快挡，≤5秒）：执行文档真相、hooks自检、文档治理、SaaS静态边界校验，跳过Go编译自检
pre-push（慢挡，3–5分钟）：完整复用run-static-analysis.ps1，覆盖快挡全部校验 + .NET/Go编译、单元测试、安全扫描、竞态检测

文件改造范围

4份全新脚本 + 2份文档更新 + 1处极小脚本参数改造；零业务代码改动。

scripts/quality/run-quality-fast.ps1：快挡编排脚本
githooks/pre-commit、githooks/pre-push：两道闸门
scripts/install-git-hooks.ps1：一键启用脚本
verify-saas.ps1新增-SkipSelfcheck开关
AGENTS.md、文档治理.md更新机制说明

落地核心价值

彻底封堵终端git绕过质检的最高风险漏洞
缺陷本地提交阶段即时拦截，不流入远程仓库
新设备、新人一键启用全套统一质量约束
全场景复用同一套校验脚本，无两套规范分裂问题
完全可逆，单行命令卸载，无任何侵入性改造

验收验证5项场景

合规commit无拦截、删除核心harness文件被拦截、HOOK_SKIP逃生舱可用、终端push触发全量校验、快挡单次运行耗时＜10秒。

明确不落地范围

不接入云端CI、保留原有GitHub流水线配置、不修改全量静态分析脚本逻辑、不动Cursor原生钩子、不新增提交信息校验、不改动业务代码。

总工时

整体落地约1.5小时，分6步顺序执行。

第四轮：结合DevOps专家意见强化静态分析、全栈代码校验方案

核心术语通俗解读（2026 AI代码工程标准）

CI漂移（CI Drift）
定义：本地完整harness校验套件与云端CI流水线校验能力严重脱节、标准不一致。

本地harness：开发者本地完整质量约束脚本run-static-analysis.ps1，是项目官方完整质量标准
云端CI（GitHub Actions）：PR合并阶段自动执行的云端流水线
漂移后果：本地十几项强制校验，云端仅执行2项；本地严格、线上宽松，质量标准撕裂。

Harness（2026 AI工程专属概念，非第三方平台）
项目本地全套代码约束工具链，类比约束AI编码的缰绳、安检围栏；所有代码提交前必须完整执行harness全套校验，保障文档、代码、安全、并发、规范全维度合规。
组件包含：文档校验、钩子完整性校验、代码静态扫描、并发竞态检测、安全漏洞扫描、编译单元测试。
verification-lock（铁律9）
项目强制约束：全套校验钩子必须强制执行，禁止随意跳过。

verify-hooks.ps1：校验git钩子配置文件完整性，防止人为删除强制校验规则
verify-doc-truth：文档真实性校验，杜绝文档描述与实际代码逻辑不一致
verify-doc-governance：文档存放、格式、版权、标签合规校验

多语言栈校验工具核心作用

工具	核心能力
`go test ./...`	Go全项目单元测试执行
`go build`	Go语法编译校验，捕获基础语法错误
`go vet`	Go官方静态缺陷扫描，捕获编译器无法识别的隐藏代码隐患
`go test -race`	Go协程并发竞态检测，提前发现多线程随机崩溃问题（原CI缺失核心项）
`semgrep`	开源代码安全扫描工具，双规则集：业务编码规范、通用漏洞安全规则
`dotnet build + test`	.NET/C#项目编译、单元测试全量执行

Matrix Job（GitHub Actions矩阵任务）
单份yaml配置并行执行多语言、多环境校验，无需重复编写多份Job配置，简化CI维护，同时并行执行Go、.NET两套代码校验。
写时拦截
代码编写、本地提交阶段提前拦截缺陷，是行业最优左移质量管控方案；而非等到合并、上线阶段才暴露故障。

现状致命缺陷完整拆解

两套质量标准严重撕裂

云端CI文件.github/workflows/saas-collector.yml仅执行：go编译 + go单元测试2项
本地完整harness脚本强制执行7大类校验：SaaS边界校验、文档一致性、文档合规、Go静态扫描、并发竞态检测、安全漏洞扫描
铁律9依赖的2项核心校验（verify-hooks、verify-doc-truth）在云端CI完全缺失

无强制兜底约束，质检完全依赖自觉

开发人员可手动跳过本地全套校验脚本，直接提交PR
AI批量生成代码不会主动执行本地harness校验，直接生成违规代码提交
云端CI校验项缺失，本地全跳过也能绿色通过PR合并，无任何拦截机制
写时拦截机制彻底失效，规范、并发、安全缺陷全部流入主干仓库，埋下线上故障隐患

痛点一句话总结
本地拥有完整严格质检体系，但云端合并关卡完全宽松；人工、AI均可绕过全部质检合并代码，质量防线仅依靠主观自觉，体系极度脆弱。

2026行业核心理念：CI = harness 的唯一权威标准

无论本地是否手动执行校验，所有PR合并流程必须完整复现本地harness全部校验项
CI流水线校验失败直接禁止PR合并，不存在任何跳过渠道
彻底消除本地严格、云端宽松的标准撕裂，CI作为统一、不可绕过的质量闸口

新建`harness.yml`流水线分层设计（所有PR强制执行）

L0前置基础校验（优先执行，快速拦截配置/文档违规）

verify-doc-truth 文档代码一致性校验
verify-doc-governance 文档存放规范校验
verify-hooks 钩子配置完整性校验>

前置执行文档、配置校验，不合规直接失败，无需浪费资源执行编译、单元测试

Go语言全量代码质量校验

go vet 静态代码缺陷扫描
go test -race 单元测试 + 并发竞态漏洞检测（原CI缺失核心项）

多语言栈.NET校验

dotnet build + dotnet test 完整编译、单元测试覆盖C#业务代码

安全扫描层

semgrep双规则集并行执行：业务编码规范扫描 + OWASP通用安全漏洞扫描

流水线落地技术关键点

独立新建harness.yml工作流文件，与原有简易saas-collector流水线解耦，所有PR自动触发，无法手动关闭
采用matrix job矩阵任务，单份配置并行执行Go、.NET两套语言校验，yaml配置极简易维护
改造成本极低，仅新增一份GitHub Actions配置文件，数小时即可补齐质量管控最后一环

CI改造前后收益对比

对比维度	改造前旧CI	改造后harness.yml完整流水线
校验覆盖范围	仅编译+单元测试，缺失文档、钩子、并发、安全扫描	1:1完整复刻本地全套harness所有校验项
强制约束力度	可随意跳过，本地不执行也能合并代码	CI校验不全量通过，PR禁止合并，无任何绕过渠道
人工/AI约束	完全依赖自觉，AI自动绕过本地校验	云端强制兜底，AI生成违规代码直接被CI拦截
质量标准统一性	本地、云端两套标准，云端标准宽松	CI作为唯一权威标准，本地脚本仅作开发预览
潜在风险	文档漂移、并发崩溃、安全漏洞、钩子配置篡改流入主干	所有规范、安全、文档缺陷在合并前全部拦截

完整方案落地价值总结

彻底解决CI漂移核心缺陷，云端流水线与本地harness校验能力完全对齐，消除标准断层
消灭「自助式本地脚本」的脆弱性，不再依靠人工、AI主动执行本地校验，云端强制兜底防护
落地左移质量管控，代码提交阶段拦截全部缺陷，避免缺陷流转至测试、线上环境
适配2026 AI大规模代码生成开发模式，针对性解决AI不会主动执行本地校验的痛点
落地成本极低，仅新增一份GitHub Actions yaml配置，矩阵配置简化长期维护，投入小、收益极高

全栈静态分析统一等级落地要求

要求Go、C#、WPF、Vue、SQL全部达到Go语言现有13项linter同等专业静态分析覆盖标准；先完整盘点项目代码资产，再分栈落地对应工具链。

项目代码资产精准盘点（实地核验）

代码技术栈	存放目录	文件数量	当前静态分析覆盖现状	改造差距
Go	saas/collector	229个	已配置golangci-lint（13个linter），但未接入校验脚本执行	仅需接入现有脚本
C# 采集器业务	src/	22个	已配置NetAnalyzers、SecurityCodeScan安全分析器	无差距，可直接复用
C#/WPF桌面	saas/desktop	105cs + 18xaml	零静态分析器覆盖	项目最大质量盲区
C#/WPF探针	FieldProbe	110cs + 10xaml	零静态分析器覆盖	高风险盲区
C#/WPF监控	MaiyataMonitor	40cs + 5xaml	零静态分析器覆盖	高风险盲区
Vue/TS模拟器	ProtoForge S7模拟工具	1份活跃源码，其余备份快照	零ESLint配置，非主线交付代码	低优先级改造
SQL	数据库迁移脚本	10个migrate文件，Go代码存在大量硬编码SQL字符串	无语法、注入风险校验	中高优先级安全隐患

三大核心发现

WPF三层桌面项目合计255份cs、33份xaml文件，完全无静态分析防护，是当前最大代码质量盲区
Vue代码仅用于S7调试模拟器，不属于客户交付主线产品，优先级最低
SQL迁移脚本 + Go硬编码SQL存在SQL注入高危风险，必须补充语法、安全校验

各语言对标golangci-lint同等能力工具选型

golangci-lint标杆能力：一次性执行13类linter，覆盖代码正确性、安全漏洞、性能反模式、并发缺陷、编码风格五大维度。

语言栈	对标golangci-lint工具组合	完整覆盖能力	部署方式
Go	golangci-lint（扩充至25+ linter）	正确性、安全、并发、性能、风格全覆盖	二进制，脚本直接调用
C#/WPF	Roslyn Analyzers（NetAnalyzers + SecurityCodeScan + WPF专属分析器）	完全对标，编译期强制拦截，力度强于Go linter	NuGet包，MSBuild编译自动执行
C# 代码风格	dotnet format + .editorconfig全局配置	统一缩进、命名、换行规范，对标go风格检查	.NET SDK内置，无需额外安装
Vue/TS	ESLint + vue-eslint-parser + @typescript-eslint规则集	类型、异步、注入风险、Vue数据流规范全覆盖	npm环境，仅模拟器目录启用
SQL	sqlfluff（语法/风格校验） + semgrep SQL注入规则	语法错误、不规范写法、拼接SQL注入风险拦截	pip安装 + semgrep自定义规则

核心结论
C#项目可实现与Go完全同等甚至更强的静态管控能力；仅需将src目录现有分析器配置全局铺开，覆盖全部WPF桌面项目。

分栈落地实施计划

落地1：Go语言 golangci-lint 接入（最高优先级，0.5小时）

现状：.golangci.yml已配置13个linter，但run-static-analysis.ps1未调用执行，配置完全闲置。
改造动作：在脚本go vet执行后新增一行调用：

golangci-lint run --timeout 5m ./...

落地收益：13类linter立即生效，自动捕获废弃API调用、SQL注入、HTTP资源泄漏、context丢失、错误掩盖等真实线上bug。
前置依赖：本地开发环境预装golangci-lint二进制程序。

落地2：C#/WPF全局分析器铺开（最大盲区，1小时）

现状：仅src目录配置代码分析器，三层WPF桌面项目完全无防护。
改造动作：仓库根目录新增全局Directory.Build.props，自动作用于所有子项目，完整复用src目录成熟配置：

<PropertyGroup>
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  <AnalysisLevel>latest-recommended</AnalysisLevel>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
  <Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="9.0.0" PrivateAssets="all"/>
  <PackageReference Include="SecurityCodeScan.VS2019" Version="5.6.7" PrivateAssets="all"/>
</ItemGroup>

落地收益

正确性校验：捕获忽略返回值、未释放资源等C#经典缺陷
安全校验：拦截硬编码密钥、弱加密、XSS风险
WPF专属校验：MVVM规范、UI线程误用、绑定异常检测
强制拦截：TreatWarningsAsErrors=true，任何分析警告直接编译失败，强制力度高于Go linter
配套改造：全局.editorconfig统一全语言代码缩进、命名规范，dotnet format自动格式化。

落地3：Vue/TS ESLint配置（低优先级，0.5小时）

现状：仅模拟器工具使用，非交付主线，无ESLint约束。
改造动作：tools/simulators/s7/ProtoForge/web/目录新增eslint.config.js，启用TypeScript、Vue、安全扫描规则。
核心规则对标golangci能力

@typescript-eslint/no-explicit-any：禁止无类型any，对标Go静态强类型约束
@typescript-eslint/no-floating-promises：强制await异步方法，对标Go errcheck错误检测
vue/no-mutating-props：约束Vue单向数据流规范
security/detect-object-injection：拦截前端注入风险
优先级说明：仅模拟器使用，可延后落地，或仅警告不阻断提交。

落地4：SQL双层校验方案（中优先级，0.5小时）

现状：10份迁移脚本 + Go代码大量硬拼接SQL字符串，存在注入高危风险。
双层落地动作

语法/风格层：安装sqlfluff，脚本执行sqlfluff lint saas/collector/migrations/，捕获语法错误、格式不规范、缺失注释等问题
安全风险层：扩展semgrep规则集，新增Go代码fmt.Sprintf拼接SQL注入检测规则，优先级高于sqlfluff

落地收益：避免数据库迁移脚本语法错误导致部署失败；拦截硬编码拼接SQL引发的注入漏洞。

更新后三层质检完整静态分析覆盖

┌─────────────────────────────────────────────────────────────────┐
│ 快挡 pre-commit（commit，5–10秒，纯静态无编译测试）             │
│ 1. 文档真相、hooks自检、文档治理、SaaS边界静态校验（原有）        │
│ 2. semgrep毫秒级扫描（Go/C#基础7条业务规则）                     │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 中挡（push，1–3分钟，全栈静态分析，不执行单元测试）              │
│ 1. 完整复用快挡全部校验项                                        │
│ 2. Go：golangci-lint完整执行（13+ linter）★核心新增             │
│ 3. Go：go build -tags all_drivers 完整编译校验                   │
│ 4. C#/WPF：dotnet build（全局Roslyn分析器，警告即失败）★核心新增 │
│ 5. SQL：sqlfluff迁移脚本语法校验 ★新增                           │
│ 6. Vue：eslint（仅修改模拟器代码时执行）                        │
│ 7. semgrep扩展至20条规则（新增SQL注入、密钥扫描规则）★核心新增   │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 慢挡（手动全量执行，3–5分钟，完整测试+并发检测）                │
│ 1. 完整复用中挡全部静态分析项                                    │
│ 2. Go：go test -race 单元测试 + 并发竞态检测（CGO依赖）          │
│ 3. C#：dotnet test 完整单元测试                                  │
│ 4. dotnet list package --vulnerable 依赖漏洞扫描阻断             │
└─────────────────────────────────────────────────────────────────┘

全栈静态分析落地优先级与工时规划

优先级标记	落地任务	预估工时	业务价值
🔴 P0 最高优先级	Go golangci-lint接入脚本	0.5h	13类linter即时生效，补齐Go代码质量防护
🔴 P0 最高优先级	根目录全局Directory.Build.props，全覆盖WPF项目	1h	255份裸奔C#/XAML代码实现强制静态管控
🟡 P1 中优先级	semgrep规则扩容，新增SQL注入、密钥扫描通用安全规则	1h	安全规则从7条扩充至20条，覆盖OWASP高危漏洞
🟡 P1 中优先级	完善三层质检脚本分层（fast/static/full）	1h	统一快慢挡执行边界，减少开发等待耗时
🟡 P1 中优先级	Git Hook全套安装、闸门脚本落地	0.5h	实现终端强制门禁，封堵绕过漏洞
🟢 P2 低优先级	SQL sqlfluff迁移脚本语法校验	0.5h	规避数据库部署语法故障
🟢 P3 最低优先级	Vue模拟器ESLint配置落地	0.5h	仅调试工具代码规范管控，非交付主线
⚪ P0 配套文档	AGENTS.md、文档治理.md同步更新全栈静态分析说明	0.5h	文档与落地机制同步，便于AI/开发理解
合计总工时	——	约5.5小时	——

两项关键决策确认（落地前确认，决定C#改造策略）

Vue/SQL优先级确认
当前方案：Vue模拟器P3最低优先级，SQL校验P2中等优先级；若认为SQL注入为工业项目最高危风险，可上调至P1优先落地。
C# TreatWarningsAsErrors=true 落地过渡策略二选一

方案A（推荐硬切）：直接启用警告即编译失败，一次性清理存量历史警告，长期强制力度最强，对齐Go linter失败阻断标准；短期会出现大量历史警告导致编译失败，需一次性批量修复。
方案B（软切过渡）：仅输出警告不阻断编译，存量历史警告暂缓处理，仅约束新增代码规范，无短期改造阻塞风险，但强制力度下降。

确认两项决策后，将完整全栈静态分析方案并入设计规格文档，完成最终施工蓝图。

第五轮：对标头部大厂DevSecOps体系，梳理现有方案缺失缺陷

整体结论

项目文档治理、AI Agent自律约束体系处于行业顶尖水平（9条铁律、三层harness、四层错题记忆），绝大多数中小厂、中型团队无同等设计；但在安全工具链硬门禁、供应链安全管控层面存在系统性短板，绝大多数安全护栏完全空白。

16项大厂标准对标差距全景（红黄绿分级+落地取舍判断）

🔴 第一类：安全护栏（大厂强制标配，当前几乎空白，必须补齐）

序号	大厂标准实践	项目现状	成熟度	是否建议落地	落地判断
1	密钥/敏感信息扫描（gitleaks/trufflehog）	无任何配置	0%	必补	工业采集项目存在PLC设备IP、访问密码、Token密钥，泄露至Git仓库属于重大生产事故，5分钟即可完成接入
2	SAST完整官方规则集（semgrep引入OWASP Top10/安全审计规则）	仅7条自研业务规则，无通用漏洞规则	＜10%	必补	当前仅校验内部业务铁律，通用注入、权限、加密漏洞完全无防护
3	依赖漏洞强制阻断（govulncheck，漏洞直接阻断CI/本地门禁）	dotnet漏洞扫描无退出码校验，Go无依赖漏洞检测	20%	建议补	现有漏洞扫描仅输出日志，发现高危依赖不会阻断提交，形同虚设
4	SBOM物料清单自动生成（syft/cyclonedx）	无	0%	可选	工业客户无强制合规审计要求，优先级极低
5	容器镜像漏洞扫描（trivy）	项目无Docker交付镜像	0%	暂缓	项目交付形态非容器，无需落地

🟡 第二类：代码质量深度管控（大厂标配，当前部分缺失）

序号	大厂标准实践	项目现状	成熟度	是否建议落地	落地判断
6	golangci-lint完整25+ linter套件	仅启用13个，缺失循环复杂度、错误包装、未使用参数等关键检查	50%	必补	已纳入施工计划，需同步扩容linter配置，不止单纯接入脚本
7	单元测试覆盖率强制门槛（80%基线门禁）	仅支持覆盖率采集，无阈值阻断，Go无覆盖率采集逻辑	15%	建议补	工业项目业务场景复杂，初期覆盖率难以达标，先采集数据，后期再设置硬性门槛
8	Go性能基准benchmark自动化校验	无任何基准测试管控	0%	锦上添花	采集吞吐量为核心指标，可针对核心链路补充，非强制落地项
9	.editorconfig全语言统一规范	仅C#配置，Go/YAML/JSON/PowerShell/Markdown无统一缩进、编码规范	40%	建议补	仅需补充少量配置，成本极低，统一全项目编码风格

🟡 第三类：协作流程治理（大厂标准化流程基石，当前空白）

序号	大厂标准实践	项目现状	成熟度	是否建议落地	落地判断
10	CODEOWNERS代码所有权自动评审指派	无配置	0%	建议补	多人协作场景下，修改S7驱动、采集核心代码自动指派对应负责人评审
11	提交签名校验（GPG/SSH）	完全未启用	0%	可选	单人/小团队开发模式，Gitee虽支持但无强合规需求，优先级低
12	commitlint提交信息规范强制校验	无commit-msg钩子，提交信息无机器约束	0%	建议补	当前人工提交风格已规范，固化为机器强制校验，避免杂乱提交日志
13	CHANGELOG语义化版本管理	无变更日志、无git版本标签	0%	锦上添花	客户交付版本追溯有价值，当前迭代阶段非核心需求

🟡 第四类：门禁机制底层硬缺陷（自身强项体系存在隐蔽漏洞）

序号	大厂标准实践	项目现状	成熟度	是否建议落地	落地判断
14	门禁校验失败强制阻断（硬fail，无静默吞异常）	多处脚本使用try-catch、异常容错吞掉校验失败，漏洞扫描无退出码校验	60%	必补	最隐蔽致命缺陷：校验工具执行失败不会阻断提交，形成「假门禁」，看似全量校验，实则无法拦截缺陷，不如不部署
15	pre-commit通用标准化框架	仅Cursor自研hooks，无跨IDE通用框架	30%	建议补	当前自研Git Hook方案可等价替代，大厂框架仅作为优化备选，非强制
16	CI流水线作为唯一合规底线	云端CI完全失效，Gitee不兼容GitHub Actions	0%	已在解决	本次整套本地Git门禁方案核心目标，弥补云端CI缺失短板

最高优先级隐蔽硬伤详解（第14项，致命缺陷）

现有run-static-analysis.ps1脚本多处逻辑会静默吞掉校验失败，导致门禁失效：

L26：dotnet format格式化校验包裹try/catch，格式化失败直接跳过，不阻断提交
L4

第六轮：实现MCP

结合具体项目实现

第七轮：结合IDE事件硬化约束和规则

一、事件能力对照表

事件	能否 deny(硬拦)	能否注入文本	可用字段
preToolUse	✅ 已验证可行	✅	permission:deny + agent_message
beforeShellExecution	✅ 已验证可行	✅	permission:deny + agent_message
beforeSubmitPrompt	❌ 无法硬拦截	✅	仅 additionalContext
stop	❌ 仅支持续聊，不可阻断流程	✅	followup_message(上限3次)
SessionStart	❌	✅	additional_context

二、待落地规划问题

规则落地改造
现有 mdc\铁律、rules\agent.md 内全部项目规范、硬性约束，是否可依托上表IDE内置事件统一落地管控？
需全量梳理文档规则，做标准化落地规划，彻底替代纯口头约束。
工程配置核查
项目配置内是否已完成 skills 路由相关配置？

posted @ 2026-07-28 18:29 GroundSoft 阅读(4) 评论(0) 收藏举报

刷新页面返回顶部

DinAction

第三纬度——ZY

DevOps+AI 代码工程场景建设系列之——增强CI流水线代码检测（一）

Maiyata 项目AI编程质检体系全流程分析文档（标准Markdown整理版）

第一轮：初探

项目AI编程设置 — 现状评估与改进建议（2026 视角）

一、总体评价

二、🔴 高优先级改进（投入小、回报大）

1. CI 漂移 — GitHub Actions 与本地harness严重脱节（核心缺口）

2. 错题本单点风险 — server-memory MCP架构脆弱

三、🟡 中优先级改进（结构性长期收益）

3. 缺失2026核心MCP能力 — 代码图谱约束与自动化测试生成

4. Skills体系与superpowers双体系并行冲突问题

四、🟢 锦上添花（按需落地，非强制）

5. 可观测性缺口 — Collector/Desktop未落地OpenTelemetry全链路追踪

6. 文档治理机械化体系完善，补充轻量化ADR架构决策流程

五、优化方案总览矩阵

六、仅落地单一项最优选择

第二轮：面向业务人员简化方案（通俗化表达）

核心诉求

📋 工作报告：给项目装上"自动质检门禁"

一、现存核心问题（一句话总结）

三层真实现状拆解

真相1：云端GitHub自动化配置完全失效

真相2：本地质检依赖手动执行，存在大量绕过通道

真相3：项目核心铁律约束彻底失去保障

二、整体改造方案（通俗描述）

方案一句话总结

双闸门禁运行逻辑（地铁进站类比）

双层门禁设计理由

三、改造前后开发场景对比

真实场景示例

四、落地5项具体工作（通俗拆解）

1. 新建快速校验脚本

2. 搭建两道Git闸门脚本

3. 一键安装启用脚本

4. 更新项目说明文档

5. 全流程验证测试

五、工作量、风险与边界说明

预估工作量

风险应对方案

明确不实施的边界（无额外改造）

六、方案总结一句话

方案极简摘要：本地Git自动质检门禁

背景核心问题

核心双层架构

新增/修改文件清单（4个新增文件 + 2份文档更新，无业务代码改动）

落地核心价值

验收验证场景

明确不做范围

工作量预估

第三轮：标准化落地设计规格文档（可直接交付实施）

前置说明

设计规格：Maiyata 项目自动质检门禁(本地 Git Hooks)

第一部分：三层咬合式质检整体架构

1.1 架构流程图

1.2 三层架构职责边界（无重叠、互补设计）

第二部分：完整校验清单（commit/push分层）

2.1 快挡 pre-commit（≤5秒，仅静态校验，无编译/单元测试）

A组：文档-代码真相一致性校验（6项）

B组：Cursor Hooks自检（15项，A4自动调用verify-hooks.ps1）

C组：文档治理规范校验（12项，A4自动调用verify-doc-governance.ps1）

D组：SaaS边界静态校验（6项，快挡跳过编译自检selfcheck）

2.2 慢挡 pre-push（3–5分钟，全量完整校验）

2.3 快慢挡核心对比表

第三部分：落地文件明细与各文件精准职责

3.1 新增/修改完整文件树

3.2 各文件精准职责说明

文件1：scripts/quality/run-quality-fast.ps1（快挡编排器）

文件2：githooks/pre-commit（第一道提交闸门）

文件3：githooks/pre-push（第二道推送闸门）

文件4：scripts/install-git-hooks.ps1（一键启用脚本）

3.3 关键技术风险与内置应对方案

第四部分：落地后可量化验证价值

4.1 核心价值1：彻底封堵终端绕过漏洞

4.2 核心价值2：缺陷本地即时暴露，前置质量拦截

4.3 核心价值3：标准化团队质量约束，新环境零配置

4.4 核心价值4：全局唯一校验标准，消除规范分裂

4.5 核心价值5：完全可逆、零侵入改造

第五部分：验收标准（落地后现场验证5项场景）

2. 错题本单点风险 — `server-memory` MCP架构脆弱

文件1：`scripts/quality/run-quality-fast.ps1`（快挡编排器）

文件2：`githooks/pre-commit`（第一道提交闸门）

文件3：`githooks/pre-push`（第二道推送闸门）

文件4：`scripts/install-git-hooks.ps1`（一键启用脚本）

新建`harness.yml`流水线分层设计（所有PR强制执行）