@wneng/create-keel 0.2.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wneng/create-keel",
-  "version": "0.2.1",
+  "version": "0.3.2",
   "description": "Scaffolder for Contract First + Vibe Coding projects (keel conventions)",
   "keywords": [
     "scaffold",
@@ -17,6 +17,7 @@
     "dist",
     "src/templates",
     "src/feature/templates",
+    "src/standards/templates",
     "README.md",
     "LICENSE"
   ],

package/src/standards/templates/coding-style-dart.md.eta

@@ -0,0 +1,49 @@
+# Dart 编码规范
+
+> 真值是 `dart format` + `dart analyze`（包含 `analysis_options.yaml`）；本文件解释 *为什么* 与 *如何调整*。机器校验在 CI 中 `analyze` job 阻断违规。
+
+config: mobile/analysis_options.yaml
+
+## 命名规范
+
+- 类 / 枚举 / typedef：`PascalCase`
+- 方法 / 变量 / 字段：`camelCase`；常量 `lowerCamelCase` 或 `kPascalCase`（与项目内一种二选一锁死）
+- 库 / 文件名：`snake_case.dart`
+- 私有：下划线前缀 `_internal`
+
+## 格式化
+
+- `dart format` 单一权威；评审禁讨论缩进 / 行宽
+- 行宽 100；2 空格缩进；尾随逗号在多参 / 多元素结构上必加（dart format 行为依赖它）
+- import 顺序：`dart:*` → `package:*` → 相对路径，每段空行
+
+## 错误处理
+
+- `Exception` 子类描述业务错误；`Error` 仅用于不可恢复的 bug
+- 禁止 `catch` 不绑定变量；至少 `catch (e, st)` 并 log
+- 异步：`async/await` 是 happy path；`Future.wait` 时显式选择 `eagerError` 行为
+- 空值：用 sound null safety；禁止 `!` 解包除非有断言注释
+
+## Widget / 状态管理
+
+- StatelessWidget 优先；StatefulWidget 仅在必要时
+- 状态管理库（Provider / Riverpod / Bloc）：项目内统一一种，写在 ADR 中
+- build 方法保持 < 50 行；超过就拆子组件
+
+## 依赖与模块
+
+- `pubspec.yaml` 钉版本，与 `tech-stack-mobile.md` 对齐
+- 跨 `apps/*` 走 `packages/<shared>/` 或独立 pub package；禁止直接 path import 兄弟 app
+
+## 注释与文档
+
+- 公共 API 必须有 dartdoc（`///` 三斜杠）
+- 复杂逻辑加 `// Why:` 段
+- `// TODO` 必须带 issue 链接
+
+## lint 配置真值
+
+| 工具 | 配置文件 | CI job |
+|------|---------|--------|
+| dart format | （内置，无配置） | `format-check` |
+| dart analyze | `mobile/analysis_options.yaml` | `analyze` |

package/src/standards/templates/coding-style-go.md.eta

@@ -0,0 +1,52 @@
+# Go 编码规范
+
+> 真值是 `gofmt` + `golangci-lint` 配置；本文件解释 *为什么* 与 *如何调整*。机器校验在 CI 中 `lint` job 阻断违规。
+
+config: server/.golangci.yml
+
+## 命名规范
+
+- 包名：全小写单词，**无下划线 / 驼峰**；表达内容而非组织（`http` 而非 `httputil`）
+- 导出符号：`PascalCase`；非导出：`camelCase`
+- 错误变量：`Err<Reason>`（`ErrNotFound`）；接口：以 `-er` 结尾（`Reader`）
+- 测试：`Test<Func>`；fuzz：`Fuzz<Func>`；benchmark：`Benchmark<Func>`
+
+## 格式化
+
+- `gofmt -s` 单一权威；评审禁讨论缩进 / 行宽
+- 行宽建议 120 但不强制（gofmt 不限）；import 三段（标准库 → 第三方 → 本仓库），用空行隔开
+- `goimports` 自动处理；CI 中 `gofmt -l` 列出未格式化文件即阻断
+
+## 错误处理
+
+- 错误是返回值，不是异常；`if err != nil { return ... }` 是常态
+- 包裹错误用 `fmt.Errorf("...: %w", err)`；上层用 `errors.Is` / `errors.As` 解包
+- 禁止 `_ = err` 吞错；明确处理或加注释 `// best-effort, see issue #xxx`
+- panic 仅在不可恢复（程序 bug）时用；HTTP handler 不允许 panic 逃逸
+- sentinel error 在包级声明：`var ErrNotFound = errors.New("not found")`
+
+## 并发约束
+
+- 优先 channel；mutex 仅在 channel 不合适时用
+- 禁止 goroutine 泄露；启动 goroutine 必须有明确 cancel / done 机制
+- `context.Context` 是函数第一个参数；禁止存储在 struct field
+
+## 依赖与模块
+
+- 第三方依赖在 `go.mod` 钉版本，与 `tech-stack-server.md` 对齐
+- 主模块 `go.mod` 跟随仓库根；跨 `apps/*` 在 multi-app 模式下走 `internal/<shared>` 或独立 module
+
+## 注释与文档
+
+- 包级 doc comment：`// Package <name> ...`，必须存在
+- 导出符号 doc comment：`// <Name> ...` 开头（godoc 约定）
+- 不写 `// TODO` 而不带 issue 链接
+
+## lint 配置真值
+
+| 工具 | 配置文件 | CI job |
+|------|---------|--------|
+| gofmt | （内置，无配置） | `format-check` |
+| golangci-lint | `server/.golangci.yml` | `lint` |
+| go vet | （内置） | `vet` |
+| govulncheck | （命令行运行） | `security` |

package/src/standards/templates/coding-style-java.md.eta

@@ -0,0 +1,50 @@
+# Java 编码规范
+
+> 真值是 Checkstyle / Spotless 配置；本文件解释 *为什么* 与 *如何调整*。机器校验在 CI 中 `checkstyle` 与 `spotless:check` 阻断违规。
+
+config: server/checkstyle.xml
+
+## 命名规范
+
+- 类 / 接口 / 枚举：`PascalCase`；接口禁止 `I` 前缀
+- 方法 / 字段：`camelCase`；常量：`UPPER_SNAKE_CASE`
+- 包名：全小写 `com.<org>.<product>.<module>`，禁止下划线
+- 测试类：`<被测类>Test`；集成测试 `<场景>IT`
+
+## 格式化
+
+- Spotless（Google Java Format AOSP 风格）单一权威；评审禁讨论分号 / 大括号位置
+- 行宽 120；4 空格缩进；import 顺序：`java.*` → `javax.*` → 第三方 → `com.<org>.*`，每段空行
+- 删除未使用 import（Spotless 自动）
+
+## 错误处理
+
+- 检查异常仅在确实可恢复时使用；其余抛 `RuntimeException` 子类
+- 禁止 `catch (Exception e)` 吞错；至少 log + rethrow 或用 sentinel 返回值
+- 资源管理走 try-with-resources；禁止手写 `finally { close() }`
+- API 边界统一异常→`ProblemDetails`（RFC 7807）
+
+## 设计约束
+
+- POJO 走 record（Java 17+）或 Lombok `@Value`；二选一在 ADR 中记录
+- 禁止字段级公共可变状态；若必须用 `volatile` / `AtomicReference`
+- 依赖注入由 Spring 管理；构造函数注入，禁止字段注入
+
+## 依赖与模块
+
+- 第三方依赖在 `pom.xml` 钉版本，与 `tech-stack-server.md` frontmatter 对齐
+- 跨模块引用：`apps/*` 之间不允许直接 import（multi-app 模式下走 contract / 共享 packages）
+
+## 注释与文档
+
+- 公共类 / 公共方法必须有 JavaDoc，含 `@param` `@return` `@throws`
+- 复杂算法或决策点加 `// Why:` 段
+- 禁止 `// TODO` 不带 issue 链接
+
+## lint 配置真值
+
+| 工具 | 配置文件 | CI job |
+|------|---------|--------|
+| Checkstyle | `server/checkstyle.xml` | `checkstyle` |
+| Spotless | `server/pom.xml` 中 `<plugin>spotless</plugin>` 段 | `spotless-check` |
+| 编译警告 | `pom.xml` `-Werror` | `compile` |

package/src/standards/templates/coding-style-python.md.eta

@@ -0,0 +1,51 @@
+# Python 编码规范
+
+> 真值是 `ruff` + `mypy` 配置；本文件解释 *为什么* 与 *如何调整*。机器校验在 CI 中 `lint` 与 `typecheck` job 阻断违规。
+
+config: server/pyproject.toml
+
+## 命名规范
+
+- 模块 / 包：`snake_case`，全小写
+- 类：`PascalCase`；异常类：以 `Error` 结尾（`UserNotFoundError`）
+- 函数 / 变量：`snake_case`；常量：`UPPER_SNAKE_CASE`
+- 私有：单下划线前缀 `_helper`；name mangling 双下划线仅在确需时
+
+## 格式化
+
+- `ruff format` 单一权威（替代 black + isort）；评审禁讨论引号 / 行宽
+- 行宽 100；4 空格缩进；import 顺序：标准库 → 第三方 → 本地
+- 删除未使用 import（ruff 自动）
+
+## 类型注解
+
+- 全文件类型注解；函数签名禁止省略
+- 严格 mypy：`disallow_untyped_defs = true`，`strict_optional = true`
+- 优先 `pydantic.BaseModel` 描述 API 边界数据；`@dataclass(slots=True)` 描述内部值对象
+
+## 错误处理
+
+- 业务异常自定义 `XxxError(BaseAppError)`；禁止 `raise Exception(...)`
+- 禁止裸 `except:`；至少 `except Exception:` 并 log
+- 资源管理走 `with`；禁止手写 `try / finally: f.close()`
+- 异步：`asyncio.gather` 时显式选择 `return_exceptions` 行为
+
+## 依赖与导入
+
+- 第三方依赖在 `pyproject.toml` 钉版本，与 `tech-stack-server.md` 对齐
+- 跨 `apps/*` 引用走 `apps/_shared/` 或共享 distribution；禁止直接 `from apps.other import ...`
+- 循环 import：拆模块或用 TYPE_CHECKING 延迟
+
+## 注释与文档
+
+- 公共函数 / 类必须 docstring（Google 或 PEP 257 风格，仓库二选一锁死）
+- 复杂决策点加 `# Why:` 段
+- `# TODO` 必须带 issue 链接
+
+## lint 配置真值
+
+| 工具 | 配置文件 | CI job |
+|------|---------|--------|
+| ruff | `server/pyproject.toml` `[tool.ruff]` 段 | `lint` |
+| mypy | `server/pyproject.toml` `[tool.mypy]` 段 | `typecheck` |
+| pip-audit | （命令行） | `security` |

package/src/standards/templates/coding-style-rust.md.eta

@@ -0,0 +1,52 @@
+# Rust 编码规范
+
+> 真值是 `rustfmt` + `clippy` 配置；本文件解释 *为什么* 与 *如何调整*。机器校验在 CI 中 `clippy` job 阻断违规。
+
+config: agent/rustfmt.toml
+
+## 命名规范
+
+- crate / 模块：`snake_case`
+- 类型 / trait / 枚举：`PascalCase`；变体也是 `PascalCase`
+- 函数 / 变量 / 字段：`snake_case`；常量 / 静态：`UPPER_SNAKE_CASE`
+- 生命周期：单字母 `'a` 起步，复杂时表义 `'session`
+
+## 格式化
+
+- `cargo fmt` 单一权威；CI 中 `cargo fmt --check` 阻断
+- 行宽 100（rustfmt 默认）；4 空格缩进
+- import 顺序：标准库 → 第三方 → 本 crate；rustfmt 处理
+
+## 错误处理
+
+- 业务函数返回 `Result<T, E>`；禁止 `unwrap()` / `expect()` 在 release 路径
+- 错误类型：库代码用 `thiserror`；应用代码用 `anyhow::Result`
+- `?` 是 happy path；想日志或转换错误时用 `.context("...")` (`anyhow`) 或 `.map_err(...)`
+- panic 仅在不可恢复（断言违反、初始化失败）时用
+
+## 所有权与并发
+
+- 优先 borrow，其次 `Clone`，再次 `Arc`；`Rc` 仅在单线程
+- `unsafe` 必须有 `// SAFETY: ...` 注释解释不变量
+- 跨线程数据走 `Send + Sync`；共享可变状态走 `Arc<Mutex<T>>` 并尽量缩小锁粒度
+- async：`tokio` 单一运行时；不要混 async-std
+
+## 依赖与模块
+
+- `Cargo.toml` 钉版本（`= "x.y.z"`），与 `tech-stack-agent.md` 对齐
+- workspace：跨 `apps/*` 在 multi-app 模式下走顶层 `crates/<shared>`，禁止直接 path import 兄弟 app
+- 第三方 crate 引入前确认 license 与维护活跃度
+
+## 注释与文档
+
+- 导出 item 必须有 `///` doc comment；crate 根写 `//!` 模块级 doc
+- `// Why:` 段说明非显然的决策
+- `cargo doc --no-deps` 在 CI 中验证 doc 不报错
+
+## lint 配置真值
+
+| 工具 | 配置文件 | CI job |
+|------|---------|--------|
+| rustfmt | `agent/rustfmt.toml` | `format-check` |
+| clippy | `agent/Cargo.toml` 中 `[lints.clippy]` 段 | `clippy` |
+| cargo deny | `agent/deny.toml` | `security` |

package/src/standards/templates/coding-style-typescript.md.eta

@@ -0,0 +1,50 @@
+# TypeScript 编码规范
+
+> 真值是 ESLint / Prettier 配置；本文件解释 *为什么* 与 *如何调整*。机器校验在 CI 中 `eslint` job 阻断违规。
+
+config: web/.eslintrc.cjs
+
+## 命名规范
+
+- 文件：`kebab-case.ts`，组件文件除外 → `PascalCase.tsx`
+- 类型 / 接口 / 类：`PascalCase`，禁止 `I` 前缀
+- 变量 / 函数：`camelCase`，常量级（模块顶部全大写枚举）：`UPPER_SNAKE_CASE`
+- React 组件：`PascalCase`；hooks：`use<Name>`
+
+## 格式化
+
+- Prettier 单一权威；本仓库不在评审里讨论分号 / 引号 / 行宽
+- 行宽 100；2 空格缩进；尾随逗号 `all`
+- import 顺序：node 内置 → 第三方 → 别名 (`@/...`) → 相对路径，每段空行隔开
+
+## 错误处理
+
+- 业务函数返回 `Result<T, E>` 或抛出 `ScaffolderError` 子类；禁止裸 `throw new Error(...)`
+- `try / catch` 必须 narrow `unknown`：`catch (e)` 后用 `instanceof` 或 type guard
+- async 函数禁止吞错；`Promise.allSettled` 用于刻意聚合失败
+
+## 类型用法
+
+- 严格模式：`tsc --noEmit` 在 CI 阻断；本地禁止 `// @ts-ignore`，必要时用 `@ts-expect-error` 并解释
+- 优先 `interface` 描述对象形状；`type` 用于联合 / 映射 / 函数签名
+- 禁止 `any`；不可避免时用 `unknown` 加 type guard
+
+## 依赖与导入
+
+- 单 app：相对路径；多 app：路径别名 `@apps/<name>` 或 `@contracts/...`
+- 跨 `apps/*` import 在 multi-app 模式下被 `dependency-cruiser` 阻断
+- 第三方依赖必须在 `tech-stack-<env>.md` 钉版本表中存在
+
+## 注释与文档
+
+- TSDoc：导出符号必须有一行说明；复杂逻辑加 `Why:` 段说明意图
+- 对外 API：`@param` `@returns` `@throws` 完整
+- 禁止注释掉的代码；用 git 历史
+
+## lint 配置真值
+
+| 工具 | 配置文件 | CI job |
+|------|---------|--------|
+| ESLint | `web/.eslintrc.cjs`（前端）/ `server/.eslintrc.cjs`（后端） | `lint` |
+| Prettier | `.prettierrc` | `format-check` |
+| TypeScript | `tsconfig.json` | `typecheck` |

package/src/standards/templates/dependency-cruiser.config.cjs.eta

@@ -0,0 +1,57 @@
+/**
+ * dependency-cruiser configuration — engineering-standards module boundaries.
+ *
+ * Generated by `@wneng/create-keel` (engineering-standards plan).
+ * Edit with care; the rules here are referenced by:
+ *   - docs/03-工程规范与研发基础设施/module-boundaries.md (narrative truth)
+ *   - tools/governance-lint/checks/stack-pinning.js (exit code mapping)
+ */
+
+/** @type {import('dependency-cruiser').IConfiguration} */
+module.exports = {
+  forbidden: [
+    {
+      name: 'GOV.BOUND.CROSS_APP',
+      severity: 'error',
+      comment:
+        'apps/<X> must not directly import from apps/<Y>. Move shared code to contracts/ or packages/<shared>/.',
+      from: { path: '^(?:[^/]+)/apps/([^/]+)/' },
+      to: { path: '^(?:[^/]+)/apps/(?!\\1)([^/]+)/' },
+    },
+    {
+      name: 'GOV.BOUND.CIRCULAR',
+      severity: 'error',
+      comment: 'Circular dependencies make the build graph unstable.',
+      from: {},
+      to: { circular: true },
+    },
+    {
+      name: 'no-orphans',
+      comment: 'Orphan modules (no incoming edges) usually indicate dead code.',
+      severity: 'warn',
+      from: {
+        orphan: true,
+        pathNot: [
+          '(^|/)\\.(?:eslint|prettier|babel|tsconfig)',
+          '\\.d\\.ts$',
+          '(^|/)src/index\\.[jt]sx?$',
+        ],
+      },
+      to: {},
+    },
+  ],
+  options: {
+    doNotFollow: { path: 'node_modules' },
+    tsConfig: { fileName: 'tsconfig.json' },
+    enhancedResolveOptions: {
+      exportsFields: ['exports'],
+      conditionNames: ['import', 'require', 'node'],
+    },
+    reporterOptions: {
+      err: {
+        // Standard error format consumed by governance-lint
+        showRules: true,
+      },
+    },
+  },
+};

package/src/standards/templates/design-tokens.ts.eta

@@ -0,0 +1,37 @@
+/**
+ * Design tokens — generated by `@wneng/create-keel` (engineering-standards).
+ *
+ * The exported constant *names* here MUST exactly match the token name
+ * column in `docs/05-前端客户端详细设计/ui-design-system.md`. The
+ * governance-lint `ui-token-drift` check enforces this; mismatches
+ * surface as `GOV.UI.TOKEN_DRIFT` in CI.
+ *
+ * Edit values, not names. Renaming a token requires a coordinated PR
+ * that touches both this file and the manifest's token table in the
+ * same commit.
+ */
+
+// Colors ---------------------------------------------------------------
+
+export const colorPrimary = '#2563EB';
+export const colorSurface = '#FFFFFF';
+export const colorTextDefault = '#0F172A';
+export const colorTextMuted = '#64748B';
+export const colorBorder = '#E2E8F0';
+export const colorDanger = '#DC2626';
+
+// Spacing --------------------------------------------------------------
+
+export const space1 = '4px';
+export const space2 = '8px';
+export const space3 = '12px';
+export const space4 = '16px';
+export const space6 = '24px';
+export const space8 = '32px';
+
+// Typography -----------------------------------------------------------
+
+export const fontHeading1 = { fontSize: '32px', lineHeight: 1.25, fontWeight: 600 } as const;
+export const fontHeading2 = { fontSize: '24px', lineHeight: 1.3, fontWeight: 600 } as const;
+export const fontBody = { fontSize: '14px', lineHeight: 1.5, fontWeight: 400 } as const;
+export const fontCaption = { fontSize: '12px', lineHeight: 1.4, fontWeight: 400 } as const;

package/src/standards/templates/module-boundaries.md.eta

@@ -0,0 +1,82 @@
+# 模块引用边界
+
+> 本文件给出仓库内的引用方向规则。机器侧守门交给 `dependency-cruiser` / `archunit` / `gomodguard` 等工具；本文件解释**为什么**有这些边界，以及**如何**调整。
+
+config: <% if (it.standards.multiApp) { %>dependency-cruiser.config.cjs<% } else { %>(单 app 模式无机器守门，仅本文件叙事)<% } %>
+
+## 总原则
+
+依赖**只**沿允许的方向流动。违反方向的 import / require / require_once 会导致以下后果之一：
+
+1. 短期：编译能过，但循环依赖让构建图不稳定
+2. 中期：模块边界腐烂，重构难度指数上升
+3. 长期：单一模块测试不再独立，整仓 CI 时长翻倍
+
+为防止这种漂移，本文件 + `dependency-cruiser`（multi-app 模式下）一起做硬约束。
+
+## 命名规范
+
+边界检查中用到的几个稳定标识：
+
+- `apps/<name>/` —— 多 app 模式下的应用根
+- `contracts/` —— 跨执行环境的机器可消费契约
+- `packages/` —— 多 app 共享的代码（root 级，可选）
+
+## 错误处理
+
+import 违规会被 dependency-cruiser 报告为以下错误码：
+
+- `GOV.BOUND.CROSS_APP` —— `apps/A` 直接引用了 `apps/B` 的代码
+- `GOV.BOUND.CIRCULAR` —— 模块循环依赖
+
+修复路径：把共享代码挪到 `contracts/`（机器可消费契约）或 `packages/<shared>/`（根级可选 workspace）。
+
+## 格式化
+
+- 模块导出文件按 layer 命名：`index.ts` 是公共入口，`internal/` 下是私有
+- 跨包 import 必须经过 `index.ts`，**禁止**深路径 `from "@app/internal/foo"`
+
+<% if (it.standards.multiApp) { %>## 多 app 模式（当前启用）
+
+仓库已切换到多 app 模式，`<env>/apps/<name>/` 下每个目录是独立应用。
+
+**禁止**：
+- `apps/A/` 中的代码 import `apps/B/` 中的任何文件（任何深度）
+- 跨 app 共享 utility 直接放在某个 app 内部
+
+**允许**：
+- 通过 `contracts/` 共享 schema / 错误码 / 状态机
+- 通过根 `packages/<name>/` 共享代码（需要在 PR 中说明为什么不能放契约层）
+
+机器守门：[`dependency-cruiser.config.cjs`](../../dependency-cruiser.config.cjs) 在 CI 中阻断违规 import。
+
+## 调整流程
+
+1. 改 `dependency-cruiser.config.cjs` 中的 forbidden 规则前，必须在 ADR 中说明
+2. 同 PR 改本文件正文部分（这是双写，让 review 看到边界变化）
+3. CI 跑 dependency-cruiser；不通过就改回去
+4. 真要破例：在违规处添加 `// eslint-disable-next-line import/no-restricted-paths` 并 PR 描述给出理由
+<% } else { %>## 单 app 模式（当前启用）
+
+仓库目前是单 app 模式，`<env>/` 下直接放一份工程文件，没有 `apps/` 子目录。
+
+**约束**：
+- 跨执行环境（如后端 server/ ↔ 前端 web/）必须通过 `contracts/` 共享类型与契约
+- 不要在 server/ 中 import web/ 的文件，或反之
+
+**没有机器守门**：单 app 模式下不强制 dependency-cruiser；这是有意为之，因为单 app 模式工程量小，引入额外工具收益不抵成本。
+
+## 升级到多 app 模式
+
+如果将来仓库需要容纳第二个应用：
+
+1. `mkdir <env>/apps/<原应用名>` 并 `git mv` 全部源码
+2. 同 PR 启用 `--multi-app` 选项，重新生成本文件 + `dependency-cruiser.config.cjs`
+3. 在 ADR 中记录"为什么从单 app 升级"
+4. 完整 promote / add-app 流程见 [`docs/governance/git-workflow.md`](../governance/git-workflow.md)
+<% } %>
+
+## 关联
+
+- 编码规范：见 `coding-style-<lang>.md` 系列
+- 部署：跨 app 共享配置走 `deploy/`，不要让一个 app 依赖另一个 app 的 deploy 制品

package/src/standards/templates/tech-stack-agent.md.eta

@@ -0,0 +1,35 @@
+---
+runtime: <%= it.standards.env %>
+language: <%= it.standards.language %>
+packageManager: <%= it.standards.packageManager %>
+manifestPath: <%= it.standards.manifestPath %>
+lastReviewed: <%= it.standards.lastReviewed %>
+dependencies:
+<% for (const dep of it.standards.dependencies) { %>  - name: "<%= dep.name %>"
+    version: "<%= dep.version %>"
+    policy: <%= dep.policy %>
+<% } %>---
+
+# 桌面 / Agent 技术栈钉版本表
+
+> frontmatter 是机器真值；governance-lint 会把上面 `dependencies` 与 `<%= it.standards.manifestPath %>` 的实际版本逐条比对。
+
+## 为什么钉版本
+
+- **桌面端发布周期长**：用户桌面上的版本几个月不更新很正常；不可重现的依赖会让远程 debug 极其痛苦
+- **平台二进制兼容**：Tauri / Electron 的原生模块在 Windows / macOS / Linux 表现不一致，主版本变化最容易触发签名失败
+
+## policy 三档
+
+policy 语义与 [tech-stack-server.md](tech-stack-server.md) 一致。桌面端常用 `minor` 起步，对 `tokio` / `serde` 一类基础设施级依赖也只用 `minor`（Rust 生态的 SemVer 通常守得住）。
+
+## Rust crate 特有的考虑
+
+- workspace 中所有 crate 的同名依赖必须钉同一版本（`Cargo.toml` 中 `[workspace.dependencies]` 段）
+- 与 C / C++ 共享库通过 FFI 交互的 crate（如 `openssl-sys`）：标 `major-only`，因为底层 ABI 变化会导致 panic
+- `unsafe` 较多的 crate：标 `major-only`，每次升级都人工 review CHANGELOG
+
+## 关联
+
+- 编码规范：[coding-style-rust.md](coding-style-rust.md)
+- 依赖安全：[../governance/security.md](../governance/security.md)

package/src/standards/templates/tech-stack-miniapp.md.eta

@@ -0,0 +1,34 @@
+---
+runtime: <%= it.standards.env %>
+language: <%= it.standards.language %>
+packageManager: <%= it.standards.packageManager %>
+manifestPath: <%= it.standards.manifestPath %>
+lastReviewed: <%= it.standards.lastReviewed %>
+dependencies:
+<% for (const dep of it.standards.dependencies) { %>  - name: "<%= dep.name %>"
+    version: "<%= dep.version %>"
+    policy: <%= dep.policy %>
+<% } %>---
+
+# 小程序技术栈钉版本表
+
+> frontmatter 是机器真值；governance-lint 会把上面 `dependencies` 与 `<%= it.standards.manifestPath %>` 的实际版本逐条比对。
+
+## 为什么钉版本
+
+- **平台 SDK 审核期长**：宿主（微信 / 支付宝 / 抖音）的基础库版本不在本表；本表管的是 npm 侧依赖
+- **小程序包大小限制**：依赖增删都影响 2 MB / 8 MB 包限制；钉版本帮助定位"哪次升级把包撑爆了"
+
+## policy 三档
+
+policy 语义与 [tech-stack-server.md](tech-stack-server.md) 一致。小程序场景常用 `minor` + 严选第三方包。
+
+## 宿主基础库
+
+- 微信：`miniapp/project.config.json` 中的 `libVersion` 是宿主版本，非 npm 依赖；不进本表
+- 自定义组件库（如 vant-weapp）：进本表，policy 标 `minor`
+
+## 关联
+
+- 编码规范：[coding-style-typescript.md](coding-style-typescript.md)
+- 依赖安全：[../governance/security.md](../governance/security.md)

package/src/standards/templates/tech-stack-mobile.md.eta

@@ -0,0 +1,36 @@
+---
+runtime: <%= it.standards.env %>
+language: <%= it.standards.language %>
+packageManager: <%= it.standards.packageManager %>
+manifestPath: <%= it.standards.manifestPath %>
+lastReviewed: <%= it.standards.lastReviewed %>
+dependencies:
+<% for (const dep of it.standards.dependencies) { %>  - name: "<%= dep.name %>"
+    version: "<%= dep.version %>"
+    policy: <%= dep.policy %>
+<% } %>---
+
+# 移动端技术栈钉版本表
+
+> frontmatter 是机器真值；governance-lint 会把上面 `dependencies` 与 `<%= it.standards.manifestPath %>` 的实际版本逐条比对。
+
+## 为什么钉版本
+
+- **应用商店审核失败回溯**：移动端经常因第三方 SDK 更新触发审核拒绝；版本钉死能精确定位
+- **多设备一致性**：CI 与开发机装出同一份依赖
+- **离线场景**：移动端不像服务端能随时回滚镜像，钉版本是唯一保险
+
+## policy 三档
+
+policy 语义、调整流程，与 [tech-stack-server.md](tech-stack-server.md) 一致。
+
+## 移动端特有的考虑
+
+- iOS 系统 API / Android SDK 不归本表管，由 `mobile/ios/Podfile` 与 `mobile/android/build.gradle` 中的对应版本约束
+- React Native / Flutter SDK 主版本升级常涉及原生模块重新链接；务必标 `major-only`
+- 推送、地图、支付 SDK：标 `major-only`（合规要求强约束）
+
+## 关联
+
+- 编码规范：[coding-style-<%= it.standards.language %>.md](coding-style-<%= it.standards.language %>.md)
+- 依赖安全：[../governance/security.md](../governance/security.md)

package/src/standards/templates/tech-stack-server.md.eta

@@ -0,0 +1,50 @@
+---
+runtime: <%= it.standards.env %>
+language: <%= it.standards.language %>
+packageManager: <%= it.standards.packageManager %>
+manifestPath: <%= it.standards.manifestPath %>
+lastReviewed: <%= it.standards.lastReviewed %>
+dependencies:
+<% for (const dep of it.standards.dependencies) { %>  - name: "<%= dep.name %>"
+    version: "<%= dep.version %>"
+    policy: <%= dep.policy %>
+<% } %>---
+
+# 后端技术栈钉版本表
+
+> 这个文件的 **frontmatter 是机器真值**：CI 中的 `governance-lint` 会把上面 `dependencies` 数组与 `<%= it.standards.manifestPath %>` 的实际版本逐条对比。
+>
+> 本文件正文是**为什么**这样选 + **如何调整**。机器无法回答这两个问题。
+
+## 为什么钉版本
+
+- **审计可追溯**：哪天升级、为什么升级、谁拍板，都留在这个文件的 git 历史里
+- **可重现构建**：六个月后回到这个 commit，依赖能装出同一棵树
+- **AI 不擅自升级**：scaffolder 的 governance-lint 把"未走 PR 的 minor / major 漂移"当作 CI 失败
+
+## policy 三档
+
+| policy | 含义 | 何时使用 |
+|--------|------|----------|
+| `free` | 任意漂移都不报 | 工具链辅助包（如类型 stub），版本变化不影响业务 |
+| `minor` | minor / patch 漂移 → warning；major → error | 默认。绝大多数 runtime 框架与库 |
+| `major-only` | 任何漂移（含 patch）→ error | 安全敏感库（加密、token 验证、SSO） |
+
+## 调整流程
+
+1. 改 `<%= it.standards.manifestPath %>` 中的版本（或让包管理器自动 bump）
+2. 同 PR 改本文件 frontmatter 的对应行；这是**双写**有意为之，让 PR review 必须看到版本变化
+3. CI 中 `governance-lint` 验证两边一致；不一致就阻断
+4. PR 描述中说明：升级动机（功能 / 安全 / 性能）+ 兼容性影响
+
+## 何时**不**钉
+
+- 仅开发期使用的 lint / format / 测试工具：可以放在 `devDependencies` 但**不**进本表
+- 容器基础镜像版本：在 `deploy/Dockerfile` 里钉，本表不重复
+- 系统包（apt / yum）：交给运行时镜像维护者
+
+## 关联
+
+- 编码规范：[coding-style-<%= it.standards.language %>.md](coding-style-<%= it.standards.language %>.md)
+- 依赖安全：[../governance/security.md](../governance/security.md)
+- 升级流程模板：参考最近的 PR 历史 `git log --grep="bump"`