Legacy

任务架构 — AI 编程项目架构管理

最高原则：architecture.json 是唯一真相源

architecture.json ≡ 项目的全部真相
  任何改动，必须先改 JSON，再改代码。代码追随 JSON，JSON 不追随代码。

三条铁律：

1. JSON 先行：需求变更、功能新增、Bug修复、重构——一律先改 JSON，再改代码。
2. JSON 是法官：代码与 JSON 不一致时，JSON 是对的，修正代码。
3. 禁止代码漂移：代码中不得出现 JSON 未定义的模块/文件/接口。需要超出范围时，先更新 JSON。

五大核心机制

机制1: 最大主动性设计（工程层面）
  → 让项目"能用"：主动补全安全/日志/监控/部署/测试

机制2: 功能簇展开（产品层面）
  → 让功能"完整"：用户说一个功能名，AI 展开为一组天然绑定的子功能

机制3: 交互完整性（体验层面）
  → 让交互"到位"：每个操作有完整的请求→反馈→异常→恢复闭环

机制4: 多层递进设计（认知层面）
  → 让 AI "想得深"：分阶段输出，每阶段聚焦一个层面

机制5: 分治设计法（执行层面）
  → 让 AI "不遗漏"：大功能拆小块，每块深度设计

架构的五个维度

项目类型	功能	数据	交互	运行时	入口
web-fullstack	✅	✅	✅	✅	✅
web-backend	✅	✅	—	✅	✅(API)
web-frontend	—	✅(状态)	✅	✅	✅(路由)
cli	✅	✅(配置)	—	✅	✅(命令)
desktop	✅	✅	✅	✅	✅(菜单)
mobile	✅	✅	✅	✅	✅
embedded/iot	✅	✅	—	✅	✅
library/sdk	✅	—	—	—	✅(公开API)

最大主动性设计

用户描述的是"想要什么"，AI 的职责是思考"应该是什么"。

设计前必须自问

维度	问题	最小保障
安全	数据如何保护？认证鉴权？敏感信息脱敏？	环境变量存密钥
可观测	怎么排查问题？日志在哪？关键指标？	结构化日志到stdout
容错	外部服务挂了怎么办？	统一错误响应格式
部署	怎么部署？健康检查？	Dockerfile+健康检查
数据	数据存哪？备份？迁移？	数据库迁移脚本
扩展	以后会不会塌？	模块化目录结构

补全规则

• 商业级标配（日志/错误处理/健康检查/迁移）→ 直接纳入，不询问
• 有多个合理方案（如"Redis vs PG 做缓存"）→ 询问用户选择
• 用户描述的功能之外发现重要缺失 → 主动建议，附理由

功能簇展开

用户说的是一个功能名称，AI 应理解这个名称背后是一组天然绑定的子功能。"做一个卡密系统"不等于"做一个卡密生成页面"，"做一个菜单栏"不等于"画一条横条"。

核心原则

用户说的 ≠ 用户需要的全部
一个功能名 = 一个功能簇（核心功能 + 衍生功能 + 关联功能）

"菜单栏" →
  不只是菜单条本身，天然包含：
    每个菜单项的点击行为、下拉子菜单、快捷键绑定、
    菜单项的启用/禁用状态、右键上下文菜单、系统托盘菜单
  → 这些不是"额外功能"，是"菜单栏"这个词自带的东西

"卡密系统" →
  不只是卡密生成，天然包含：
    生成(单条/批量/模板)、管理列表、验证接口、
    使用记录、状态管理(未用/已用/过期/禁用)、导出
  → 这些不是用户忘了说，是"卡密系统"这个词的完整含义

展开三维度

设计前，按三个维度自动展开功能簇：

第1维：功能使用流程
  "这个东西的完整使用链路是什么？"
  卡密：创建→分发→使用→验证→记录→管理→统计  → 每步对应子功能

第2维：功能生命周期
  "这个东西从生到死经历什么状态？"
  卡密：未使用→已使用→已过期→已禁用  → 每个状态需要对应操作和页面

第3维：生产上下文
  "这个功能在真实产品中跟什么关联？"
  卡密→谁创建的？（账号）→怎么来的？（支付）→异常怎么办？（风控）
  → 关联功能可能需要一并考虑

展开流程

用户描述需求 → AI 第一个动作（不写代码，不画界面）：

1. 功能簇展开：
   输入："[用户说的功能名]"
   输出：
     核心功能簇（第1维，功能自身的完整使用链路）
     衍生功能簇（第2维，生命周期管理）
     关联功能簇（第3维，生产中的上下文关联）

2. 向用户汇报功能全景：
   "这个功能按标准应包含：核心①-⑥，衍生⑦-⑨，关联⑩-⑪。
    建议优先做核心簇，衍生和关联根据你的实际场景决定。"

3. 用户确认范围 → 进入拆块+逐块设计

展开深度

默认标准展开（核心+衍生全部列出，让用户砍），不能默认浅展开（浅展开=用户说一个只做一个=现在的行为）。

深度	何时用	内容
标准展开	默认	核心+衍生全部列出，用户砍
浅展开	用户明确说"只做XX，其他不要"	只展开核心簇
深展开	大型项目/用户要求完整方案	核心+衍生+关联全部列出，标注依赖

交互完整性

AI 设计任何东西时，自动检查"这个交互完整吗"——不是用户提醒，是 AI 在设计完成后自动对照检查表补全。

全局铁律（所有项目类型，所有组件/接口/命令）

□ 请求闭环：请求→处理中→成功反馈→失败处理，缺一不可
□ 错误信息："出了什么问题 + 建议怎么做"，禁止 "Error: 500"
□ 进度反馈：超过 1 秒的操作必须有进度指示
□ 中断恢复：Ctrl+C/关闭/超时必须有清理逻辑

按项目类型的检查包

设计任何组件/接口/命令时，根据项目类型自动加载对应检查包，逐项对照。未覆盖的项必须补充到设计中。

Web/桌面/移动：
  表单：校验+loading+成功反馈+失败处理+键盘提交+未保存离开确认
  列表：骨架屏+空引导+加载失败重试+分页/无限滚动
  详情：骨架屏+不存在提示+加载失败重试+操作后状态同步
  操作(删/改)：确认弹窗(含操作对象名称)+操作loading+成功toast+失败toast+列表刷新
  搜索：输入防抖300ms+搜索loading+无结果引导+错误重试
  全局：网络断开提示+登录过期重新引导

CLI：
  命令：--help完整+参数校验+长操作进度+错误退出码非零+Ctrl+C清理
  管道：--json/--quiet模式+stdin/stdout支持
  全局：--version+配置文件缺失引导

API/后端：
  接口：统一响应格式+每个错误码有具体描述+列表接口有分页信息+请求ID
  全局：健康检查端点+OpenAPI文档+可写操作返回变更后资源

库/SDK：
  公开API：类型标注+异常有清晰层级+每个异常触发条件文档说明+默认值合理
  全局：README有3行快速开始+CHANGELOG+每个公开函数有docstring

嵌入式/IoT：
  硬件交互：断线重连策略+看门狗/掉电保存+状态指示(LED/显示屏/串口)
  全局：启动自检序列+错误恢复流程文档

触发时机

阶段3逐块设计时，每个块的设计末尾：
  1. 识别当前设计的组件/接口/命令类型
  2. 加载对应项目类型的检查包
  3. 逐项对照 → 自动补全未覆盖的项
  4. 在设计输出末尾标注"交互完整性: 通过N/M项, N项未覆盖(附原因)"

---

多层递进设计（分阶段输出）

核心问题：一次思维过程中同时思考 10+ 个模块，思考深度必然被稀释。

解决方案：分阶段输出。每个阶段只聚焦一个层面，前阶段结论锁定后作为下一阶段的输入前提。这不是多次 API 调用，而是 Agent 在单次执行中将思维过程阶段化。

四阶段递进

阶段1：商业化全景分析
  聚焦："这个项目按商业标准应该是什么样"
  输出：项目类型、技术栈推荐、五大维度初稿、补全清单
  ↓ 结论锁定

阶段2：拆块 + 骨架设计
  聚焦："怎么拆块 + 基础设施怎么定义"
  输入：阶段1的全景文档
  输出：拆块清单（含优先级和依赖）+ 骨架 architecture.json（仅基础设施）
  ↓ 结论锁定

阶段3：逐块深度设计
  聚焦：每次只关注"一个块的完整细节"
  输入：骨架JSON + 前面块的接口签名摘要 + 当前块要求
  输出：当前块完整设计（接口/异常/测试/数据表/组件树）+ 更新JSON + 代码 + 测试
  ↓ 自动进入下一块

阶段4：集成验证
  聚焦："接口一致性、依赖完整性、跨模块矛盾"
  输出：验证报告 + 修复建议

阶段间信息传递

只传结论，不传思考过程。 每个阶段把前一阶段的输出作为既定前提，不需要重新分析。

architecture.json 的四层递进结构

核心问题：扁平 JSON 把所有信息堆在同一层级——路由、接口签名、组件树、数据库字段全混在一起。AI 做任何任务都要吞下全部细节，导致"东一块西一块"——它无法区分"全局骨架"和"局部细节"。

解决方案：将 architecture.json 设计为四个递进层级。AI 做不同任务时读不同深度：

第1层：项目骨架          第1次读取（任何操作的第一步）
  ├── 项目身份（类型/语言/框架）
  ├── 入口结构（路由树/CLI命令树）
  ├── 模块拓扑（节点列表+依赖图，只有名称和关系）
  ├── 页面拓扑（页面列表+依赖的模块）
  └── 数据拓扑（表列表+所属模块）
  → AI 读完就知道"项目有几层、入口在哪、谁依赖谁"
  → 加新功能时，只需这一层就能判断新模块应该插在哪里

第2层：接口契约          需要调用已有模块时读取
  ├── 每个模块的导出接口签名（名称+参数类型+返回类型+可能异常）
  └── 每个模块的依赖声明（依赖谁+使用哪些接口）
  → AI 知道"能调用什么、怎么调用、会出什么错"
  → 写新模块代码时，只读它依赖模块的第2层

第3层：实现清单          开始写具体模块代码时读取
  ├── 每个模块的文件列表（路径+说明）
  ├── 每张数据库表定义（字段/约束/索引/迁移路径）
  └── 每个页面的组件树骨架（组件名+嵌套关系）
  → AI 知道"要创建哪些文件、每个文件写什么"

第4层：完整细节          写具体函数/组件代码或调试时读取
  ├── 每个接口的完整参数说明+实现约束+测试用例
  ├── 每个组件的属性列表+交互事件链+五态展示
  └── 每个页面的布局+接口调用时序
  → 写具体代码时不需要猜任何东西

关键规则：永远不要一次性把第4层的全部内容喂给 AI。
只传当前任务相关模块的第4层。

防越层规则（硬约束）：

使用 architecture.json 时（修改/编码/调试），AI 必须：

1. 先声明：本次任务需要读哪几层、哪些模块
2. 只读声明的层和模块：编码 m6 时，只读 m6 的第3-4层 + m6依赖模块的第2层
3. 不得以"了解项目全貌"为由读取无关模块的第4层细节
4. 如果发现需要额外信息，再次声明补充读取，而不是一次性全读

违反此规则 = JSON 的四层设计被架空，退化为扁平 JSON。

完整 Schema 见 references/schemas.md。

分治设计法

大功能 → 拆小块清单 → 逐块深度设计 → 自动推进 → 集成验证。

单块设计标准

每块必须达到：另一个不熟悉项目的开发者能独立写出完整代码。

每块设计按四层递进输出到 architecture.json：

• 第1层补充：把当前块加入模块拓扑+依赖图+页面拓扑+数据拓扑
• 第2层完整：当前块的导出接口完整签名 + 依赖声明（不允许省略任何参数/异常）
• 第3层完整：文件列表（1-5文件）、关联数据表DD、页面组件树骨架
• 第4层完整：每个接口的实现约束+测试用例、每个组件的属性/事件/五态
• 交互完整性检查：设计完成后自动对照项目类型的检查包，逐项确认或补全，标注检查结果

块的大小控制

项目类型	一个块大约等于
后端	1个模块（2-5文件）+ 关联1-2张表
前端	1个页面 + 完整组件树（3-10组件）
全栈	1个后端模块 + 1个对应前端页面
CLI	1个命令 + 参数/选项/错误码

拆块原则

✅ 好："用户管理系统" → ①数据库连接 ②用户模型+表 ③CURD服务 ④API路由 ⑤登录页 ⑥管理页
❌ 差："用户管理系统" → ①所有后端 ②所有前端（太大了）

四个命令

/分析架构 — 从代码逆向生成架构

触发：已有项目代码，想纳入架构管理。

流程：

1. 扫描项目目录结构，识别技术栈和框架
2. 分析模块边界（目录结构 + import关系 + 类/函数职责聚类）
3. 提取每个模块的导出接口（函数签名、类方法）
4. 构建模块依赖图（从 import 语句推导）
5. 对照完整性检查清单（见 references/schemas.md），标记已有覆盖和缺失项
6. 生成 architecture.json
7. 汇报：架构概况 + 完整性检查结果（已覆盖/缺失/建议补充）

关键：主动指出缺失的基础设施模块（没有日志？没有迁移？没有健康检查？），这些是已有项目最常见的缺口。

/创建架构 — 从零搭建项目架构

触发：新项目从零开始。

流程：

阶段1：全景分析
  1. 理解需求 → 功能簇展开（标准展开列出核心+衍生子功能→用户确认范围）
  2. 确定项目类型 → 五大维度启用哪些
  3. 最大主动性设计：主动补全缺失关注点
  4. 推荐技术栈

阶段2：拆块+骨架
  4. 拆块清单（名称、优先级、依赖关系）
  5. 基础设施模块详细定义（配置/日志/错误/迁移/健康检查）
  6. 运行时+入口架构定义
  7. 生成骨架 architecture.json（不包含业务模块）

阶段3：逐块设计
  8. 按依赖顺序自动逐块深度设计 → 更新JSON → 编码 → 测试
  9. 每块完成后提取接口签名摘要，传给下一块

阶段4：集成验证
  10. 检查接口一致性 → 汇报总结

禁止：在阶段2预定义业务模块。骨架JSON只有基础设施。业务模块只在阶段3逐块加入。

/修改架构 — 修改已有内容

触发：修改已存在的模块/文件/接口/表/组件/路由等任何已在 JSON 中的内容。

与 /追加架构 的边界：

• 改已有模块的任何东西（文件/接口/状态）→ /修改架构
• 新增一个 JSON 中不存在的模块 → /追加架构
• 给已有模块新增文件或导出接口 → /修改架构（不是追加，是修改已有模块）

流程：

1. 读取 architecture.json，定位目标模块
2. 影响范围分析（修改前必做）：
   • 从依赖图找出所有依赖目标模块的下游模块
   • 判断变更级别：接口级（破坏性）还是实现级（非破坏性）
   • 接口级变更 → 列出所有受影响的下游接口调用点
3. 更新 JSON + 追加变更记录
4. 级联处理：
   • 接口签名变化 → 重置所有下游模块状态为"计划中"，按依赖顺序重新验证
   • 内部实现变化 → 只改当前模块状态，下游模块不受影响
   • 删除导出 → 检查下游是否存在悬空依赖，如有则必须同步修改下游
5. 按更新后的 JSON 修改代码 + 运行受影响模块的测试

安全修改模式：

变更类型	影响范围	处理方式
改函数内部实现	仅当前模块	改代码→跑测试→完成
新增导出接口	仅当前模块	更新JSON→加代码→加测试
改接口参数（新增可选参数）	当前模块	向后兼容，下游不受影响
改接口参数（改类型/删参数）	当前+所有下游	先更新所有下游的调用代码，再改当前模块
改数据库表结构	当前+所有操作该表的模块	先写迁移脚本，再依次更新各模块
拆分模块	新增模块+原模块+下游	先创建新模块→迁移接口→更新下游引用→删除旧代码
合并模块	合并后的模块+下游	先创建合并模块→迁移所有接口→更新下游引用→删除旧模块

/追加架构 — 新增不存在的模块

触发：新增 JSON 中不存在的模块/功能。

流程：

1. 读取 architecture.json
2. 功能簇展开（用户说的功能名 → 展开核心+衍生子功能 → 用户确认范围）
3. 确认后自动拆块 → 逐块深度设计 → 自动推进
4. 全部完成后汇报

单块模式：如果新增内容不超过一个块的规模，直接深度设计+编码+测试。

状态流转

模块状态：计划中 → 编写中 → 待测试 → 测试中 → 已完成
              │         │           │
              └── 已废弃 ←── 修复中 ←─┘

文件状态：计划中 → 编写中 → 已完成 → 待审查
              │         │
              └── 已废弃 ←── 修复中

转换规则：

• 模块依赖的所有模块必须"已完成"，该模块才能"编写中"
• 模块下所有文件"已完成"后，模块自动变为"待测试"
• 测试失败 → 相关模块和文件变为"修复中"

拆分原则

应该拆（满足任一）：有独立对外接口、被其他模块依赖、可独立编译测试、职责明显不同。 不应该拆（满足任一）：仅内部辅助函数、会循环依赖、文件预计<50行、拆分后高度耦合。 粒度：一个模块 1~5 个文件。超过 5 个考虑再拆，但必须有职责上的理由。

工作流程

从 JSON 到代码

architecture.json 就绪
    ↓
按优先级顺序，每个模块：
  1. 读第1层确认依赖模块是否全部"已完成"（是则继续，否则等待）
  2. 读第2层获取当前模块的接口契约（导出什么+依赖谁）
  3. 读第3层获取文件清单+数据表DD→创建目录和文件骨架
  4. 读第4层获取当前模块的完整细节→按接口签名填充实现→按测试用例生成测试
  5. 运行测试 → 通过则标记"已完成" → 进入下一模块

四层读取逐模块递进：写 m6 时只读 m6 的第4层 + 它依赖模块（m4, m2）的第2层。不读无关模块的任何层。

完整开发流程

/创建架构 或 /分析架构 → architecture.json 就绪
    ↓
逐块设计 + 编码 + 测试 → 自动推进直到全部"已完成"
    ↓
集成验证 → 最终产物

中断恢复

读取 architecture.json 的状态字段即可知道：哪些已完成、哪些进行中、下一个该做什么。

调试与排错

architecture.json 也是排错地图。当出现 Bug 时，利用 JSON 的以下信息快速定位：

定位流程：

Bug 报告 → 确定出问题的模块编号
    │
    ├── 查 JSON 的 依赖 字段 → 是上游传错数据，还是本模块逻辑错误？
    │   如果上游接口返回的数据不对 → 追溯到上游模块
    │
    ├── 查 JSON 的 接口.导出 → 实际调用参数是否符合接口签名？
    │   参数类型不匹配 → 调用方的问题
    │   参数正确但结果错误 → 本模块实现问题
    │
    ├── 查 JSON 的 接口.可能异常 → 这个异常是否被正确处理？
    │   未列出的异常 → JSON 定义不完整，需更新
    │   已列出但未捕获 → 代码实现遗漏
    │
    └── 查 JSON 的 测试用例 → 这个 Bug 场景是否有覆盖？
        没有 → 先补测试用例到 JSON，再修代码
        有但测试未发现 → 测试实现有误，修正测试

常见排错模式：

症状	JSON 诊断	修复方式
模块A调用模块B报错	检查B的接口签名和可能异常	如A的参数不符合签名→修A；如B少列了异常→更新B的JSON
数据表字段缺失	检查数据架构中的表定义	表定义不完整→/修改架构补字段+写迁移
组件状态异常	检查组件的状态展示五态定义	某态未定义→补定义；实现不符合定义→修代码
循环依赖报错	检查依赖图	/修改架构重构去除循环
测试通过但线上异常	检查测试用例是否覆盖该场景	补测试用例到JSON→补测试代码→复现→修复

修复后必须做的事：

1. 更新 JSON 变更记录（原因写明 Bug 根因）
2. 补充测试用例到 JSON（覆盖本次 Bug 场景）
3. 检查是否有同类问题存在于其他模块（同类接口、同类组件）

项目优化

优化项目 = 优化 architecture.json，然后重新生成代码。 不存在"绕过 JSON 直接优化代码"的路径。

优化发现：定期检查 architecture.json 中的以下信号自动发现优化点：

信号1: 模块文件数 > 5 → 考虑拆分
信号2: 模块文件数 = 1 且 < 50行 → 考虑与相关模块合并
信号3: 依赖链深度 > 4 → 中间层可能过度抽象
信号4: 同一模块被 5+ 个模块依赖 → 考虑是否过于中心化
信号5: 测试用例仅覆盖 happy path → 补充边界和异常测试
信号6: 变更记录中同一模块频繁修改 → 接口设计可能不稳定
信号7: 多个模块有相同的导出签名 → 提取公共接口/基类
信号8: 组件树的属性很多但默认值为空 → 组件可能过度设计

优化决策矩阵：

优化目标	识别方式	操作
性能优化（接口不变）	分析/监控发现瓶颈	更新目标模块变更记录 → 改实现 → 跑测试
重构拆分	模块文件 > 5 或职责混杂	/修改架构拆成2个模块 → 定义新接口和依赖 → 逐模块重写
重构合并	小模块且高度耦合	/修改架构合并 → 更新接口列表 → 合并代码
消除循环依赖	依赖图分析发现环	/修改架构重构依赖关系 → 可能需要提取公共接口
补充测试覆盖	测试用例缺少边界/异常	更新JSON测试用例 → 补测试代码
升级框架/库	项目信息中的版本号	/修改架构更新项目信息+受影响模块接口 → 逐模块适配
提取公共代码	多模块重复的导出签名	/追加架构新增公共模块 → /修改架构让各模块依赖公共模块

优化原则：

• 先改 JSON 再改代码——优化的第一步永远是更新 architecture.json
• 一次优化只做一件事——不要同时拆分+合并+升级
• 每次优化后跑全部受影响模块的测试——不只是当前模块
• 优化完成后在变更记录中注明"为什么优化"（性能数据？可维护性？）

智能关联路由

architecture.json 的节点之间有天然的关联关系。修改一个节点时，AI 沿着关联链自动"联想"到受影响的其他节点——不需要死记硬背规则，而是理解节点之间的牵引关系。

关联链模型

JSON 中的每个节点都属于某种类型，不同节点类型之间存在固定的关联牵引力：

模块拓扑 ──牵引──→ 接口契约（模块定义了什么接口）
接口契约 ──牵引──→ 接口契约（m6.auth 被哪些模块依赖？）
接口契约 ──牵引──→ 入口路由（需要登录的页面依赖 auth.validate_session）
入口路由 ──牵引──→ 页面拓扑（这个路由对应哪个页面？）
页面拓扑 ──牵引──→ 组件树（这个页面由哪些组件构成？）
组件树   ──牵引──→ 完整细节（这个组件的属性和事件是什么？）
数据拓扑 ──牵引──→ 实现清单（这张表的字段和迁移路径是什么？）

联想引擎

修改 JSON 时，分三步自动联想：

第1步：直接联想（我碰了什么，就联想到什么）

碰了 X 节点的 Y 字段
  → 沿着关联链向外辐射一层：X 直接关联的所有节点进入"关注列表"
  → 例如：改了 m6 的接口签名 → 直接联想到所有依赖 m6 的模块

第2步：概念联想（这个改动在业务上意味着什么，还想到了什么）

分析改动的业务语义：
  "加了认证模块" →
    功能簇联想：认证→登录+注册+密码重置+邮箱验证+会话管理+记住我+个人中心
    交互完整性联想：登录(表单类)→校验/loading/成功跳转/失败提示/键盘提交
    工程联想：涉及用户身份→入口路由中哪些页面需要保护；涉及会话→数据拓扑需要sessions表

  "加了菜单栏" →
    功能簇联想：菜单栏→每个菜单项的下拉子菜单+点击行为+快捷键+启用/禁用状态+
               右键上下文菜单+系统托盘+菜单项与路由/命令的绑定
    交互完整性联想：菜单项(操作类)→点击展开/高亮当前项/禁用态tooltip/快捷键提示

  "改了数据库表 users" →
    工程联想：涉及数据迁移→迁移脚本；涉及ORM→依赖此表的所有模块需要检查
    交互完整性联想(API)：返回User对象的接口是否需要更新字段？响应格式是否一致？

第3步：一致性联想（改动后，整个 JSON 还自洽吗？）

做完改动后自动检查：
  入口路由中标记"需登录"的页面 → 是否都依赖了 auth.validate_session？
  接口契约中 m6 导出的接口 → 是否都有对应的实现清单（文件列表）？
  数据拓扑中的表 → 是否都有对应的迁移脚本？
  页面拓扑中的页面 → 是否都在入口路由中有路由？
  完整细节中的测试用例 → 是否覆盖了接口契约中列出的所有可能异常？

联想深度控制

改动规模	联想深度	说明
加一个模块	深联想（3层）	模块→接口→页面→路由→数据表，全链路联想
改一个接口签名	中联想（2层）	接口→下游模块→下游模块的调用代码
改内部实现	浅联想（1层）	只联想本模块的测试用例
修 Bug	点联想（0层+补测试）	不联想其他节点，只补当前 Bug 场景的测试用例

联想但不盲动

联想出来的节点是"提醒检查"，不是"直接修改"。AI 必须：

1. 列出联想到的所有节点
2. 逐一判断是否真的受影响
3. 只修改确认受影响的节点
4. 对不确定的节点标注"建议人工检查"

优先级与冲突解决

五大机制可能产生冲突。当机制建议不一致时，按以下优先级裁决：

优先级（从高到低）：
  1. 用户明确意愿    — 用户说"不要XX"，就真的不要，不因为机制建议而绕过
  2. 工程铁律        — 安全/数据保护/不可逆操作的前置确认，不可被机制覆盖
  3. 功能簇展开建议  — 高于交互完整性（先确定做什么，再确定怎么做）
  4. 交互完整性检查  — 高于设计便利性（多写几个状态处理 > 图省事）
  5. 多层递进流程    — 高于执行速度（按阶段走 > 跳步快出）

常见冲突处理示例：

冲突	裁决
功能簇展开建议加注册页 vs 用户说只要登录	用户意愿优先，但提醒"没有注册页，用户从哪来？"
交互完整性要求表单有"离开确认" vs 登录页实际不需要	交互完整性低优先级，标注"不适用"即可跳过
最大主动性要求加日志 vs 用户项目是 20 行脚本	工程铁律让位于用户意愿，但标注"建议日志"
多层递进要求分阶段输出 vs 项目只有 3 个模块	用户意愿可选跳过部分阶段，但不跳过一致性校验
分治设计要求拆块 vs 用户想一次性写完	分治设计高于速度，但可以让用户选择"连着做不确认"

原则：机制是建议引擎，不是束缚。用户知道自己的项目比机制更清楚。但安全相关（密码明文存储、SQL注入、数据丢失）不可妥协。

关键规则

接口即合同

模块的"导出"是对下游的承诺。修改导出接口时，必须检查所有依赖链上的模块，受影响模块状态重置为"计划中"。

变更记录不可省略

每次修改 JSON 必须在变更记录中追加：时间、操作类型、原因、影响范围。即使只改一行代码的 Bug，也要留痕。

修改后一致性自动校验

每次修改 architecture.json 后，必须立即执行以下校验，不得跳过。校验结果写入变更记录。

校验1：依赖完整性
  遍历所有模块的 依赖.使用接口 → 检查目标模块的 导出 中是否存在该接口
  → 不存在 = 悬空依赖，必须修复

校验2：路由-页面对应
  遍历入口路由中所有路径 → 检查是否有对应的页面拓扑节点
  → 缺失 = 路由指向空白页

校验3：接口-实现对应
  遍历接口契约中所有导出接口 → 检查实现清单中是否有对应的文件
  → 缺失 = 接口只有声明没有实现

校验4：数据表-迁移对应
  遍历数据拓扑中所有表 → 检查是否有迁移脚本路径
  → 缺失 = 表无法创建

校验5：需登录页面-认证依赖
  遍历入口路由中标记"需登录"的路径 → 检查对应页面是否依赖了认证模块
  → 缺失 = 页面缺少认证保护

校验6：测试覆盖异常
  遍历接口契约中每个接口的 可能异常 → 检查完整细节中测试用例是否覆盖了每个异常
  → 缺失 = 异常路径无测试覆盖

校验7：依赖图无环
  从模块拓扑的依赖图检测是否存在循环依赖
  → 存在 = 架构错误，必须重构

校验8：交互完整性
  遍历本次涉及的所有组件/接口/命令
  → 检查是否有交互完整性检查记录
  → 检查是否有未通过的检查项（不含"不适用"）
  → 有未通过项 = 设计不完整，必须补全

校验结果格式（写入变更记录的影响范围字段）：

"影响范围": "m3, m5 | 校验通过: 7/7" 或 "m3 | 校验未通过: 校验3(接口无实现), 校验6(异常无测试)"

禁止事项

以下任一信号出现，说明设计停留在 Demo 层面：

• 没有配置管理模块（硬编码URL）
• 没有错误处理模块（各自try-catch，返回格式不一致）
• 没有日志模块（靠print排查）
• 没有数据校验（假设输入总是合法）
• 没有数据库迁移（手动建表）
• 测试用例只有happy path
• 模块依赖图有循环
• 接口定义只有成功返回没有异常

精细化程度标准

唯一判断标准：一个不熟悉项目的开发者，拿到 architecture.json 后，能否独立写出完整的可运行代码？ 能→够了。不能→继续细化。

辅助文件

• references/principles-card.md — 速记卡：铁律+机制+命令+层级（日常参考）
• references/quickstart.md — 快速上手：3步开始使用
• references/schemas.md — 四层递进 JSON Schema + 四层读取策略 + 完整性检查清单
• references/splitting-guide.md — 拆块策略参考
• references/commands-cheatsheet.md — 命令速查
• assets/architecture-template.json — 空白架构模板