日常工作知识库

Appearance

SpecFlow AI IDE 规制加载原理与三重锁死注入架构 (v0.13.46) ​

文档类型：SpecFlow AI 工程化架构与 Agent 治理规范
归档路径：/site/ai/specflow-ide-rule-injection-architecture.md
适用对象：AI Coding 架构师、工具链研发、AI IDE 接入工程师
维护团队：58 业财研发部 · SpecFlow 架构组
更新时间：2026-08-14

📌 一、 背景与核心问题 ​

在基于 LLM 的 AI Coding 工具链落地过程中，主流 AI IDE（如 Antigravity、Cursor、Claude Code 等）对工作区上下文与 Rules 的参考加载机制存在以下差异：

  1. System Prompt 全局级：工作区根目录的 AGENTS.md 或 .agents/AGENTS.md 会被绝大多数 IDE 无条件读取作为最高优先级系统规则；
  2. Sub-Rules 散落子规制：物理存在于 .agents/rules/*.rule.md 下的 14+5 细分规制，若技能未显式指示读取，简单 Agent 容易产生上下文漏读 (Rule Dropping)。

为保障 58 部门级 5 大安全与质量规制（秘钥安全、金额精度、异常防吞噬、双审查门禁、文档 Push 隔离）在任何 AI IDE 中 100% 规则无死角硬拦截，SpecFlow 建立了 三重锁死规制注入体系 (Triple-Lock Rule Ingestion Architecture)。

🛡️ 二、 三重锁死规制注入体系架构 (Triple-Lock Architecture) ​

text
       ┌────────────────────────────────────────────────────────┐
       │ 1. 规范仓 .agents/agents.md 自动同步全局 5 大防线摘要   │ 👈 IDE 打开立刻生效 (Global System Prompt)
       └───────────────────────────┬────────────────────────────┘
                                   │
       ┌───────────────────────────▼────────────────────────────┐
       │ 2. 子技能 SKILL.md 声明 Pre-Execution 读取 .agents/rules  │ 👈 AI 斜杠技能调用时生效 (Skill Directive)
       └───────────────────────────┬────────────────────────────┘
                                   │
       ┌───────────────────────────▼────────────────────────────┐
       │ 3. CLI 静态引擎 (specflow review) Node.js 物理读取比对   │ 👈 物理命令行门禁卡点 (Physical Engine)
       └────────────────────────────────────────────────────────┘

锁死 1：规范仓 agents.md 全局防线强同步 ​

当通过 specflow init 初始化或 specflow doctor --fix 诊断时，CLI 自动将 5 大部门级规制摘要物理写入规范仓的 .agents/agents.md 顶层：

  • SEC-001：秘钥安全规制
  • FIN-002：BigDecimal 金额精度保护规制
  • QUAL-005：异常吞噬禁止规制
  • GATE-003：阶段审查双门禁规制
  • DOCS-001：物理 Push 隔离约束

哪怕 AI IDE 仅装载了顶级的 agents.md，也能在第一秒继承这 5 大硬规制！

锁死 2：AI 技能 (SKILL.md) 声明物理 docs/ 与 rules/ 双重加载 ​

在 specflow-specify、specflow-plan、specflow-task 等全量子技能 Prompt 的 Pre-Execution 卡点中，硬编码下达如下物理指令：

“Agent 在执行任何物理代码生成或计划修改前，必须物理 view_file 调阅规范仓下的 docs/projects/<project-name>.md 与 docs/architecture/codegraph.json 物理图谱节点，以及 .agents/rules/*.rule.md 防线，绝对禁止脱离物理 docs/ 架构盲目猜测代码组件！”

锁死 3：CLI 静态引擎 (specflow review) 物理硬编码读取 ​

命令行工具（如 specflow review / specflow task）绝不依赖大模型的上下文记忆，而是通过 Node.js 物理读取 .agents/rules/*.rule.md 文件内容，进行 AST 与正则比对计算得分，确保门禁逻辑硬性判阻。

🛠️ 三、 SpecFlow update 自更新机制与私有源配置 ​

在终端运行 specflow update 时，针对 58 部门私有 NPM 源缺少第三方依赖（如 chalk）导致 404 升级失败的问题，自更新引擎内置了定向 Registry 隔离语法：

bash
# 仅针对 @specflow 作用域指定私有源，三方公共依赖走默认/镜像源
npm install -g @specflow/cli@latest --@specflow:registry=http://ires.58corp.com/repository/npm/

运行 specflow update 可同时完成全局 CLI 升级与规范仓 .agents/ 技能热重载覆写。