npm - @wneng/create-keel - Versions diffs - 0.4.0 → 0.4.2 - Mend

@wneng/create-keel 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/dist/index.js +1 -1
package/dist/index.js.map +1 -1
package/package.json +1 -1
package/src/templates/ci-gitee/files/PULL_REQUEST_TEMPLATE.md +15 -2
package/src/templates/ci-github/files/PULL_REQUEST_TEMPLATE.md +15 -2
package/src/templates/docs-skeleton/files/governance-change-tiers.md +135 -76
package/src/templates/root-files/files/AGENTS.md +29 -15
package/src/templates/welcome-html/files/WELCOME.md +39 -0
package/src/templates/welcome-html/files/keel-README.md +28 -0
package/src/templates/welcome-html/files/welcome.html +644 -0
package/src/templates/welcome-html/fragment.yaml +14 -0

package/src/templates/welcome-html/files/welcome.html ADDED Viewed

@@ -0,0 +1,644 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>欢迎使用 keel — <%= it.options.projectName %></title>
+<style>
+  :root {
+    --bg: #fafafa;
+    --fg: #1f2328;
+    --fg-muted: #6e7781;
+    --accent: #0969da;
+    --accent-soft: #ddf4ff;
+    --border: #d0d7de;
+    --code-bg: #f6f8fa;
+    --code-fg: #24292f;
+    --warn-bg: #fff8c5;
+    --warn-border: #d4a72c;
+    --ok-bg: #dafbe1;
+    --ok-border: #2da44e;
+    --nav-w: 260px;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #0d1117;
+      --fg: #e6edf3;
+      --fg-muted: #8d96a0;
+      --accent: #58a6ff;
+      --accent-soft: #0d2d5a;
+      --border: #30363d;
+      --code-bg: #161b22;
+      --code-fg: #e6edf3;
+      --warn-bg: #3a2a00;
+      --warn-border: #d4a72c;
+      --ok-bg: #0d2818;
+      --ok-border: #2da44e;
+    }
+  }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC",
+                 "Microsoft YaHei", "Noto Sans CJK SC", Helvetica, Arial, sans-serif;
+    font-size: 15px;
+    line-height: 1.65;
+    color: var(--fg);
+    background: var(--bg);
+  }
+  .layout { display: flex; min-height: 100vh; }
+  nav.sidebar {
+    width: var(--nav-w);
+    flex-shrink: 0;
+    border-right: 1px solid var(--border);
+    padding: 24px 20px;
+    position: sticky;
+    top: 0;
+    height: 100vh;
+    overflow-y: auto;
+    background: var(--bg);
+  }
+  nav.sidebar h1 {
+    font-size: 18px;
+    margin: 0 0 4px 0;
+  }
+  nav.sidebar .subtitle {
+    font-size: 12px;
+    color: var(--fg-muted);
+    margin-bottom: 20px;
+  }
+  nav.sidebar ol {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    counter-reset: section;
+  }
+  nav.sidebar li { margin: 4px 0; }
+  nav.sidebar a {
+    display: block;
+    padding: 6px 10px;
+    border-radius: 6px;
+    text-decoration: none;
+    color: var(--fg);
+    font-size: 14px;
+  }
+  nav.sidebar a:hover { background: var(--accent-soft); }
+  nav.sidebar a.active {
+    background: var(--accent-soft);
+    color: var(--accent);
+    font-weight: 600;
+  }
+  main {
+    flex: 1;
+    padding: 40px 56px;
+    max-width: 920px;
+  }
+  section { margin-bottom: 56px; scroll-margin-top: 24px; }
+  section h2 {
+    font-size: 22px;
+    margin: 0 0 12px 0;
+    border-bottom: 1px solid var(--border);
+    padding-bottom: 8px;
+  }
+  section h3 {
+    font-size: 17px;
+    margin: 24px 0 8px 0;
+  }
+  p { margin: 12px 0; }
+  code {
+    background: var(--code-bg);
+    color: var(--code-fg);
+    padding: 1px 6px;
+    border-radius: 4px;
+    font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+    font-size: 13px;
+  }
+  pre {
+    background: var(--code-bg);
+    color: var(--code-fg);
+    padding: 12px 16px;
+    border-radius: 6px;
+    overflow-x: auto;
+    font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+    font-size: 13px;
+    line-height: 1.5;
+  }
+  pre code { background: transparent; padding: 0; }
+  table {
+    border-collapse: collapse;
+    width: 100%;
+    margin: 12px 0;
+    font-size: 14px;
+  }
+  th, td {
+    border: 1px solid var(--border);
+    padding: 8px 10px;
+    text-align: left;
+    vertical-align: top;
+  }
+  th { background: var(--code-bg); font-weight: 600; }
+  a { color: var(--accent); }
+  a:hover { text-decoration: underline; }
+  .callout {
+    border-left: 3px solid var(--accent);
+    background: var(--accent-soft);
+    padding: 10px 14px;
+    margin: 16px 0;
+    border-radius: 0 6px 6px 0;
+  }
+  .callout.warn {
+    border-left-color: var(--warn-border);
+    background: var(--warn-bg);
+  }
+  .callout.ok {
+    border-left-color: var(--ok-border);
+    background: var(--ok-bg);
+  }
+  ul, ol { padding-left: 24px; }
+  li { margin: 4px 0; }
+  .badge {
+    display: inline-block;
+    padding: 2px 8px;
+    border-radius: 10px;
+    font-size: 12px;
+    background: var(--code-bg);
+    color: var(--fg-muted);
+    margin-right: 6px;
+  }
+  .badge.tier-0, .badge.tier-1, .badge.tier-2 {
+    background: var(--ok-bg); color: var(--ok-border);
+  }
+  .badge.tier-3 {
+    background: var(--accent-soft); color: var(--accent);
+  }
+  .badge.tier-4 {
+    background: var(--warn-bg); color: var(--warn-border);
+  }
+  .meta {
+    color: var(--fg-muted);
+    font-size: 13px;
+  }
+  details summary {
+    cursor: pointer;
+    font-weight: 600;
+    padding: 8px 0;
+  }
+  details > *:not(summary) { margin-left: 20px; }
+  hr {
+    border: none;
+    border-top: 1px solid var(--border);
+    margin: 24px 0;
+  }
+  @media (max-width: 800px) {
+    .layout { flex-direction: column; }
+    nav.sidebar {
+      width: 100%; height: auto; position: static;
+      border-right: none; border-bottom: 1px solid var(--border);
+    }
+    main { padding: 24px; }
+  }
+</style>
+</head>
+<body>
+<div class="layout">
+  <nav class="sidebar">
+    <h1>📘 keel 速查</h1>
+    <div class="subtitle">
+      <%= it.options.projectName %><br>
+      由 @wneng/create-keel <%= it.scaffolderVersion %> 生成
+    </div>
+    <ol>
+      <li><a href="#welcome">1. 欢迎</a></li>
+      <li><a href="#layout">2. 目录速查</a></li>
+      <li><a href="#concepts">3. 关键概念</a></li>
+      <li><a href="#what-to-do">4. 我要做什么</a></li>
+      <li><a href="#commands">5. 常用命令</a></li>
+      <li><a href="#ai">6. AI 协作</a></li>
+      <li><a href="#more">7. 去哪查更多</a></li>
+      <li><a href="#faq">8. 常见问题</a></li>
+    </ol>
+  </nav>
+  <main>
+    <section id="welcome">
+      <h2>1. 欢迎</h2>
+      <p>
+        本项目由 <strong>keel</strong> 框架生成，采用 <strong>Contract First + Vibe Coding</strong>
+        的协作方式。一句话：
+      </p>
+      <div class="callout">
+        <strong>契约（API / 事件 / 字典 / 错误码）</strong>是真值。代码、文档、测试都围绕契约展开；
+        改契约必须走 SemVer 与 CHANGELOG。AI 与人类协作时，AGENTS.md 是总纲。
+      </div>
+      <p>
+        keel 帮你省掉这些重复劳动：搭目录、配 lint / format / typecheck / 安全扫描、
+        装迁移工具、PR 模板、AI 工具的对接（Kiro / Cursor / Claude Code / Codex）、
+        多团队协作的边界与责任分配。
+      </p>
+      <p>
+        <strong>第一次进项目，按下面顺序看：</strong>
+        §2 看目录布局 → §3 学三个核心概念 → §4 找对应你当前任务的入口 → §5 跑常用命令。
+      </p>
+    </section>
+    <section id="layout">
+      <h2>2. 目录速查</h2>
+      <p>顶层目录每一项一句话即可知道是干嘛的。机器目录写代码，人类目录写文档。</p>
+      <table>
+        <tr><th>目录</th><th>面向</th><th>放什么</th></tr>
+        <tr><td><code>contracts/</code></td><td>机器 / AI</td><td>API（OpenAPI）、事件（AsyncAPI）、字典、错误码、状态机——所有跨模块的真值</td></tr>
+        <tr><td><code>docs/</code></td><td>人类</td><td>需求、架构决策、详细设计、治理细则、过程文档</td></tr>
+        <% if (it.options.backend !== 'none') { %><tr><td><code>server/</code></td><td>机器</td><td>后端实现（<%= it.options.backend %>）<% if (it.options.database !== 'none') { %>，含 <code>db/</code> 数据库迁移与种子<% } %></td></tr>
+        <% } %><% if (it.options.frontend !== 'none') { %><tr><td><code>web/</code></td><td>机器</td><td>前端实现（<%= it.options.frontend %>）</td></tr>
+        <% } %><% if (it.options.mobile !== 'none') { %><tr><td><code>mobile/</code></td><td>机器</td><td>移动端（<%= it.options.mobile %>）</td></tr>
+        <% } %><% if (it.options.miniapp !== 'none') { %><tr><td><code>miniapp/</code></td><td>机器</td><td>小程序（<%= it.options.miniapp %>）</td></tr>
+        <% } %><% if (it.options.agent !== 'none') { %><tr><td><code>agent/</code></td><td>机器</td><td>桌面 / CLI 客户端（<%= it.options.agent %>）</td></tr>
+        <% } %><tr><td><code>ops/</code></td><td>机器</td><td>基础设施即代码（即便没有业务也要存在）</td></tr>
+        <tr><td><code>deploy/</code></td><td>机器</td><td>应用打包与发布（Dockerfile、Helm、流水线）</td></tr>
+        <tr><td><code>tools/</code></td><td>机器</td><td>结构化、可复用的开发工具（小产品级别）</td></tr>
+        <tr><td><code>scripts/</code></td><td>机器</td><td>薄、零散、日常维护脚本</td></tr>
+        <% if (it.options.ai === 'kiro') { %><tr><td><code>.kiro/</code></td><td>AI</td><td>Kiro IDE 的 steering / specs / hooks</td></tr>
+        <% } else if (it.options.ai === 'cursor') { %><tr><td><code>.cursor/</code></td><td>AI</td><td>Cursor 项目规则</td></tr>
+        <% } else if (it.options.ai === 'claude-code') { %><tr><td><code>CLAUDE.md</code> / <code>.claude/</code></td><td>AI</td><td>Claude Code 上下文 + slash-commands</td></tr>
+        <% } else if (it.options.ai === 'codex') { %><tr><td><code>.codex/</code></td><td>AI</td><td>Codex 项目备注</td></tr>
+        <% } %><tr><td><code>.keel/</code></td><td>用户</td><td>本指南、keel 元数据（你正在看的就在这里）</td></tr>
+      </table>
+      <div class="callout">
+        每个目录的细则见 <code>AGENTS.md</code> §1（顶层职责）和 <code>docs/governance/</code>（深度规则）。
+      </div>
+    </section>
+    <section id="concepts">
+      <h2>3. 关键概念</h2>
+      <h3>Contract First（契约优先）</h3>
+      <p>
+        所有跨模块的接口、事件、字典、错误码统一放在 <code>contracts/</code>。
+        任何代码改动如果触及契约，<strong>先冻结契约再写代码</strong>，并在同一 PR 里更新
+        <code>contracts/CHANGELOG.md</code>。
+      </p>
+      <h3>Tier（变更影响面，6 档，AI 自动判）</h3>
+      <p>每个改动从 0 到 5 选一档。AI 看你改了什么文件、是否动 contracts、是否跨服务，自动给建议。</p>
+      <table>
+        <tr><th>Tier</th><th>例子</th><th>动契约？</th></tr>
+        <tr><td><span class="badge tier-0">0</span> trivial</td><td>typo / 格式化 / 升级 patch / 补测试</td><td>不</td></tr>
+        <tr><td><span class="badge tier-1">1</span> bugfix</td><td>修 NPE、改 SQL、修 UI 错位</td><td>不</td></tr>
+        <tr><td><span class="badge tier-2">2</span> small change</td><td>加按钮 / 排序 / 文案</td><td>通常不</td></tr>
+        <tr><td><span class="badge tier-3">3</span> contract change</td><td>加 API / 字段 / 错误码 / 事件</td><td><strong>必须</strong></td></tr>
+        <tr><td><span class="badge tier-4">4</span> arch / breaking</td><td>跨服务、改鉴权、删字段</td><td><strong>必须</strong> + ADR</td></tr>
+        <tr><td><span class="badge">5</span> spike</td><td>探索性、用 <code>spike/*</code> 分支</td><td>合入前补</td></tr>
+      </table>
+      <h3>Doc Weight（文档投入，3 档，作者选）</h3>
+      <p>
+        与 Tier 正交：<strong>Tier</strong> 是变更客观属性，<strong>Doc Weight</strong> 是团队这次愿意投多少笔墨在 markdown 上。
+        AI 推荐默认值，作者可在 PR 模板里覆盖。
+      </p>
+      <table>
+        <tr><th>档</th><th>包含</th><th>常用场景</th></tr>
+        <tr><td><strong>lite</strong></td><td>PR 描述（动机 + 方案 + 影响面）+ 契约 diff（Tier 3+）+ ADR（Tier 4）</td><td>Tier 0/1/2/3 默认；Tier 4 简单情况</td></tr>
+        <tr><td><strong>standard</strong></td><td>lite + 简短的后端 / 前端设计章节（每份 2-3 段）</td><td>Tier 4 默认；Tier 3 复杂情况</td></tr>
+        <tr><td><strong>full</strong></td><td>standard + PRD（<code>docs/01/</code>） + UI 稿（如涉及前端）</td><td>来自产品需求 / 跨多团队 / 跨季度的项目</td></tr>
+      </table>
+      <div class="callout warn">
+        <strong>关键</strong>：Tier 3（加 API 字段）默认 <code>lite</code>——<strong>契约 diff 本身就是设计真值</strong>，
+        额外写中文设计文档反而易和契约漂移。仅当业务复杂度高（多状态机、跨服务、跨团队）才升 standard / full。
+      </div>
+      <h3>Adoption Tier（工程规范采纳档，<code>--engineering-standards</code>）</h3>
+      <p>
+        与 Doc Weight 是不同的"档"。Adoption Tier 是 <strong>项目级</strong>选择（在创建项目时一次性决定）：
+        <code>lite</code> 只发编码风格 markdown；<code>standard</code> 加技术栈钉版本；<code>full</code> 加 UI 设计系统。
+        本项目当前是 <code>standard</code>（默认），见 <code>docs/03-工程规范与研发基础设施/</code>。
+      </p>
+      <% if (it.options.ai !== 'none') { %><h3>AI Access Mode（5 档，AI 触达规则）</h3>
+      <p>
+        每个 docs 子目录用 <code>_ai-policy.yaml</code> 声明 AI 可不可以读 / 写：
+        <code>strict</code>（必同步）、<code>generated</code>（AI 主动改人审）、<code>suggest</code>（默认；提示但不自动改）、
+        <code>on-demand</code>（说出关键词才动）、<code>read-only</code>。完整规则见
+        <a href="../docs/governance/ai-access-modes.md"><code>docs/governance/ai-access-modes.md</code></a>。
+      </p>
+      <% } %>
+    </section>
+    <section id="what-to-do">
+      <h2>4. 我要做什么</h2>
+      <p>按你当前任务找入口：</p>
+      <details open>
+        <summary>🔧 修一个 bug（不动行为，不动 API）</summary>
+        <p><span class="badge tier-1">Tier 1</span> <span class="badge">lite</span></p>
+        <ul>
+          <li>直接改代码 + 加回归测试</li>
+          <li>PR 描述包含：重现步骤 / 根因 / 修复点 / 测试</li>
+          <li>不需要改 <code>contracts/</code> 和详细设计</li>
+        </ul>
+      </details>
+      <details>
+        <summary>➕ 加一个新 API 端点 / 字段（兼容新增）</summary>
+        <p><span class="badge tier-3">Tier 3</span> <span class="badge">默认 lite</span></p>
+        <ol>
+          <li>改 <code>contracts/openapi/api.yaml</code> 加端点 / 字段</li>
+          <li>改 <code>contracts/CHANGELOG.md</code> 记录 MINOR bump</li>
+          <li>实现代码</li>
+          <li>PR 描述引用契约锚点（<code>api.yaml#/paths/~1users/post</code>）</li>
+        </ol>
+        <p><strong>不需要</strong>额外写 <code>docs/04</code> 或 <code>docs/05</code> 设计文档；契约 diff 本身就是设计。</p>
+      </details>
+      <details>
+        <summary>♻️ 重构鉴权 / 改数据模型 / 删除字段</summary>
+        <p><span class="badge tier-4">Tier 4</span> <span class="badge">standard 起步</span></p>
+        <ol>
+          <li>先在 <code>docs/02-系统方案与架构/</code> 写 ADR（<code>adr-NNNN-&lt;slug&gt;.md</code>）</li>
+          <li>讨论 / 评审通过后改 <code>contracts/</code></li>
+          <li>写迁移与回滚预案</li>
+          <li>实现 + 测试</li>
+        </ol>
+      </details>
+      <details>
+        <summary>🧪 我想试新方案，不确定能不能用</summary>
+        <p><span class="badge">Tier 5 spike</span> <span class="badge">lite</span></p>
+        <ul>
+          <li>建 <code>spike/&lt;topic&gt;</code> 分支，自由实验</li>
+          <li>结论清楚后：采纳 → 重新走 Tier 1-4 流程并合入；不采纳 → 文档进 <code>docs/过程文档/spike-investigations/</code></li>
+          <li><code>spike/*</code> 不能直接合入 <code>main</code></li>
+        </ul>
+      </details>
+      <% if (it.options.database !== 'none') { %><details>
+        <summary>🗄️ 加一张表 / 改一个字段（数据库变更）</summary>
+        <p><span class="badge tier-3">Tier 3</span>（加字段）或 <span class="badge tier-4">Tier 4</span>（删字段 / 改类型）</p>
+        <ul>
+          <li>在 <code>server/db/migrations/</code> 加新迁移文件</li>
+          <li><strong>已合入 main 的迁移文件不允许修改</strong>，改 schema 写新文件</li>
+          <li>本项目用 <%= it.options.database %>，迁移工具见 <code>server/db/README.md</code></li>
+          <li>字典数据要同步 <code>contracts/dictionaries/</code></li>
+        </ul>
+      </details>
+      <% } %>
+      <details>
+        <summary>📦 升级一个依赖</summary>
+        <ul>
+          <li><strong>patch</strong>（4.17.20 → 4.17.21）：<span class="badge tier-0">Tier 0</span></li>
+          <li><strong>minor</strong>（4.17 → 4.18）：<span class="badge tier-2">Tier 2</span>，看 changelog</li>
+          <li><strong>major</strong>（3.x → 4.x）：<span class="badge tier-4">Tier 4</span>，要 ADR + 兼容性测试</li>
+          <li>所有情况都要同步 <code>docs/03-工程规范与研发基础设施/tech-stack-server.md</code> 的钉版本表（如启用 standard / full 工程规范）</li>
+        </ul>
+      </details>
+    </section>
+    <section id="commands">
+      <h2>5. 常用命令</h2>
+      <% if (it.options.backend === 'node') { %><h3>后端（Node + TypeScript）</h3>
+      <pre><code>cd server
+npm install
+npm run typecheck      # tsc --noEmit
+npm run lint           # eslint
+npm run format:check   # prettier
+npm test               # vitest / jest（按你加的）<% if (it.options.database === 'mysql' || it.options.database === 'postgres') { %>
+npm run db:migrate     # Knex 升到最新迁移
+npm run db:rollback    # 回滚最近一组
+npm run db:seed:prod   # 装字典数据
+npm run db:seed:dev    # 装开发样例数据<% } %><% if (it.options.database === 'elasticsearch') { %>
+npm run es:apply       # 应用 ES index template<% } %></code></pre>
+      <% } else if (it.options.backend === 'java') { %><h3>后端（Java + Spring Boot）</h3>
+      <pre><code>cd server
+mvn -B verify          # 编译 + 测试 + Checkstyle + Spotless<% if (it.options.database === 'mysql' || it.options.database === 'postgres') { %>
+mvn flyway:migrate     # 跑迁移
+mvn flyway:validate    # 校验代码 vs DB 历史一致<% } %>
+mvn spring-boot:run    # 启动应用</code></pre>
+      <% } else if (it.options.backend === 'python') { %><h3>后端（Python + FastAPI）</h3>
+      <pre><code>cd server
+python -m venv .venv
+source .venv/bin/activate    # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+uvicorn app.main:app --reload --port 8000
+# 浏览自动 OpenAPI UI: http://127.0.0.1:8000/docs
+pytest -q
+ruff check .
+mypy .<% if (it.options.database === 'mysql' || it.options.database === 'postgres') { %>
+alembic upgrade head        # 跑迁移
+alembic downgrade -1        # 回滚一版<% } %><% if (it.options.database === 'elasticsearch') { %>
+python db/apply_templates.py  # 应用 ES index template<% } %></code></pre>
+      <% } else if (it.options.backend === 'go') { %><h3>后端（Go）</h3>
+      <pre><code>cd server
+go mod download
+make build
+make test
+make lint              # golangci-lint<% if (it.options.database === 'mysql' || it.options.database === 'postgres') { %>
+make db-up             # golang-migrate 升迁移
+make db-down           # 回滚一条
+make db-create name=xxx # 新建迁移文件<% } %><% if (it.options.database === 'elasticsearch') { %>
+make es-apply          # 应用 ES index template<% } %></code></pre>
+      <% } %>
+      <% if (it.options.frontend === 'react' || it.options.frontend === 'vue') { %><h3>前端（<%= it.options.frontend %>）</h3>
+      <pre><code>cd web
+npm install
+npm run dev            # vite 开发服务器
+npm run build          # 生产打包
+npm run typecheck      # tsc --noEmit
+npm run lint
+npm run format:check
+npm test               # 如果加了 vitest</code></pre>
+      <% } %>
+      <h3>治理 / 全局</h3>
+      <pre><code># 检查 AGENTS.md / governance / role 目录 / 多应用 / 钉版本一致性
+node tools/governance-lint/index.js --strict<% if (it.options.contract === 'rest' || it.options.contract === 'rest+events') { %>
+# 校验 OpenAPI 契约
+npx --yes @stoplight/spectral-cli lint contracts/openapi/api.yaml<% } %><% if (it.options.contract === 'rest+events' || it.options.contract === 'events-only') { %>
+# 校验 AsyncAPI 契约
+npx --yes @stoplight/spectral-cli lint contracts/asyncapi/asyncapi.yaml<% } %>
+# 校验所有 JSON Schema
+for s in contracts/**/*.schema.json; do
+  npx --yes ajv-cli compile -s "$s"
+done</code></pre>
+    </section>
+    <section id="ai">
+      <h2>6. AI 协作</h2>
+      <% if (it.options.ai === 'kiro') { %><p>本项目集成 <strong>Kiro IDE</strong>。AI 协作的关键文件：</p>
+      <table>
+        <tr><th>文件 / 目录</th><th>用途</th></tr>
+        <tr><td><code>AGENTS.md</code></td><td>所有 AI 工具的总纲（也包括 Kiro）</td></tr>
+        <tr><td><code>.kiro/steering/*.md</code></td><td>Kiro 默认加载的"任务级"上下文</td></tr>
+        <tr><td><code>.kiro/specs/&lt;feature&gt;/</code></td><td>每个新特性的 requirements / design / tasks 三件套</td></tr>
+        <tr><td><code>.kiro/hooks/</code></td><td>事件触发的自动化（保存触发跑测试等）</td></tr>
+      </table>
+      <% } else if (it.options.ai === 'cursor') { %><p>本项目集成 <strong>Cursor</strong>。AI 协作的关键文件：</p>
+      <ul>
+        <li><code>AGENTS.md</code>：所有 AI 工具的总纲</li>
+        <li><code>.cursor/rules/*.md</code>：Cursor 的项目级规则</li>
+      </ul>
+      <% } else if (it.options.ai === 'claude-code') { %><p>本项目集成 <strong>Claude Code</strong>。AI 协作的关键文件：</p>
+      <ul>
+        <li><code>AGENTS.md</code>：所有 AI 工具的总纲</li>
+        <li><code>CLAUDE.md</code>：Claude Code 启动时自动加载的项目上下文</li>
+        <li><code>.claude/commands/*.md</code>：自定义 slash-commands</li>
+      </ul>
+      <% } else if (it.options.ai === 'codex') { %><p>本项目集成 <strong>Codex</strong>。AI 协作的关键文件：</p>
+      <ul>
+        <li><code>AGENTS.md</code>：所有 AI 工具的总纲</li>
+        <li><code>.codex/project.md</code>：Codex 项目备注</li>
+      </ul>
+      <% } else { %><p>本项目暂未集成具体 AI 工具。<code>AGENTS.md</code> 仍是总纲；
+      日后启用 Kiro / Cursor / Claude Code / Codex 等任意工具，它们都会自动读 <code>AGENTS.md</code>。</p>
+      <% } %>
+      <h3>AI 协作的规则</h3>
+      <ul>
+        <li>AI 生成的 commit 用 <code>feat(ai):</code> / <code>chore(ai):</code> / <code>fix(ai):</code> 前缀</li>
+        <li>PR 打 <code>ai-generated</code> 标签</li>
+        <li>Tier 3+ 改动 PR 描述必须引用契约锚点</li>
+        <li>Tier 4 必须引用 ADR</li>
+      </ul>
+    </section>
+    <section id="more">
+      <h2>7. 去哪查更多</h2>
+      <h3>给 AI（路径触发表）</h3>
+      <p>
+        <a href="../AGENTS.md"><code>AGENTS.md</code></a> §6 列出每条路径修改时必读的文档。
+        AI 在执行任务前会自动按这张表加载对应规则。
+      </p>
+      <h3>给人（文档门户）</h3>
+      <p>
+        <a href="../docs/README.md"><code>docs/README.md</code></a> 是文档总入口，含目录地图与归档规则。
+      </p>
+      <h3>治理细则</h3>
+      <table>
+        <tr><th>主题</th><th>文件</th></tr>
+        <tr><td>变更分级（Tier + Doc Weight）</td><td><a href="../docs/governance/change-tiers.md"><code>change-tiers.md</code></a></td></tr>
+        <tr><td>CI 校验矩阵</td><td><a href="../docs/governance/ci.md"><code>ci.md</code></a></td></tr>
+        <tr><td>依赖安全 / SBOM / 应急响应</td><td><a href="../docs/governance/security.md"><code>security.md</code></a></td></tr>
+        <tr><td>Git 工作流 / PR / CODEOWNERS</td><td><a href="../docs/governance/git-workflow.md"><code>git-workflow.md</code></a></td></tr>
+        <tr><td>数据库目录 / 迁移工具 / SQL 归属</td><td><a href="../docs/governance/database.md"><code>database.md</code></a></td></tr>
+        <tr><td>AI 访问模式</td><td><a href="../docs/governance/ai-access-modes.md"><code>ai-access-modes.md</code></a></td></tr>
+        <tr><td>完整 checklist</td><td><a href="../docs/governance/checklists.md"><code>checklists.md</code></a></td></tr>
+      </table>
+    </section>
+    <section id="faq">
+      <h2>8. 常见问题</h2>
+      <details>
+        <summary>我能直接改 <code>contracts/openapi/api.yaml</code> 吗？</summary>
+        <p>
+          能，但属于 <span class="badge tier-3">Tier 3</span>。同 PR 必须更新 <code>contracts/CHANGELOG.md</code>（CI 强制）。
+          PR 描述要引用契约锚点（如 <code>api.yaml#/paths/~1users/post</code>）。
+          删除字段或不兼容修改是 <span class="badge tier-4">Tier 4</span>，需要 ADR。
+        </p>
+      </details>
+      <details>
+        <summary>提了 PR 但 CI 报 <code>@TBD</code>？</summary>
+        <p>
+          根目录 <code>CODEOWNERS</code> 还有 <code>@TBD</code> 占位符。CI 在 governance-lint 这一步会拒绝
+          含 <code>@TBD</code> 的 CODEOWNERS。把 <code>@TBD</code> 替换成真实的 Git 账号即可。
+        </p>
+      </details>
+      <details>
+        <summary>Tier 怎么定？我每次都要查这表？</summary>
+        <p>
+          不用。AI 在 PR 描述里会根据 <code>git diff</code> 自动建议 Tier 与 Doc Weight。
+          你看不合适直接勾选别的。Reviewer 也会按现实情况调。
+        </p>
+      </details>
+      <details>
+        <summary>Doc Weight 选 lite，reviewer 让我补 04 设计文档怎么办？</summary>
+        <p>
+          指给他看 <a href="../docs/governance/change-tiers.md"><code>change-tiers.md</code></a> §3.2：Tier 3
+          默认 lite，契约 diff 本身就是设计；只在多状态机 / 跨服务 / 跨团队时升 standard。
+          Reviewer 不应仅因"没写设计文档"打回 Tier 3 + lite 的 PR。
+        </p>
+      </details>
+      <% if (it.options.database !== 'none') { %><details>
+        <summary>我误改了已合入 main 的迁移文件，怎么办？</summary>
+        <p>
+          回退那个文件到原内容（<code>git checkout main -- &lt;path&gt;</code>），然后写一个新迁移文件做你想做的事。
+          原因：迁移工具记录的是文件 hash，改既有迁移会让任何已部署环境的 <code>migrate</code> 校验失败。
+        </p>
+      </details>
+      <% } %>
+      <details>
+        <summary>我刚加完代码 commit 时被 governance-lint 拦下来了？</summary>
+        <p>
+          看终端里 <code>governance-lint</code> 输出的具体错误码。常见的：
+        </p>
+        <ul>
+          <li><code>GOV.STACK.DRIFT.MAJOR/MINOR</code>：技术栈钉版本与运行时清单漂移；同步两边</li>
+          <li><code>missing required key</code>：<code>_ai-policy.yaml</code> 字段不全</li>
+          <li><code>last-reviewed missing/stale</code>：governance markdown 的 frontmatter 过期</li>
+        </ul>
+        <p>详见 <code>docs/governance/ci.md</code>。</p>
+      </details>
+      <details>
+        <summary>我想加一个新角色目录（比如 <code>docs/12-XXX/</code>）</summary>
+        <p>
+          这是结构改动，需要 <span class="badge tier-4">Tier 4</span> + 新 ADR。原因：role 目录与 AI 触达模式、双闸门、
+          PR 模板都耦合，结构调整要走 <code>docs/02-系统方案与架构/adr-NNNN-XXX.md</code>。
+        </p>
+      </details>
+    </section>
+    <hr>
+    <p class="meta">
+      本文件由 <code>@wneng/create-keel</code> <%= it.scaffolderVersion %> 在
+      <%= it.generatedAt.slice(0, 10) %> 生成。可以自由编辑；如要让 AI 帮你重新生成，
+      在 <code>.keel/welcome.html</code> 顶部加一行 <code>&lt;!-- regen-on-update --&gt;</code>。
+    </p>
+  </main>
+</div>
+<script>
+  // 平滑滚动 + 当前章节高亮
+  const links = document.querySelectorAll('nav.sidebar a');
+  const sections = document.querySelectorAll('section[id]');
+  links.forEach((a) => {
+    a.addEventListener('click', (e) => {
+      const id = a.getAttribute('href');
+      if (id && id.startsWith('#')) {
+        const target = document.querySelector(id);
+        if (target) {
+          e.preventDefault();
+          target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+          history.replaceState(null, '', id);
+        }
+      }
+    });
+  });
+  // IntersectionObserver: 当前 section 进入视口 → 高亮对应 nav link
+  const obs = new IntersectionObserver((entries) => {
+    entries.forEach((entry) => {
+      if (!entry.isIntersecting) return;
+      const id = entry.target.id;
+      links.forEach((a) => {
+        a.classList.toggle('active', a.getAttribute('href') === '#' + id);
+      });
+    });
+  }, { rootMargin: '-30% 0px -60% 0px' });
+  sections.forEach((s) => obs.observe(s));
+</script>
+</body>
+</html>

package/src/templates/welcome-html/fragment.yaml ADDED Viewed

@@ -0,0 +1,14 @@
+name: welcome-html
+version: 1.0.0
+appliesWhen: {}
+priority: 5
+files:
+  - from: files/welcome.html
+    to: .keel/welcome.html
+    render: true
+  - from: files/keel-README.md
+    to: .keel/README.md
+    render: true
+  - from: files/WELCOME.md
+    to: WELCOME.md
+    render: true