Skill: inksnowhailong/tvs-inksnow-arch (version 1.0.0)

--- 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 本身记录了所有依据，不需要在外面再说一遍。


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal:  | SkillSpector: clean (LOW)