x-rw-togaf-l1

> TOGAF AI Prompt Chain — 五层 AI System Prompt 链，按 TOGAF Phase A 方法论半自动化需求分析。

版本: V1.5 (Prompt) / V1.0.0 (CLI) | 功能状态: 全5层完成 + CLI 自动化工具 + draw.io 模块化图示拆分 + AI 消费子集产出 + Diagram-as-Contract 契约提取（D1-D5）+ 契约 → 代码骨架生成器（D1/D2/D3）

> 📖 用户指南: 详见 README.md
> 🤖 AI参考: 详见 references/ 目录

🔄 会话启动行为

本 Skill 为 Prompt Chain 类型，无持久化会话状态。每次调用时：
1. 加载对应层级的 System Prompt（prompts/L{N}-*.md）
2. 按 L1→L2→L3→L4→L5 顺序依次执行
3. 推荐通过 x-rw-loopengineering-o2 编排层调用

📊 logs/ 行为记录

每次执行结束必须执行

1. 记录执行指标到 logs/executions/{timestamp}.json
2. 格式参考 logs/README.md 行为记录规约

快速开始

Prompt 方式

按 L1→L2→L3→L4→L5 顺序依次使用：
1. 将 prompts/L1-战略锚定器-SystemPrompt-V3.0.md 作为 System Prompt
2. 输入自然语言需求，获取《需求决策书》+ 决策流程图（1 文件）
3. 将 L1 输出 + L2 Prompt 输入，获取《上下文关系图》+ N 张能力域上下文图
4. 依此类推至 L5

推荐通过 x-rw-loopengineering-o2 编排层调用，享受自动 Loop 控制和收敛检测。

CLI 方式（V1.0 新增）

togaf init --project=项目名称        # 初始化目录
togaf run L1 --project=项目名称        # 输出 LLM 调用请求
togaf run L2 --project=项目名称        # 输出 LLM 调用请求
togaf status --project=项目名称       # 查看执行进度
togaf check-anchors --project=项目名称  # 锚点链式一致性校验（V3.0）
togaf export-ai-subset --project=项目名称  # 导出 AI 消费子集（V3.0）
togaf config                        # 查看配置

契约 → 代码骨架生成（V3.0 新增）

各层 ingest 自动提取 drawio 契约（*.drawio.contract.json），代码骨架生成器消费契约产出可开发代码：

from togaf.codegen.generator import generate_state_machine_skeleton
files = generate_state_machine_skeleton(d1_contract)  # {对象名: {"xxx_state_machine.py": "..."}}

排查模板渲染问题：设置 TOGAF_CODEGEN_LOG=DEBUG 环境变量（或 configure_logging("DEBUG")），
输出每次渲染的上下文键、耗时与失败时的模板片段。

功能

架构

• Loop 控制委托至 x-rw-loopengineering-o2（宿主编排）
• 每层产出文本分析 + 模块化 draw.io XML 可视化图示（L2-L4 按模块拆分为文件组）
• 层间通过锚点保险箱只读传递（铁律+建议+术语+待定项）
• 三级门禁（轻微自动修正/严重人工介入/致命回溯）

文件结构

prompts/     — 5层 System Prompt + E1-E7 实现层输出模板（执行指令层："怎么做"）
    ├── L1-战略锚定器-SystemPrompt-V3.0.md
    ├── L2-能力地图器-SystemPrompt-V2.0.md
    ├── L3-流程导航器-SystemPrompt-V2.0.md
    ├── L4-实体建模器-SystemPrompt-V2.0.md
    ├── L5-规格精炼器-SystemPrompt-V3.0.md
    └── 实现层模板/ — E1-E7 输出模板（功能说明书/数据库/API/前端原型/权限/任务清单/测试用例）
src/togaf/   — CLI 源码（V1.0 新增，含 diagram 契约提取 + codegen 骨架生成）
tests/       - pytest 测试套件（191 个用例，门禁 5/5 通过）
scripts/     — 门禁检查脚本 check-gates.py
pyproject.toml — CLI 项目配置
references/  — TOGAF 参考 + drawio 规范 + LoopEngine 集成契约（参考规范层："按什么标准做"）
    ├── diagram_contract_schemas/ — D1-D5 契约 Schema
    ├── database-design/  — 数据库设计子专题（01 命名字段 / 02 表结构索引 / 03 表关系模型 / 04 数据字典 / 05 反冗余 / 06 评审红线 / 07 安全运维 + E2 自检清单）
    ├── prototype-design/ — 原型制作子专题（01 页面结构 / 02 组件交互 / 03 保真视觉 / 04 可访问性 / 05 追溯 / 06 红线评审 / 07 交付自检 + E4 自检清单）
    ├── test-design/      — 测试设计子专题（01 用例方法 / 02 分层金字塔 / 03 契约接口 / 04 非功能 / 05 数据 fixture / 06 覆盖率门禁 / 07 交付自检 + E7 自检清单）
    ├── human-decision-gate.md — 人工决策门禁机制（C1-C5 人工控制点 + O2 建议单前置 + 可追责签名）
    ├── terminology.md — 术语全称映射表（g1→架构门禁 / g2→规划门禁 / g3→执行验收门禁 / C0→中控台 / L1→战略锚定层 等；人类可读场景必须使用全称）
    └── togaf-l1-参考/   — TOGAF Phase A 对齐确认与参考
logs/        — 执行日志

> 职责分层说明（prompts vs references）：
> - prompts/ = 执行指令层：L1-L5 System Prompt 是流水线直接加载执行的指令（"怎么做"），E1-E7 模板是 L5 输出实现的格式骨架；变更频率高，随 Prompt 迭代。
> - references/ = 参考规范层：专题集（database/prototype/test-design）、契约 Schema、门禁机制是 L5 Prompt 引用与人工决策查阅的标准（"按什么标准做"）；变更频率低，沉淀稳定规范。
> - 二者不合并：prompts/ 被流水线按文件加载，references/ 被 Prompt 按路径引用（L5 引用 6 处）与 C0 门禁调用（如 suggestion-template.md）；合并会导致引用路径全部失效。

关键约束规则

1. 顺序执行: L1→L2→L3→L4→L5，不可跳过或乱序
2. 锚点保险箱只读: 下游层加载上游产出物后只读引用，不可修改
3. 门禁不可跳过: 每层的锚点合规声明必须输出
4. 图示模块拆分: L2-L4 必须按模块维度拆分，不可合并为单图（详见 references/drawio-conventions.md）
5. 术语一致性: 全链路必须使用锚点保险箱术语表统一定义
6. 🔴 Draw.io XML 质量: 生成任何图示前必须先读取 references/drawio-conventions.md §XML质量强制规约；输出后必须通过 6 项自检锚点（①id="0"/"1"存在 ②实体编码 ③style格式 ④perimeter匹配 ⑤顶点先于边 ⑥无XML注释）

异常处理

> 📖 完整异常处理: 各层 Prompt 文件中的「异常处理汇总」章节

产出契约

输出结构

每层分析必须输出三类产物：

V3.0: Diagram-as-Contract

ingest 时从每张 drawio 图示自动提取 JSON 契约（*.drawio.contract.json），供下游消费：

契约消费端（代码骨架生成器）见「契约 → 代码骨架生成」章节。

L5 实现层 E1-E7（开发就绪产物）

L5 完成后除层级文档外，必须产出 7 份 E 系列开发就绪产物（可直接驱动开发，可交互原型即验收基线）：

> 强制约定（P2-1 格式统一）：E 系列产物输出为 Markdown（E{n}-名称.md），与 L5 Prompt 模板一致；可选增强为自包含 HTML（E{n}-名称.html，用于 C5 原型验收的可交互原型）。G1 门禁按 Markdown 文件名（E1-~E7-）检查完整性。
> （check_output togaf / check_g1 的 E1-E7 完整性检查项已按此约定执行）；缺失任一 E 产物将导致 G1 门禁拦截。
>
> P2-4 按需生成 + 清单校验（2026-08-09）：E1-E7 按项目实际需要生成——无数据库需求可输出 E2 无（纯前端/无持久化） 占位说明，但清单必须完整；L5 结束时运行 check_output togaf 校验 E1-E7 清单齐全且无孤儿（E 系列完整性由架构门禁拦截）。各 E 产物一致性自检：
> - E1: FR 须有来源 REQ（check_traceability.py REQ→FR 校验）
> - E3: 示例一致性自检（check_e3_consistency.py E3-01~06）
> - E4: 原型制作规范 N1-N6 自检（模板 4.5 清单：零依赖单文件 / 保真度分级 / 主题一致 / 可访问性 / 交互覆盖 / 动效含蓄）
> - E6/E7: FR-GWT→Task→TC 双向闭合（check_traceability.py）

> 🔴 人工决策门禁：E1-E7 产出后经 C2 架构门禁（G1） O2 审计质询，E4 可交互原型经 C5 原型验收门禁 人工签字后方可作为验收基线。完整 C1-C5 控制点、O2 建议单规范与一页式门禁签核单（references/gate-signoff-template.md）见 references/human-decision-gate.md。

L5 额外产出

L5 完成后额外产出 AI 消费子集（JSON），包含：

• business_capabilities — 业务能力地图（从 L2 提取）
• constraint_matrix — 约束矩阵（从 L3-L4 提取）
• architecture_decisions — 架构决策记录（从 L4 提取）

AI 消费子集的 Schema 见 references/ai_consumption_subset_schema.json。

锚定机制

AI 消费子集生成后，由 scripts/generate_anchor.py 计算 SHA-256 锚定哈希。下游 Loop 消费时必须校验此哈希。

接口契约

TOGAF→Loop 的数据流契约详见 references/togaf-loop-interface-contract.md。

不产出（L1-L4 分析层）

L1-L4 分析层不产出（V3.0 与 L5 实现层区分）：

• 执行计划、时间排期、Gantt 图（E6 开发任务清单由 L5 实现层输出）
• 技术实现方案、代码、配置（E1-E5/E7 规格由 L5 实现层输出）
• 资源分配、团队分工

> ⚡ V3.0 例外：L5 实现层必须产出 E1-E7 开发就绪产物（见上方「L5 实现层 E1-E7」章节），C0 全流程中 L5 未产出 E1-E7 视为交付不完整，G1 门禁拦截。

兼容性

• 依赖于 x-rw-loopengineering-o2 >= v10.3（编排层）
• 产出可被 x-rw-loopengineering-o2 的 KDNA 注入阶段消费
• AI 消费子集可被 x-rw-graphengineering-g3 的 Plan 编译器间接消费（经 Loop 转换）