Tvs Inksnow Arch

SKILL.md

---
name: tvs-inksnow-arch
description: 项目架构初始化与重构一体 Skill。何时使用：用户表达"我想重构架构 / 想改成 DDD / 想拆模块 / 想改成单端或多端 / 想拆掉 Redux 或 Pinia / 想初始化项目 .cursor/rules 架构规则 / 让 AI 知道代码该放哪 / 想梳理目录结构 / 项目越来越乱不知道在哪写新代码 / 重新整理分层 / 想定一套架构规范"等架构方向变更类需求时激活。作用：先访谈锁定架构决策（优先调用 tvs-deep-interview skill；不可用时走内置简化协议），产出 docs/architecture-refactor-rfc.md 等用户批准；再扫描项目当前结构并按 RFC 决议生成 .cursor/rules/*.mdc 强制约束，一次完成"想清楚"和"固化下来"两件事。不要在仅做单点 bug 修复、改文案、或对架构无变更的业务功能开发任务中激活。
---

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

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

## 角色定位

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

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

你不负责：

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

## 与其他工具的关系

```text
本 skill（tvs-inksnow-arch）     ← 决策（访谈 → RFC）+ 落地（生成 .cursor/rules/）一体
        ↓
/init-memory-system             ← 维护（业务记忆层）
```

推荐顺序：先跑本 skill，再跑 `/init-memory-system`。

---

# 阶段 1：决策（产出 RFC）

## 第一步：检查 `tvs-deep-interview` skill 是否可用

按以下顺序检查：

1. `Glob ~/.cursor/skills/tvs-deep-interview/SKILL.md`（用户级 skill 仓库）
2. `Glob .cursor/skills/tvs-deep-interview/SKILL.md`（项目级 skill）
3. 当前 Agent 环境的可用 skill 列表（如有元接口可查）

### 情况 A：已安装

直接进入第二步，全程参照 `tvs-deep-interview` SKILL 的访谈协议执行（Round 0 拓扑确认 → 一次一问 → 歧义评分 → 挑战模式 → 规格结晶）。

### 情况 B：未安装

向用户输出以下文本（**逐字输出，让用户清楚知情**）：

```text
当前未检测到 `tvs-deep-interview` skill。

这个 skill 是深度访谈的协议指导（Round 0 拓扑确认 / 一次一问 / 歧义评分 /
挑战模式 / 规格结晶），是 RFC 决策不跑偏的关键保障。强烈推荐安装后再进入访谈。

请选择：

A. 现在安装 tvs-deep-interview。
   我会暂停在这里，你装好后回复 "continue"，我接着进入访谈。

B. 跳过 skill，使用本 skill 内置的简化访谈协议。
   不评分、不挑战、不锁拓扑，能产出 RFC 但可能漏关键约束。
   适合只是想快速过一遍决策的场景。

C. 取消，暂不开始本流程。

请选 A / B / C。
```

用户回答 A / B / C 之前**不要进入第二步**。**不要替用户决定**。

### 情况 C：用户选 A 但回复 "continue" 后 skill 仍然不在

复查一遍（重新跑情况 A 的 Glob 检测）。若仍然没装上：

- 提示用户检查安装路径是否正确
- 告知可以改选 B 用简化协议先把 RFC 跑出来

## 第二步：深度访谈

### 情况 A 路径（已安装 tvs-deep-interview）

按该 skill 的协议执行：

1. **Round 0：拓扑确认** — 把用户的初始想法拆成 1~6 个顶层组件，确认拓扑后再进入循环
2. **循环访谈** — 一次只问一个问题，瞄准当前最弱清晰度维度
3. **歧义评分** — 每轮后评分（目标 / 约束 / 成功标准 / 上下文），歧义 ≤ 20% 才能进入规格结晶
4. **挑战模式**（Round 4+）— 反方 / 简化 / 本体 三种视角
5. **规格结晶** — 把对话整理成 RFC

### 情况 B 路径（用户选跳过，走简化协议）

按以下简化清单**逐项**询问，每个问题等用户回答后再问下一题（**禁止批量提问**）：

#### 问题 1：业务模块拓扑

```text
项目里有几个独立的业务能力？逐个列出来。
（例如：用户管理 / 订单 / 商品 / 客服 / 后台报表）
```

#### 问题 2：治理模式

```text
本次重构是渐进式还是一次性？
- 渐进式：旧代码允许保留，仅新代码强制新分层
- 一次性：旧代码必须全部迁移，重构期间项目可短期停摆
```

#### 问题 3：adapters 层是否保留

```text
项目是单端还是多端？
- 单端（仅 Web 或仅 Native）+ 用元框架（Next.js / Nuxt 等）→ adapters 退化合并到 infrastructure
- 多端 / 同一能力多个平台实现 → 保留完整 core/infrastructure/adapters/views 四层
```

#### 问题 4：core 内部组织

```text
你列出的业务模块有多少个？
- ≤ 3 个：core 内可平铺
- ≥ 4 个：core 内必须按业务模块垂直切（每个模块自包含 domain/application/infrastructure）
```

#### 问题 5：平台 / 框架约束

```text
项目使用什么前端 / 后端框架？
框架是否封装了平台差异（路由 / SSR / 存储等）？
```

#### 问题 6：数据源可换性需求

```text
未来是否需要"可换 ORM / 后端实现，业务文件 0 修改"？
- 是 → 业务模块必须用 Repository / Port 接口反转依赖
- 否 → infrastructure 可直接用具体技术栈
```

#### 问题 7：试点策略

```text
重构从哪个业务模块开始试点？
（推荐选最复杂或当前最痛的那一个，先验证范式）
```

#### 问题 8：执行时间窗口

```text
你预计多少天 / 周完成这次重构？
是否能接受重构期间项目暂停接需求？
```

简化协议下不做歧义评分，但每个回答后**简要复述一遍让用户确认**：

```text
我理解你的意思是：xxx。对吗？
```

用户确认后再问下一题。

## 第三步：产出 RFC

在 `docs/architecture-refactor-rfc.md` 写入以下结构（不存在则创建）：

````markdown
# 架构重构 RFC

## 元信息

- 版本：v1.0
- 日期：YYYY-MM-DD
- 状态：待批准
- 决策方式：tvs-deep-interview / 简化协议（按实际选择）

## 项目类型

- 单端 / 多端：xxx
- 使用框架：xxx
- 业务模块数量：xxx 个

## 1. 目标

（用 3~5 句话说清重构后项目要变成什么样）

## 2. 病因诊断（重构前的痛点清单）

| 痛点 | 现象 | 代码证据 |
|---|---|---|
| ... | ... | ... |

## 3. 目录拓扑（重构后的目标结构）

```text
src/
├── ...
```

## 4. 依赖规则

```text
A → B → C （单向依赖图）
```

每层的"允许 / 禁止"列表。

## 5. 治理模式

（渐进式 / 一次性，用户在访谈中的选择）

## 6. 验收信号

3~6 个可验证的"重构成功"信号，例如：

- S1: ...
- S2: ...

## 7. 试点策略

- 第一个试点模块：xxx
- 试点完成的验收信号：xxx
- 是否暂停看效果再铺开：xxx

## 8. 风险与代价

| 风险 | 影响 | 缓解 |
|---|---|---|
| ... | ... | ... |

## 9. 路线图

- 阶段 0：基础设施（生成 .cursor/rules/，运行 /init-memory-system 建记忆层）
- 阶段 1：试点（xxx 模块）
- 阶段 2：批量铺开
- 阶段 3：清理 & 收尾

## 10. 待确认问题（Open）

- ...
````

如果走情况 A 路径（深度访谈），按 tvs-deep-interview 的"规格结晶"段输出额外字段（清晰度拆解 / 拓扑 / 关键实体 / 本体收敛 / 访谈记录 等）。

## 第四步：等用户批准 RFC

RFC 写完后，向用户输出：

```text
RFC 已生成在 docs/architecture-refactor-rfc.md，请你认真过一遍。

下一步选项：

A. 批准 RFC，我接着进入阶段 2 生成 .cursor/rules/*.mdc 规则文件
B. 修改 RFC 某些章节（告诉我哪几条要改，我会就地修订成 v1.1）
C. 暂停，先消化

请选 A / B / C。
```

**在用户明确选 A 之前**：

- 不允许进入阶段 2
- 不允许修改任何业务代码

用户选 B 时反复迭代直到选 A 或 C。

---

# 阶段 2：落地（生成 .cursor/rules/）

**进入条件**：用户已在第四步选 A，明确批准 RFC。

## 第五步：扫描项目当前结构

阅读以下内容形成对项目结构的理解：

- 顶层目录结构
- `package.json` / `pnpm-workspace.yaml` 与依赖
- 主要入口文件（`main.ts` / `index.ts` / `App.vue` / `_app.tsx` 等）
- API 层 / 状态管理层 / 组件层
- 主要配置文件（`vite.config`、`next.config` 等）
- 已有架构文档或约定（README、AGENTS.md、`.cursor/rules` 已有内容）

把识别结果与 RFC 决议对照，找出**当前结构与 RFC 目标的差距**，作为规则文件生成的依据。

## 第六步：汇报生成计划，等用户最终确认

向用户输出三段：

1. **识别出的项目主要分层**（具体目录 → 含义）
2. **计划生成的规则文件列表**（文件名 + 主题）
3. **每个规则文件的职责**（一两句话说明）

然后停下来等用户确认，**用户没说"开始生成"前不要写盘**。

## 第七步：按主题生成规则文件

每个 `.mdc` 文件只关注一个主题，按 RFC 决议裁剪：

- 架构边界规则
- 代码分层规则
- 数据流规则
- 组件与界面规则
- 状态与副作用规则
- AI 协作规则

具体按项目实际情况选，不必每个主题都建一个文件。

---

## 规则文件硬性要求

- **格式**：`.mdc` 文件，文件名可中文或短横线，正文必须中文
- **基调**：短、硬、可执行
- **每条规则必须能回答**："这段代码应该放哪里、不能放哪里"
- **每个文件必须包含**：分层职责 + 禁止项 + 放置判断
- **禁止写**：
  - "保持代码整洁""提高可维护性"等空泛原则
  - 项目业务知识（那属于记忆层）
  - 修改建议或变更说明（规则不是 changelog）

每条规则要能让未来的 AI 在写代码前回答这些问题：

1. 这是业务事实 / 业务流程吗？
2. 这是技术机制吗？
3. 这是当前平台 / 框架的具体实现吗？
4. 这是用户看到和操作的吗？
5. 我现在改的代码属于"旧逻辑小修" / "新增能力" / "重构收敛" 哪一种？

具体分层名称按 RFC 决议中的目录拓扑（§3）来，不要硬套某种风格。

---

## 规则正文怎么写让 AI 读得懂

本 skill 生成的 `.cursor/rules/*.mdc` 不是写给人看的，是写给 AI 的。AI 在每次写代码前会自动加载 `alwaysApply: true` 的规则。要让规则真正发挥作用：

### 规则文件命名

- 按主题独立成文件，每个文件只解决一类问题
- 文件命名建议带数字前缀（`01-架构边界.mdc` / `02-模块化与DDD.mdc`），AI 加载时有稳定顺序
- 文件名可中文或短横线，正文必须中文

### 规则正文写法

- **短而硬**：每条规则一句话能讲清"这是禁止 / 允许"
- **可执行**：每条规则能让 AI 在写代码前回答"放哪 / 不放哪"
- **0 模糊词**：禁止 "应当 / 尽量 / 适当 / 合理" 等弱词，用 "必须 / 禁止 / 仅允许"
- **配示例**：每个"禁止项"举一个反模式代码片段，AI 看示例比看抽象更准

### 规则文件应当回答的固定问题

AI 写代码前会自问，规则文件必须能给答案：

1. 这是业务事实 / 业务流程吗？
2. 这是技术机制吗？
3. 这是当前平台 / 框架的具体实现吗？
4. 这是用户看到和操作的吗？
5. 我现在改的代码属于"旧逻辑小修" / "新增能力" / "重构收敛" 哪一种？

### 怎么验证规则真的有效

- 让 AI 用一句话复述某个规则文件的核心约束 —— 如果 AI 表达模糊，说明规则正文太抽象，要加示例
- 故意让 AI 写一个违规代码片段 —— 看 AI 会不会在写之前主动指出"这不符合规则"，不会就是规则写得不够硬

---

## 与 `/init-memory-system` 的边界

| 维度 | 本 skill 产物 | `/init-memory-system` 产物 |
|---|---|---|
| 性质 | 决议 + 法律 | 档案 |
| 内容 | 架构方向、结构边界、归属判断、禁止项 | 业务流程、模块边界、风险点、复用入口 |
| 落地位置 | `docs/architecture-refactor-rfc.md` + `.cursor/rules/**` | `.memory/**` + `.cursor/agents/**` + `.cursor/hooks/**` |
| 修改频率 | 低，决策稳定 | 高，随项目演进 |

**严禁**在规则文件里写业务知识，**严禁**把记忆内容塞进规则。

---

## 可选参考模板：渐进型业务与视图分离架构

如果 RFC 决议采用 `core / infrastructure / adapters / views` 的渐进型分层（适合多端复用、业务/视图分离的项目），可以直接生成下面这份模板作为 `.cursor/rules/业务与视图分离架构规则.mdc`。

> ⚠️ 不是所有项目都适用。如果 RFC 决议中目录拓扑不是这种结构，请按 RFC 真实分层另写规则，**不要强行套用本模板**。

````markdown
---
description: 渐进型业务与视图分离架构规则，用于约束 AI 将业务逻辑、基础设施、平台适配与 UI 表现放在正确层级
alwaysApply: true
---

# 渐进型业务与视图分离架构规则

## 核心目标

```text
业务事实、业务流程、业务状态规则、业务数据契约进入 core。
请求机制、状态引擎、存储机制、缓存、日志等技术底座进入 infrastructure。
平台 API、框架绑定、运行环境差异进入 adapters。
页面结构、组件展示、交互触发、端侧 UI 状态进入 views。
```

不得因为一段代码"跨端可复用"就直接放进 `core`。`core` ≠ `shared`，`core` 只代表业务核心。

## 分层职责

### core：业务核心层

只回答"业务是什么、业务如何流转"。

允许：业务模型、业务流程、业务用例、业务状态规则、业务数据契约、业务 API 契约、业务错误码语义、权限与鉴权规则、业务数据转换与格式化规则、可跨端复用的纯业务算法。

禁止：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 实现。

### core 内部组织：是否需要按业务模块垂直再切分

判断标准（按 RFC §3 目录拓扑决定）：

- 业务模块 ≤ 3 个：core 内可平铺组织（如 `core/auth/`、`core/order/`）
- 业务模块 ≥ 4 个：core 内必须按业务模块垂直再切，否则 core 会演化成"业务杂物间"

垂直切分形态：

```text
core/
├── {模块1}/
│   ├── domain/          业务模型 + 业务规则纯函数 + 接口契约
│   ├── application/     编排 domain 完成一个业务用例
│   ├── infrastructure/  数据源实现（实现 domain 中定义的接口）
│   └── ui/ 或 hooks/    业务模块专属的视图 / 数据流 hook（如有）
├── {模块2}/
│   └── ...
```

跨业务模块通信：只能从 `core/{name}/index.ts`（barrel）import，禁止深路径访问其他模块的内部目录。

### infrastructure：基础设施层

只回答"技术机制如何组织"。

允许：请求客户端抽象、请求拦截器、请求去重 / 超时 / 重试 / 取消、状态引擎封装、持久化、缓存、日志、事件总线、通用错误处理底座、与业务无关的通用工具。

禁止：具体业务流程、具体业务判断、具体页面逻辑、具体 UI 组件、领域模型与业务用例。

要求：infrastructure 不应知道"用户、订单、文章、消息"等具体业务语义。

### adapters：平台适配层

只回答"当前平台如何实现某个能力"。

允许：axios / fetch / uni.request 等具体 HTTP 实现、localStorage / uni storage / AsyncStorage 等具体存储实现、vue-router / next/navigation / uni.navigateTo 等路由实现、Toast / Loading / Modal 实现、平台环境检测、Vue / React / UniApp 响应式绑定、Web / App / 小程序 / 桌面端运行时适配。

要求：adapter 可以依赖平台 API 与 UI 框架；可以实现 infrastructure 定义的接口；不沉淀业务规则；对上层暴露稳定接口。

**adapters 退化时**：单端项目 + 元框架已封装平台差异，可以不建 adapters 层；adapter 的职责由 infrastructure 的 Repository 实现承担。具体看 RFC §3 是否保留 adapters。

### views：端侧视图层

只回答"用户如何看到和操作"。

允许：页面、组件、路由入口、端侧布局、UI 交互触发、临时 UI 状态、平台初始化代码、当前端独有且不会复用的展示逻辑。

禁止：可跨端复用的业务流程、业务状态规则、业务数据转换、鉴权规则、统一错误码处理、可复用请求封装、可复用状态引擎、可复用领域模型。

## 治理模式（按 RFC §5 中的选择二选一）

### 选项 A：渐进式治理规则

旧代码允许小修，新代码强制分层。

修改旧代码时：允许在旧位置最小修复；禁止在旧错误结构上继续扩大业务逻辑、为小修复迁移整个模块、借修复之名重写无关代码。

新增代码时强制：业务逻辑 / 状态规则 / 数据契约必须进入 `core`；请求 / 状态引擎 / 缓存 / 日志必须进入 `infrastructure`；平台差异和框架绑定必须进入 `adapters`；UI 表现必须进入 `views`；新增可复用能力前必须先判断它是业务能力还是技术机制。

重构方向：将业务流程从 `views` 收敛到 `core`；将技术机制从 `core` 或 `views` 收敛到 `infrastructure`；将平台 API 与框架绑定移到 `adapters`；不为"抽离"创建空泛抽象。

### 选项 B：一次性治理规则

所有代码必须符合新分层，旧代码必须迁移到位。**不接受"小修豁免"**。

修改旧代码时：必须先评估其归属层；位置不对的代码必须先迁移再修改；禁止在旧错误结构上做任何新增。

新增代码时强制：同选项 A 的强制条款。

重构方向：本项目处于集中重构期，所有不符合分层的代码视为架构债，必须在路线图中明确清理时间点。重构期间产生的"临时方案"必须挂明显 `TODO(arch-debt)` 注释 + 收敛时点。

适用前提：RFC §5 中已明确选择"一次性"模式。

## AI 写代码前的判断流程

```text
1. 这是旧逻辑的小修吗？是 → 原位置最小修改，但不能扩大错误结构（仅渐进式模式有效；一次性模式必须先迁再改）。
2. 回答"业务是什么、业务如何流转"？是 → core
3. 回答"技术机制如何组织"？是 → infrastructure
4. 回答"当前平台如何实现某个能力"？是 → adapters（adapters 退化时归 infrastructure）
5. 回答"用户如何看到和操作"？是 → views
6. 这段逻辑可能被两个端复用吗？继续判断它是业务能力还是技术机制，不能因为可复用直接放 core。
7. 这段逻辑依赖具体平台 API 吗？是 → 不能直接写进 core，必须通过 adapter 注入或封装。
```

## 输出要求

涉及分层边界的修改，回复中必须简短说明：

```text
本次改动属于：旧逻辑小修 / 新增业务能力 / 基础设施机制 / 平台适配 / UI 表现 / 重构收敛
放置位置理由：为什么放在 core / infrastructure / adapters / views
是否产生架构债：有 / 无；如果有，说明后续应如何收敛
```

## 成功标准

- `core` 越来越像业务能力中心，不是共享代码杂物间。
- `infrastructure` 承载稳定技术底座。
- `adapters` 集中处理平台差异（或在退化模式下由 infrastructure 承担）。
- `views` 越来越像端侧 UI 壳。
- 旧代码按 RFC §5 治理模式有序收敛。
````

---

## 收尾

阶段 1 + 阶段 2 全部完成后，向用户输出一段简短摘要：

- RFC 路径：`docs/architecture-refactor-rfc.md`
- 关键决策（治理模式 / adapters 是否保留 / core 是否垂直切 / 试点模块）
- 生成的规则文件清单（路径列表）
- 每个文件覆盖什么主题
- 提示用户：「架构决议与规则已就位。如需自动维护项目业务记忆，请运行 `/init-memory-system`。」

不要输出"以下是修改记录"这类 changelog 内容 —— RFC 与 rules 本身记录了所有依据，不需要在外面再说一遍。