仓库元知识完整性扫描器 (Scan Meta-Project)

仓库元知识完整性扫描器 (Scan Meta-Project) 是做什么的？

用于对现有元项目设置进行快速扫描或深度完整性审计的操作技能，无需破坏性重新初始化。

该技能以两种模式运行：

• --shallow (快速健全性检查): 验证根 AGENTS.md 和5个知识分片的存在性及非空性，执行边界守卫 (check_boundaries.py --audit-tree) 实现100%文件覆盖，并检查任务新鲜度。
• --deep (核心深度检查与漂移检测): 运行所有浅层检查，调用核心检查清单审核关键运行时模块，委托 sync-architecture 进行组件/数据流同步，审计 weak_spots.md 中的技术债务，并执行本地集成测试。

---

何时调用该技能

• 用户请求：“scan-meta-project”、“scan meta project”、“инспекция мета-знаний”、“чекни покрытие”、“audit meta-knowledge”、“check boundaries coverage”、“найди слепые зоны”、“verify slices”。
• 预发布验证、PR审查，或在代理会话之外进行大量更改后恢复开发时。
• 由 init-meta-project 在初始化结束时自动调用。
• 主要指定角色：agent-quality-guardian（紧凑三拓扑）或 agent-meta-guardian（扩展角色拓扑），或由用户直接调用。

---

执行步骤

阶段1：模式确定与目标解析

1. 从用户提示中识别调用模式，默认使用 --shallow：
   • --shallow：常规完整性检查、边界覆盖验证、任务新鲜度。
   • --deep：完整架构漂移检测、核心检查清单、测试执行。
2. 定位边界守卫脚本：
   • 优先使用 .agents/scripts/check_boundaries.py（目标仓库布局）。
   • 回退到 scripts/check_boundaries.py（元项目布局）。
   • 如果两个脚本都不存在，则根据 boundaries.md 的 glob 模式手动验证边界。

---

阶段2：浅层扫描 (--shallow)

1. 通行证完整性：
   • 验证根 AGENTS.md 的存在性。
   • 确保第1节包含北极星和不变规则（Circuit Breaker、Default Deny）。
   • 确保第2、3、4、5节已填充，没有占位符标签（{{...}}）。
2. 知识分片审计：
   • 验证 .agents/project_knowledge/ 中的5个规范分片：
     • architecture.md（组件和数据流）。
     • boundaries.md（职责区域）。
     • weak_spots.md（脆弱模块和风险）。
     • observations.md（5列观察表）。
     • tasks.md（活跃目标和清单）。
3. 边界覆盖（零未映射目录规则）：
   • 运行自动边界守卫审计：

     python .agents/scripts/check_boundaries.py --audit-tree
     # 回退：python scripts/check_boundaries.py --audit-tree
     

   • 如果报告了任何未映射的文件或目录，请将其视为黑区违规。立即标记它们以包含到 boundaries.md 中。
4. 任务寄存器检查 (tasks.md)：
   • 验证活跃目标是否清晰，已完成项目是否标记为 - [x]。

---

阶段3：深度扫描 (--deep)

当使用 --deep 执行时，代理将运行所有阶段2检查，然后进行：

1. 核心检查清单（关键模块）：
   • 数据库与存储： 读取主要模型/仓库文件。检查模式耦合、迁移和单体增长。
   • 外部客户端与API： 读取集成（AI SDK、HTTP客户端）。检查超时设置、断路器与错误传播。
   • 容器化与CI： 读取 Dockerfile、docker-compose*.yml、.github/workflows/。验证构建矩阵和安全标志。
   • 入口点与UI： 读取主要路由器、CLI入口点和命令处理程序。检查平台负载约束和输入验证。
2. 架构漂移检测（委托给 sync-architecture）：
   • 不要重复自定义代码解析逻辑。调用过程式技能 sync-architecture：
     • sync-architecture 对所有 local_repo_data 块执行预飞行保留。
     • 使用当前组件和端到端数据流更新 .agents/project_knowledge/architecture.md。
3. 风险与债务重新校准 (weak_spots.md)：
   • 检查 weak_spots.md 中的现有项目：如果先前记录的技术债务已解决，则标记为已解决或删除它。
   • 如果在核心检查期间发现了新的脆弱耦合或架构瓶颈，请记录它们。
4. 自动测试运行：
   • 使用标准测试发现执行项目测试套件：

     python -m unittest discover -s tests -p "test_*.py" -v
     # 或特定堆栈的运行器（例如 pytest、npm test、cargo test）
     

---

阶段4：机会性刷新与报告

1. 回填已识别差距（读取 + 机会性刷新）：
   • 将发现的未映射路径原子写入 boundaries.md（在 <!-- local_repo_data:boundaries --> 内）。
   • 使用新的子任务或完成的里程碑更新 tasks.md。
   • 将新解决的环境怪癖记录到 observations.md 中。
2. 提交扫描报告： 向用户展示简洁摘要：

   ### 🔍 扫描报告（元项目扫描器）
   - **模式：** `--shallow` | `--deep`
   - **通行证与分片：** 5/5个分片存在，AGENTS.md 有效
   - **边界覆盖：** 100%已映射（或检测到N个未映射路径）
   - **架构漂移：** 同步（或已通过 sync-architecture 更新）
   - **已识别行动项：** [具体建议1-3条列表（如有）]