vlv-code/init-meta-project

智能体环境初始化与升级（元项目初始化和审计）

为任何仓库准备智能体工作流的自主技能。自动检测是否已存在 meta-project 结构，防止覆盖累积数据，并执行安全升级至最新标准，或从头引导该结构。

基于持续/机会性刷新原则：在访问元知识片段时，智能体必须填补空白并维护项目的统一视图。

---

何时调用技能

• 用户请求：“为智能体准备仓库”、“初始化元项目”、“检查 agents.md”、“更新智能体结构”、“刷新元知识”。

---

执行步骤

阶段 0：检查现有元项目环境

在执行任何写入之前，检查元项目组件的存在：

1. 检查仓库根目录的 AGENTS.md。
2. 检查 .agents/project_knowledge/ 和 .agents/skills/ 目录。

场景 A：结构已存在（审计与安全升级模式）

如果仓库中已存在 AGENTS.md 或 .agents/ 文件夹：

1. 禁止破坏性覆盖：
   • 严格禁止删除或覆盖 observations.md —— 所有累积的观察必须保留。
   • 禁止删除现有 AGENTS.md 中的自定义不变项和用户描述。
2. 标准合规性审计：
   • 检查 AGENTS.md 是否包含“原则与架构方向（North Stars）”部分。如果缺失，则添加而不修改服务目的和不变项。
   • 检查 AGENTS.md 中的指令协议是否包含“访问 + 机会性刷新”链接。如果过时，更新该部分。
   • 检查 boundaries.md 中的 glob 模式使用、数据目录保护（data/**、*.db）、将格式化/渲染模块分配给黄区，以及默认拒绝（黑区）不变项的存在。
   • 检查 observations.md 表中是否存在 Category 列。如果使用传统的 4 列格式，更新表头而不删除数据行。
   • 验证 .agents/skills/ 中 SKILL.md 文件（record-observation、sync-architecture、ground-meta-project）的新鲜度。
3. 安全增强：
   • 创建缺失的切片（例如，如果 weak_spots.md 不存在）。
   • 在 AGENTS.md 中为仓库补充新的专业化栈技能技能注册表。
4. 升级报告：
   • 告知用户：“检测到现有元项目。已审计并升级至最新标准，未丢失累积数据。”

---

场景 B：初始设置（清洁脚手架模式）

如果不存在结构，执行标准的两遍算法：

第一遍：快速扫描和骨架生成（快速且高层级）

1. 对仓库根目录进行快速检查： 列出根目录并识别：

   • 清单文件：package.json、pyproject.toml、go.mod、Cargo.toml、requirements.txt、pom.xml、docker-compose.yml。
   • 核心目录：src/、app/、tests/、migrations/、scripts/、data/。
   • 零未映射目录规则： 枚举仓库根目录中的所有顶层源目录。严格过滤掉 .gitignore 路径、VCS 元数据和标准构建/包/测试缓存（.git、node_modules、.venv、venv、dist、build、coverage、__pycache__、.pytest_cache、.idea、.vscode）。每个剩余的顶层源目录必须在 boundaries.md 中明确说明并映射到绿、黄或红区（未映射目录默认属于默认拒绝/红区）。
   • 从 README.md（如果存在）获取项目名称、目的和核心概念。
   • 从 .env.example（如果存在）获取所需键和依赖项。

2. 识别技术栈和核心原则：

   • 制定简洁的栈字符串（例如，Python 3.12, FastAPI, uv, pytest, Docker）。
   • 强调 2-3 个基线方向（例如，架构简单性、严格类型、数据不可变性、离线优先）。

3. 创建目录结构： 创建目录：

   • .agents/project_knowledge/
   • .agents/project_knowledge/archive/
   • .agents/skills/record-observation/
   • .agents/skills/sync-architecture/
   • .agents/skills/ground-meta-project/
   • scripts/

4. 部署捆绑的元项目技能和运行时脚本： 将以下嵌入模板中的 SKILL.md 文件写入：

   • .agents/skills/record-observation/SKILL.md
   • .agents/skills/sync-architecture/SKILL.md
   • .agents/skills/ground-meta-project/SKILL.md 将零依赖边界和压缩自动化脚本部署到仓库 scripts/：
   • scripts/check_boundaries.py（边界门 CLI）
   • scripts/compact_memory.py（上下文轮盾与内存压缩器）

5. 创建初始知识切片草稿： 写入 .agents/project_knowledge/ 中的文件：

   • observations.md（5 列表格，包含第一行初始化；使用跨平台命令示例，例如：python -m pytest）。
   • boundaries.md（区域模板，包含基本 glob 模式：格式化在黄区，数据在红区）。
   • weak_spots.md（基线风险注册表结构）。
   • architecture.md（基线架构脚手架）。
   • tasks.md（活动目标、团队检查表和委派注册表）。

第二遍：仓库深度挖掘、原则与 Shell 技能

1. 强制性核心检查清单： 禁止在未读取关键模块源代码的情况下，用样板模板填充 weak_spots.md 和 architecture.md！ 智能体必须对以下关键区域执行 read_file 调用：

   • 存储与数据库： 读取主要数据访问模块（storage.py、仓库、模型）。评估单体大小（LOC 计数）、模式耦合和迁移设置。
   • 外部 API 与服务客户端： 读取集成模块（AI 模型 SDK、外部客户端）。检查重试、超时、回退和全局单例。
   • 容器化与运行时： 读取 Dockerfile、docker-compose.yml 和 CI 工作流（.github/workflows/）。检查系统二进制依赖（FFmpeg、实用程序）、用户权限（UID）和数据卷挂载。
   • 用户界面与输入： 读取键盘/路由器模块。检查平台约束（例如，Telegram callback_data 的 64 字节限制、FSM 状态、破坏性操作确认）。

2. 交互式校准面试（编码的两问题协议）： 自动化扫描识别代码中存在的内容，但无法检测未记录的历史上下文、业务不变项或生产敏感性。智能体通过 ask_question 工具或直接交互提示进行简短的结构化交互式面试，精确提问 2 个重点问题：

   • 问题 1（North Stars 与核心不变项）： "Какие ключевые архитектурные инварианты, бизнес-правила и ограничения продакшена (North Stars) нельзя нарушать при любых доработках?"（哪些核心架构不变项、业务规则和生产约束在任何修改中都绝不能违反？）
   • 问题 2（红区与敏感路径）： "Какие специфические каталоги или модули (биллинг, БД, криптография, ключи, легаси) являются критическими и должны быть заблокированы в Red Zone?"（哪些特定目录或模块（计费、数据库、加密、密钥、遗留代码）是关键性的，必须严格放入红区？）

   处理答案：

   • 用户对问题 1 的答案立即集成到 AGENTS.md 的第 1 节（“原则与架构方向 (North Stars)”）中。
   • 用户对问题 2 的答案在单次刷新之前映射到 boundaries.md 的红区中。
   • 如果用户跳过或提供空响应，则优雅地回退到从核心检查清单推断出的方向。

3. 校准项目概念和原则： 综合检查清单发现和面试答案，形成 2-3 个简洁的架构方向（North Stars），防止矛盾的智能体行为。

4. 从智能体 Shell 注册表匹配栈技能： 将仓库栈映射到智能体环境中可用的专业技能（~/.gemini/config/skills/ 和内置技能）：

   • Python / uv / ruff → python-pro
   • FastAPI → fastapi-pro
   • TypeScript / JavaScript → typescript-expert
   • Next.js → nextjs-best-practices
   • Docker / Dockerfile / Compose → docker-expert
   • PostgreSQL / SQL / migrations → postgresql-optimization, sql-pro
   • Kubernetes / Helm → kubernetes-architect
   • Telegram bot / aiogram → telegram-bot-builder
   • CI/CD pipelines → github-actions-creator
   • Clean code & review → clean-code, code-reviewer

5. 校准边界（boundaries.md）： 为实际项目目录细化 .agents/project_knowledge/boundaries.md 中的 glob 模式：

   • 默认拒绝 / 100% 路径覆盖（零未映射目录）： 确保每个未被忽略的顶层源目录明确分配到一个区域。添加默认拒绝（黑区）规则：任何未映射路径默认严格为红区。
   • 测试区域区分：
     • 为新功能创建新测试 —— 绿区。
     • 现有回归测试套件（tests/**, *_test.*, *.spec.*）—— 严格黄区，并附带禁止削弱断言（assert/expect）的不变项。
     • 架构完整性、API 契约和数据模式测试（*integrity*, *contract*, *schema*, E2E）—— 严格红区。
   • 格式化/转义模块和模板引擎 —— 严格黄区。
   • 数据库文件和目录（data/**, *.db, *.sqlite*）—— 严格红区。
   • 用实际迁移路径替换占位符路径（alembic/versions/**, prisma/migrations/** 等）。
   • 用实际子系统位置替换路由/控制器路径。

6. 风险与弱点分析（weak_spots.md）： 记录在核心检查期间识别的具体技术债务（单体、单例）、外部运行时依赖（Redis、Postgres、消息代理、系统实用程序如 FFmpeg）、平台约束以及来自 .env.example 的必需变量。

7. 填充架构切片（architecture.md）： 基于检查的核心模块描述高层级栈、子系统、后台任务/调度器和数据流。

   • 条件性端到端数据流： 当检测到多层、客户端-服务器、API 或 UI 组件时，生成“端到端数据流（预飞行流追踪）”模式（映射 [Origin: UI/CLI/Event] ➔ [Transport: API Route / Message] ➔ [Domain / Storage: Persistence] ➔ [Assembly / Packager] ➔ [Consumer: Client / Daemon]）。对于没有外部通信或持久层的纯单层 CLI 或 stdlib 库，省略此部分以避免上下文膨胀。

8. 内存中合成刷新协议： 智能体不将中间草稿写入磁盘。所有不变项在第一遍和第二遍期间在工作内存中合成，之后文件以严格的从下到上顺序写入：

   • 步骤 A：预安装的技能（.agents/skills/record-observation/、sync-architecture/ 和 ground-meta-project/）和自动化脚本（scripts/check_boundaries.py、scripts/compact_memory.py，如果共享仓库设置）。
   • 步骤 B：知识切片（observations.md -> boundaries.md -> weak_spots.md -> architecture.md）。
   • 步骤 C：根护照（AGENTS.md）—— 严格最后，作为切片和栈技能引用的聚合器。

---

完成与验证

1. 使用 Get-ChildItem -Recurse .agents 或 ls -R .agents 验证已创建/更新的文件。
2. 本地不可见覆盖选项： 如果在外部/客户项目中初始化，或者请求不使用 Git 提交的个人模式：
   • 将 AGENTS.md 和 .agents/ 添加到目标仓库的 .git/info/exclude 中。
   • 验证 git status：元项目文件不得出现在未跟踪文件中。
3. 向用户输出简洁摘要：
   • 执行模式（初始设置与审计并升级；共享与不可见覆盖）。
   • 已创建/更新的文件树。
   • 捕获的项目方向（North Stars）。
   • 链接的栈技能列表。

---

嵌入参考模板

模板：record-observation/SKILL.md

---
name: record-observation
description: >-
  使用此技能将未记录的 bug、环境怪癖、运行时边缘情况或非显而易见的解决方案记录到仓库的 `.agents/project_knowledge/observations.md` 表中。
---

# 在仓库知识库中记录观察

1. 确认 `.agents/project_knowledge/observations.md` 存在。
2. 检查最近 20 行是否有重复。
3. 将条目严格作为单个 Markdown 表行追加：
   `| YYYY-MM-DD | [<category>] | <Path_or_component> | <Brief issue summary/fact> | <Solution or workaround> |`
   类别：`[build]`, `[runtime]`, `[deps]`, `[db]`, `[api]`, `[test]`, `[env]`, `[ci]`, `[boundaries]`, `[orchestration]`, `[decommission]`, `[incident]`, `[init]`，或显式领域标签（例如 `[theme]`）。
4. 如果行数 > 30–40，将已解决的记录归档到 `.agents/project_knowledge/archive/observations-YYYY.md`。

模板：sync-architecture/SKILL.md

---
name: sync-architecture
description: >-
  使用此技能分析仓库模块、依赖项和入口点，并生成或更新 `.agents/project_knowledge/architecture.md`。
---

# 同步项目架构切片

1. 读取依赖项和构建清单。
2. 识别入口点和顶层目录。
3. 识别 3–5 个子系统、它们的角色和数据流。
4. 更新 `.agents/project_knowledge/architecture.md`。
5. 向用户显示更改的简要摘要。

模板：ground-meta-project/SKILL.md

---
name: ground-meta-project
description: >-
  紧急接地和重新校准技能：停止失控的编辑，强制缩小视图，重新读取 AGENTS.md、活动角色护照、boundaries.md 和架构映射，诊断上下文漂移，并重置智能体状态。
---

# 应急元项目接地

1. 停止所有正在进行的编辑（`undo` 未提交的更改）。
2. 更改模型 `thinking` 模式以强制缩小视图。
3. 重新读取基本文档：`AGENTS.md`（角色护照）、`.agents/project_knowledge/boundaries.md`、`.agents/project_knowledge/architecture.md`。
4. 评估当前 Agent 上下文与项目护照方向的漂移。
5. 重新计算任务优先级或终止不兼容的目标。
6. 通知用户，列出已应用的诊断和重新定位。