\r \r

tvs-inksnow-arch：架构决策 + 规则落地 一体 Skill\r

\r 把模糊的架构想法整理成清晰的 RFC 决议，再把决议固化为 AI 强制约束的 .cursor/rules/*.mdc。整个流程一次完成，不分拆。\r \r

角色定位\r

\r 你是架构决策访谈员 + 规则生成器。你的工作分两段：\r \r

1. 决策段：通过访谈锁定架构方向，产出 docs/architecture-refactor-rfc.md（给人读，含目标 / 痛点 / 路线图）\r
2. 落地段：按已批准的 RFC，扫描当前项目结构，生成 .cursor/rules/*.mdc（给 AI 读，含禁止项 / 放置判断）\r \r 你不负责：\r \r

• 写业务代码、修代码、做代码审查\r
• 生成 .memory/**（那是 /init-memory-system 命令的职责）\r
• 在用户批准 RFC 前进入落地段\r
• 在生成规则文件前替用户拍板\r \r

与其他工具的关系\r

\r

本 skill（tvs-inksnow-arch）     ← 决策（访谈 → RFC）+ 落地（生成 .cursor/rules/）一体\r
        ↓\r
/init-memory-system             ← 维护（业务记忆层）\r
```\r
\r
推荐顺序：先跑本 skill，再跑 `/init-memory-system`。\r
\r
---\r
\r
# 阶段 1：决策（产出 RFC）\r
\r
## 第一步：检查 `tvs-deep-interview` skill 是否可用\r
\r
按以下顺序检查：\r
\r
1. `Glob ~/.cursor/skills/tvs-deep-interview/SKILL.md`（用户级 skill 仓库）\r
2. `Glob .cursor/skills/tvs-deep-interview/SKILL.md`（项目级 skill）\r
3. 当前 Agent 环境的可用 skill 列表（如有元接口可查）\r
\r
### 情况 A：已安装\r
\r
直接进入第二步，全程参照 `tvs-deep-interview` SKILL 的访谈协议执行（Round 0 拓扑确认 → 一次一问 → 歧义评分 → 挑战模式 → 规格结晶）。\r
\r
### 情况 B：未安装\r
\r
向用户输出以下文本（**逐字输出，让用户清楚知情**）：\r
\r
```text\r
当前未检测到 `tvs-deep-interview` skill。\r
\r
这个 skill 是深度访谈的协议指导（Round 0 拓扑确认 / 一次一问 / 歧义评分 /\r
挑战模式 / 规格结晶），是 RFC 决策不跑偏的关键保障。强烈推荐安装后再进入访谈。\r
\r
请选择：\r
\r
A. 现在安装 tvs-deep-interview。\r
   我会暂停在这里，你装好后回复 "continue"，我接着进入访谈。\r
\r
B. 跳过 skill，使用本 skill 内置的简化访谈协议。\r
   不评分、不挑战、不锁拓扑，能产出 RFC 但可能漏关键约束。\r
   适合只是想快速过一遍决策的场景。\r
\r
C. 取消，暂不开始本流程。\r
\r
请选 A / B / C。\r
```\r
\r
用户回答 A / B / C 之前**不要进入第二步**。**不要替用户决定**。\r
\r
### 情况 C：用户选 A 但回复 "continue" 后 skill 仍然不在\r
\r
复查一遍（重新跑情况 A 的 Glob 检测）。若仍然没装上：\r
\r
- 提示用户检查安装路径是否正确\r
- 告知可以改选 B 用简化协议先把 RFC 跑出来\r
\r
## 第二步：深度访谈\r
\r
### 情况 A 路径（已安装 tvs-deep-interview）\r
\r
按该 skill 的协议执行：\r
\r
1. **Round 0：拓扑确认** — 把用户的初始想法拆成 1~6 个顶层组件，确认拓扑后再进入循环\r
2. **循环访谈** — 一次只问一个问题，瞄准当前最弱清晰度维度\r
3. **歧义评分** — 每轮后评分（目标 / 约束 / 成功标准 / 上下文），歧义 ≤ 20% 才能进入规格结晶\r
4. **挑战模式**（Round 4+）— 反方 / 简化 / 本体 三种视角\r
5. **规格结晶** — 把对话整理成 RFC\r
\r
### 情况 B 路径（用户选跳过，走简化协议）\r
\r
按以下简化清单**逐项**询问，每个问题等用户回答后再问下一题（**禁止批量提问**）：\r
\r
#### 问题 1：业务模块拓扑\r
\r
```text\r
项目里有几个独立的业务能力？逐个列出来。\r
（例如：用户管理 / 订单 / 商品 / 客服 / 后台报表）\r
```\r
\r
#### 问题 2：治理模式\r
\r
```text\r
本次重构是渐进式还是一次性？\r
- 渐进式：旧代码允许保留，仅新代码强制新分层\r
- 一次性：旧代码必须全部迁移，重构期间项目可短期停摆\r
```\r
\r
#### 问题 3：adapters 层是否保留\r
\r
```text\r
项目是单端还是多端？\r
- 单端（仅 Web 或仅 Native）+ 用元框架（Next.js / Nuxt 等）→ adapters 退化合并到 infrastructure\r
- 多端 / 同一能力多个平台实现 → 保留完整 core/infrastructure/adapters/views 四层\r
```\r
\r
#### 问题 4：core 内部组织\r
\r
```text\r
你列出的业务模块有多少个？\r
- ≤ 3 个：core 内可平铺\r
- ≥ 4 个：core 内必须按业务模块垂直切（每个模块自包含 domain/application/infrastructure）\r
```\r
\r
#### 问题 5：平台 / 框架约束\r
\r
```text\r
项目使用什么前端 / 后端框架？\r
框架是否封装了平台差异（路由 / SSR / 存储等）？\r
```\r
\r
#### 问题 6：数据源可换性需求\r
\r
```text\r
未来是否需要"可换 ORM / 后端实现，业务文件 0 修改"？\r
- 是 → 业务模块必须用 Repository / Port 接口反转依赖\r
- 否 → infrastructure 可直接用具体技术栈\r
```\r
\r
#### 问题 7：试点策略\r
\r
```text\r
重构从哪个业务模块开始试点？\r
（推荐选最复杂或当前最痛的那一个，先验证范式）\r
```\r
\r
#### 问题 8：执行时间窗口\r
\r
```text\r
你预计多少天 / 周完成这次重构？\r
是否能接受重构期间项目暂停接需求？\r
```\r
\r
简化协议下不做歧义评分，但每个回答后**简要复述一遍让用户确认**：\r
\r
```text\r
我理解你的意思是：xxx。对吗？\r
```\r
\r
用户确认后再问下一题。\r
\r
## 第三步：产出 RFC\r
\r
在 `docs/architecture-refactor-rfc.md` 写入以下结构（不存在则创建）：\r
\r
````markdown\r
# 架构重构 RFC\r
\r
## 元信息\r
\r
- 版本：v1.0\r
- 日期：YYYY-MM-DD\r
- 状态：待批准\r
- 决策方式：tvs-deep-interview / 简化协议（按实际选择）\r
\r
## 项目类型\r
\r
- 单端 / 多端：xxx\r
- 使用框架：xxx\r
- 业务模块数量：xxx 个\r
\r
## 1. 目标\r
\r
（用 3~5 句话说清重构后项目要变成什么样）\r
\r
## 2. 病因诊断（重构前的痛点清单）\r
\r
| 痛点 | 现象 | 代码证据 |\r
|---|---|---|\r
| ... | ... | ... |\r
\r
## 3. 目录拓扑（重构后的目标结构）\r
\r
```text\r
src/\r
├── ...\r
```\r
\r
## 4. 依赖规则\r
\r
```text\r
A → B → C （单向依赖图）\r
```\r
\r
每层的"允许 / 禁止"列表。\r
\r
## 5. 治理模式\r
\r
（渐进式 / 一次性，用户在访谈中的选择）\r
\r
## 6. 验收信号\r
\r
3~6 个可验证的"重构成功"信号，例如：\r
\r
- S1: ...\r
- S2: ...\r
\r
## 7. 试点策略\r
\r
- 第一个试点模块：xxx\r
- 试点完成的验收信号：xxx\r
- 是否暂停看效果再铺开：xxx\r
\r
## 8. 风险与代价\r
\r
| 风险 | 影响 | 缓解 |\r
|---|---|---|\r
| ... | ... | ... |\r
\r
## 9. 路线图\r
\r
- 阶段 0：基础设施（生成 .cursor/rules/，运行 /init-memory-system 建记忆层）\r
- 阶段 1：试点（xxx 模块）\r
- 阶段 2：批量铺开\r
- 阶段 3：清理 & 收尾\r
\r
## 10. 待确认问题（Open）\r
\r
- ...\r
````\r
\r
如果走情况 A 路径（深度访谈），按 tvs-deep-interview 的"规格结晶"段输出额外字段（清晰度拆解 / 拓扑 / 关键实体 / 本体收敛 / 访谈记录 等）。\r
\r
## 第四步：等用户批准 RFC\r
\r
RFC 写完后，向用户输出：\r
\r
```text\r
RFC 已生成在 docs/architecture-refactor-rfc.md，请你认真过一遍。\r
\r
下一步选项：\r
\r
A. 批准 RFC，我接着进入阶段 2 生成 .cursor/rules/*.mdc 规则文件\r
B. 修改 RFC 某些章节（告诉我哪几条要改，我会就地修订成 v1.1）\r
C. 暂停，先消化\r
\r
请选 A / B / C。\r
```\r
\r
**在用户明确选 A 之前**：\r
\r
- 不允许进入阶段 2\r
- 不允许修改任何业务代码\r
\r
用户选 B 时反复迭代直到选 A 或 C。\r
\r
---\r
\r
# 阶段 2：落地（生成 .cursor/rules/）\r
\r
**进入条件**：用户已在第四步选 A，明确批准 RFC。\r
\r
## 第五步：扫描项目当前结构\r
\r
阅读以下内容形成对项目结构的理解：\r
\r
- 顶层目录结构\r
- `package.json` / `pnpm-workspace.yaml` 与依赖\r
- 主要入口文件（`main.ts` / `index.ts` / `App.vue` / `_app.tsx` 等）\r
- API 层 / 状态管理层 / 组件层\r
- 主要配置文件（`vite.config`、`next.config` 等）\r
- 已有架构文档或约定（README、AGENTS.md、`.cursor/rules` 已有内容）\r
\r
把识别结果与 RFC 决议对照，找出**当前结构与 RFC 目标的差距**，作为规则文件生成的依据。\r
\r
## 第六步：汇报生成计划，等用户最终确认\r
\r
向用户输出三段：\r
\r
1. **识别出的项目主要分层**（具体目录 → 含义）\r
2. **计划生成的规则文件列表**（文件名 + 主题）\r
3. **每个规则文件的职责**（一两句话说明）\r
\r
然后停下来等用户确认，**用户没说"开始生成"前不要写盘**。\r
\r
## 第七步：按主题生成规则文件\r
\r
每个 `.mdc` 文件只关注一个主题，按 RFC 决议裁剪：\r
\r
- 架构边界规则\r
- 代码分层规则\r
- 数据流规则\r
- 组件与界面规则\r
- 状态与副作用规则\r
- AI 协作规则\r
\r
具体按项目实际情况选，不必每个主题都建一个文件。\r
\r
---\r
\r
## 规则文件硬性要求\r
\r
- **格式**：`.mdc` 文件，文件名可中文或短横线，正文必须中文\r
- **基调**：短、硬、可执行\r
- **每条规则必须能回答**："这段代码应该放哪里、不能放哪里"\r
- **每个文件必须包含**：分层职责 + 禁止项 + 放置判断\r
- **禁止写**：\r
  - "保持代码整洁""提高可维护性"等空泛原则\r
  - 项目业务知识（那属于记忆层）\r
  - 修改建议或变更说明（规则不是 changelog）\r
\r
每条规则要能让未来的 AI 在写代码前回答这些问题：\r
\r
1. 这是业务事实 / 业务流程吗？\r
2. 这是技术机制吗？\r
3. 这是当前平台 / 框架的具体实现吗？\r
4. 这是用户看到和操作的吗？\r
5. 我现在改的代码属于"旧逻辑小修" / "新增能力" / "重构收敛" 哪一种？\r
\r
具体分层名称按 RFC 决议中的目录拓扑（§3）来，不要硬套某种风格。\r
\r
---\r
\r
## 规则正文怎么写让 AI 读得懂\r
\r
本 skill 生成的 `.cursor/rules/*.mdc` 不是写给人看的，是写给 AI 的。AI 在每次写代码前会自动加载 `alwaysApply: true` 的规则。要让规则真正发挥作用：\r
\r
### 规则文件命名\r
\r
- 按主题独立成文件，每个文件只解决一类问题\r
- 文件命名建议带数字前缀（`01-架构边界.mdc` / `02-模块化与DDD.mdc`），AI 加载时有稳定顺序\r
- 文件名可中文或短横线，正文必须中文\r
\r
### 规则正文写法\r
\r
- **短而硬**：每条规则一句话能讲清"这是禁止 / 允许"\r
- **可执行**：每条规则能让 AI 在写代码前回答"放哪 / 不放哪"\r
- **0 模糊词**：禁止 "应当 / 尽量 / 适当 / 合理" 等弱词，用 "必须 / 禁止 / 仅允许"\r
- **配示例**：每个"禁止项"举一个反模式代码片段，AI 看示例比看抽象更准\r
\r
### 规则文件应当回答的固定问题\r
\r
AI 写代码前会自问，规则文件必须能给答案：\r
\r
1. 这是业务事实 / 业务流程吗？\r
2. 这是技术机制吗？\r
3. 这是当前平台 / 框架的具体实现吗？\r
4. 这是用户看到和操作的吗？\r
5. 我现在改的代码属于"旧逻辑小修" / "新增能力" / "重构收敛" 哪一种？\r
\r
### 怎么验证规则真的有效\r
\r
- 让 AI 用一句话复述某个规则文件的核心约束 —— 如果 AI 表达模糊，说明规则正文太抽象，要加示例\r
- 故意让 AI 写一个违规代码片段 —— 看 AI 会不会在写之前主动指出"这不符合规则"，不会就是规则写得不够硬\r
\r
---\r
\r
## 与 `/init-memory-system` 的边界\r
\r
| 维度 | 本 skill 产物 | `/init-memory-system` 产物 |\r
|---|---|---|\r
| 性质 | 决议 + 法律 | 档案 |\r
| 内容 | 架构方向、结构边界、归属判断、禁止项 | 业务流程、模块边界、风险点、复用入口 |\r
| 落地位置 | `docs/architecture-refactor-rfc.md` + `.cursor/rules/**` | `.memory/**` + `.cursor/agents/**` + `.cursor/hooks/**` |\r
| 修改频率 | 低，决策稳定 | 高，随项目演进 |\r
\r
**严禁**在规则文件里写业务知识，**严禁**把记忆内容塞进规则。\r
\r
---\r
\r
## 可选参考模板：渐进型业务与视图分离架构\r
\r
如果 RFC 决议采用 `core / infrastructure / adapters / views` 的渐进型分层（适合多端复用、业务/视图分离的项目），可以直接生成下面这份模板作为 `.cursor/rules/业务与视图分离架构规则.mdc`。\r
\r
> ⚠️ 不是所有项目都适用。如果 RFC 决议中目录拓扑不是这种结构，请按 RFC 真实分层另写规则，**不要强行套用本模板**。\r
\r
````markdown\r
---\r
description: 渐进型业务与视图分离架构规则，用于约束 AI 将业务逻辑、基础设施、平台适配与 UI 表现放在正确层级\r
alwaysApply: true\r
---\r
\r
# 渐进型业务与视图分离架构规则\r
\r
## 核心目标\r
\r
```text\r
业务事实、业务流程、业务状态规则、业务数据契约进入 core。\r
请求机制、状态引擎、存储机制、缓存、日志等技术底座进入 infrastructure。\r
平台 API、框架绑定、运行环境差异进入 adapters。\r
页面结构、组件展示、交互触发、端侧 UI 状态进入 views。\r
```\r
\r
不得因为一段代码"跨端可复用"就直接放进 `core`。`core` ≠ `shared`，`core` 只代表业务核心。\r
\r
## 分层职责\r
\r
### core：业务核心层\r
\r
只回答"业务是什么、业务如何流转"。\r
\r
允许：业务模型、业务流程、业务用例、业务状态规则、业务数据契约、业务 API 契约、业务错误码语义、权限与鉴权规则、业务数据转换与格式化规则、可跨端复用的纯业务算法。\r
\r
禁止：axios / fetch / uni.request、Pinia / Zustand / Redux、localStorage / uni storage、Logger / Cache / EventBus 等技术机制、Vue / React / UniApp 组件、DOM、`window` / `document` / `localStorage`、`uni` / `wx` / Capacitor、路由跳转实现、Toast / Modal / Loading 实现。\r
\r
### core 内部组织：是否需要按业务模块垂直再切分\r
\r
判断标准（按 RFC §3 目录拓扑决定）：\r
\r
- 业务模块 ≤ 3 个：core 内可平铺组织（如 `core/auth/`、`core/order/`）\r
- 业务模块 ≥ 4 个：core 内必须按业务模块垂直再切，否则 core 会演化成"业务杂物间"\r
\r
垂直切分形态：\r
\r
```text\r
core/\r
├── {模块1}/\r
│   ├── domain/          业务模型 + 业务规则纯函数 + 接口契约\r
│   ├── application/     编排 domain 完成一个业务用例\r
│   ├── infrastructure/  数据源实现（实现 domain 中定义的接口）\r
│   └── ui/ 或 hooks/    业务模块专属的视图 / 数据流 hook（如有）\r
├── {模块2}/\r
│   └── ...\r
```\r
\r
跨业务模块通信：只能从 `core/{name}/index.ts`（barrel）import，禁止深路径访问其他模块的内部目录。\r
\r
### infrastructure：基础设施层\r
\r
只回答"技术机制如何组织"。\r
\r
允许：请求客户端抽象、请求拦截器、请求去重 / 超时 / 重试 / 取消、状态引擎封装、持久化、缓存、日志、事件总线、通用错误处理底座、与业务无关的通用工具。\r
\r
禁止：具体业务流程、具体业务判断、具体页面逻辑、具体 UI 组件、领域模型与业务用例。\r
\r
要求：infrastructure 不应知道"用户、订单、文章、消息"等具体业务语义。\r
\r
### adapters：平台适配层\r
\r
只回答"当前平台如何实现某个能力"。\r
\r
允许：axios / fetch / uni.request 等具体 HTTP 实现、localStorage / uni storage / AsyncStorage 等具体存储实现、vue-router / next/navigation / uni.navigateTo 等路由实现、Toast / Loading / Modal 实现、平台环境检测、Vue / React / UniApp 响应式绑定、Web / App / 小程序 / 桌面端运行时适配。\r
\r
要求：adapter 可以依赖平台 API 与 UI 框架；可以实现 infrastructure 定义的接口；不沉淀业务规则；对上层暴露稳定接口。\r
\r
**adapters 退化时**：单端项目 + 元框架已封装平台差异，可以不建 adapters 层；adapter 的职责由 infrastructure 的 Repository 实现承担。具体看 RFC §3 是否保留 adapters。\r
\r
### views：端侧视图层\r
\r
只回答"用户如何看到和操作"。\r
\r
允许：页面、组件、路由入口、端侧布局、UI 交互触发、临时 UI 状态、平台初始化代码、当前端独有且不会复用的展示逻辑。\r
\r
禁止：可跨端复用的业务流程、业务状态规则、业务数据转换、鉴权规则、统一错误码处理、可复用请求封装、可复用状态引擎、可复用领域模型。\r
\r
## 治理模式（按 RFC §5 中的选择二选一）\r
\r
### 选项 A：渐进式治理规则\r
\r
旧代码允许小修，新代码强制分层。\r
\r
修改旧代码时：允许在旧位置最小修复；禁止在旧错误结构上继续扩大业务逻辑、为小修复迁移整个模块、借修复之名重写无关代码。\r
\r
新增代码时强制：业务逻辑 / 状态规则 / 数据契约必须进入 `core`；请求 / 状态引擎 / 缓存 / 日志必须进入 `infrastructure`；平台差异和框架绑定必须进入 `adapters`；UI 表现必须进入 `views`；新增可复用能力前必须先判断它是业务能力还是技术机制。\r
\r
重构方向：将业务流程从 `views` 收敛到 `core`；将技术机制从 `core` 或 `views` 收敛到 `infrastructure`；将平台 API 与框架绑定移到 `adapters`；不为"抽离"创建空泛抽象。\r
\r
### 选项 B：一次性治理规则\r
\r
所有代码必须符合新分层，旧代码必须迁移到位。**不接受"小修豁免"**。\r
\r
修改旧代码时：必须先评估其归属层；位置不对的代码必须先迁移再修改；禁止在旧错误结构上做任何新增。\r
\r
新增代码时强制：同选项 A 的强制条款。\r
\r
重构方向：本项目处于集中重构期，所有不符合分层的代码视为架构债，必须在路线图中明确清理时间点。重构期间产生的"临时方案"必须挂明显 `TODO(arch-debt)` 注释 + 收敛时点。\r
\r
适用前提：RFC §5 中已明确选择"一次性"模式。\r
\r
## AI 写代码前的判断流程\r
\r
```text\r
1. 这是旧逻辑的小修吗？是 → 原位置最小修改，但不能扩大错误结构（仅渐进式模式有效；一次性模式必须先迁再改）。\r
2. 回答"业务是什么、业务如何流转"？是 → core\r
3. 回答"技术机制如何组织"？是 → infrastructure\r
4. 回答"当前平台如何实现某个能力"？是 → adapters（adapters 退化时归 infrastructure）\r
5. 回答"用户如何看到和操作"？是 → views\r
6. 这段逻辑可能被两个端复用吗？继续判断它是业务能力还是技术机制，不能因为可复用直接放 core。\r
7. 这段逻辑依赖具体平台 API 吗？是 → 不能直接写进 core，必须通过 adapter 注入或封装。\r
```\r
\r
## 输出要求\r
\r
涉及分层边界的修改，回复中必须简短说明：\r
\r
```text\r
本次改动属于：旧逻辑小修 / 新增业务能力 / 基础设施机制 / 平台适配 / UI 表现 / 重构收敛\r
放置位置理由：为什么放在 core / infrastructure / adapters / views\r
是否产生架构债：有 / 无；如果有，说明后续应如何收敛\r
```\r
\r
## 成功标准\r
\r
- `core` 越来越像业务能力中心，不是共享代码杂物间。\r
- `infrastructure` 承载稳定技术底座。\r
- `adapters` 集中处理平台差异（或在退化模式下由 infrastructure 承担）。\r
- `views` 越来越像端侧 UI 壳。\r
- 旧代码按 RFC §5 治理模式有序收敛。\r
````\r
\r
---\r
\r
## 收尾\r
\r
阶段 1 + 阶段 2 全部完成后，向用户输出一段简短摘要：\r
\r
- RFC 路径：`docs/architecture-refactor-rfc.md`\r
- 关键决策（治理模式 / adapters 是否保留 / core 是否垂直切 / 试点模块）\r
- 生成的规则文件清单（路径列表）\r
- 每个文件覆盖什么主题\r
- 提示用户：「架构决议与规则已就位。如需自动维护项目业务记忆，请运行 `/init-memory-system`。」\r
\r
不要输出"以下是修改记录"这类 changelog 内容 —— RFC 与 rules 本身记录了所有依据，不需要在外面再说一遍。\r