shaomang/mtnode-aio/dev-architect

开发节点架构师（mtnode-dev-architect）

把软件项目变成「开发节点」画布：每个功能块一个节点、概述写清作用、关系线表达模块关系、每块绑定一个开发会话。参考 archify 的思路，但采用剥洋葱式逐层下钻（一层层剥到叶子，见「细化纪律」），而不是一次性出静态架构图。搭建依靠 Agent 会话完成，不需要专门的扫描/搭建节点。

适用边界（先读）

本技能只在「MTNode 画布上构建 / 分析开发节点架构」时使用（模式 A 扫描建图 / 模式 B 先架构后搭建 / 在画布上细化建子节点）。不要在以下场景调用本技能：

• 功能块的「开发 / 细化」绑定会话：那是基于项目根目录真实代码的开发工作，由各自任务书（开发任务书 / 细化任务书）驱动，自带两段式概述、色卡、AGENTS.md 共识等全部规则，无需也不得再加载本技能——本技能描述的是"怎么在画布上搭架构图"，不是"怎么写某个模块的代码"。
• 会话任务是写代码、改 bug、补测试、写文档等常规开发内容时。
• 用户没有明确要求"把项目 / 模块变成画布架构图"时，即使对话里出现了「开发节点」这个词，也不要主动加载本技能。

判断口径：画布构建场景（建图 / 建子节点 / 上色 / 连线）→ 可用；绑定开发 / 细化会话 → 禁用。

开发节点是什么

• 形态：kind: "super" + dev: true（可嵌套，parentSuperId 指向父块）
• note = 概述（必填），固定分两段书写（详见「概述书写规范」）：
• 第一段 · 非技术功能说明（≤60 字）：大白话讲清「这个模块是干什么的、为谁服务、产出什么」
• 第二段 · 工程实现梗概（≤120 字）：工程四要素——位置（对应目录）、技术栈、关键依赖、目录映射；顶层块必须附目录映射（如 对应目录：src/renderer）
• devPath = 项目根目录（绝对路径，设在顶层块，子块自动继承）
• devStatus = pending（待开发）/ wip（进行中）/ done（已完成）
• devKind = 元素类型（层级细化链，画布上用不同外框颜色区分）：
• module（模块/功能块，默认，绿色）→ 细化为文件，或继续细化为子模块（module 可多层嵌套，见「细化纪律」）
• file（文件，蓝色，对应一个源码文件）→ 细化为类图元素
• class（类，橙色）/ interface（接口，紫色）/ enum（枚举，粉色）——参考 UML 类图基本元素（成员与职责写进 note）
• devColor = 该块自定义外框 + 呼吸灯颜色（#rrggbb，空 = 元素类型默认色）；建块 / 细化时按「功能色卡」主动传色（模块传功能色、文件类元素留空）；用户也可在头部颜色小按钮的 HSV 色板里手改，Agent 可用 update 补丁设置（对已有块改色前先问用户，勿擅自统一改色）
• devModel（+devProvider）= 该功能块的 Agent 模型：本块的「建议」只读调研与「开发 / 细化」绑定会话都走它；未自行选择的子功能块就近继承上层，子块自己选过则以子块为准。用户说「整个项目 / 这个模块统一用某模型」→ 只在顶层块或该块设一次即可（devProvider 可省略，应用按模型反查路由）；传空串 = 恢复跟随默认。会话视图里仍可临时改模型，不影响节点上的生效模型
• devPreset（+devEffort）= 该功能块的 Agent 预设 与 思考强度，与 devModel 并列的第三、第四项 Agent 设定（画布上就是 🧠 弹层里的「预设 / 模型 / 思考强度」三格）：
• devPreset = AGENT_PRESETS 的 id —— minimal（极简，默认档）/ standard（标准）/ lean（思维精简；旧名 sketch 会自动归一为 lean）/ code（PTC 模式）/ cordis（创造）。传空串 = 跟随默认（应用兜底 minimal）；未知 id 会被拒绝并回报，不要自创档位名。
• devEffort = 思考强度，只认档位词汇表内值 low / medium / high / xhigh / max（与会话思考档同一张表 AGENT_EFFORT_ORDER；UI 露出 low=轻 / high=标准 / xhigh=强 / max=最强 四档，medium 是合法词汇但默认路由会把它夹到 low，不在 UI 露出），传空串 = 跟随默认（兜底 high）。这一档只由设置决定：预设不会改写它。
• 两项与 `devModel` 一样就近向上继承，但各自独立生效：模型 / 预设 / 思考强度分别沿父链找第一个已选值，互不牵连——用户说「整个项目统一用 X 模型 + 思维精简，但某个模块单独开最强思考」→ 顶层块设一次 devModel + devPreset，再到那个子块设 devEffort。别为了改一项把三项都覆写（先 mtnode_canvas_get 看清现状，只 patch 用户点名的那一格）。
• 生效范围 = 本块的「建议」只读调研 + 「开发 / 细化」绑定会话 + 开发「问询」会话（都按就近继承的解析结果下达）。
• 界面写的就是实际跑的：思考强度只由所选档位决定——历史上 lean（思维精简）会替用户把「标准」压到 low，界面上因此多出「生效档」一套双口径，该压档机制与双口径文案已一并取消：选 low 就按 low 跑、high 就按 high 跑、xhigh 就按 xhigh 跑、max 就按 max 跑。向用户解释时直接说他所选的那一档，不要提「实际生效的更低」。
• 用户说「这块 / 整个项目都用 XX 模式（预设）或开最强思考」时，用 update 补丁直接写 `devPreset` / `devEffort` 即可（等同用户在弹层里点），无需新建会话或改提示词。
• devFiles = 该功能块的核心文件列表（字符串数组，最多 10 条，每项一条相对项目根 `devPath` 的路径，如 renderer/app-devnode.js；绝对路径也可，落在项目根内的会被折成相对）。它是节点折叠卡「文件 N」按钮展开的那份清单，点任意一行即在资源管理器中定位该文件——建块时就顺手填，并在每次开发 / 细化 / 建议收尾时用 update 补丁回写真实核心文件（传 [] 清空）。填法：只列本模块真正负责的文件（一般 3~10 条，优先入口与关键实现，不要把整目录或无关文件塞进来）；file / class / interface / enum 块可留空（标题本身就是路径，应用会自动兜底收集）。最外层（项目）开发块一律不传——它代表整个项目，不列举核心文件，传了会被拒绝并回报 warning。
• 「建议」按钮（所有开发节点）→ 先弹确认对话框（列出元素类型 / 状态 / Agent 模型 · 预设 · 思考强度 / 项目根 / 下层元素 / 历史会话 / 上次建议，可选填「本轮关注点」）；确认后 AI 只读调研项目真实代码与该模块的开发进度（不改文件、不改画布、不新建会话），返回恰好 4 条下一步方案（各带优先级与真实证据）；用户在同一个对话框里多选、可写补充说明，然后点该对话框里的 「开发」 = 用「所选方案 + 补充」新建绑定会话并开工。方案缓存在节点字段 devSuggest（随工作流保存），下次可直接「查看上次建议」而不重跑模型；「换一批」则重新评估
• 「开发」按钮（所有开发节点）→ 先弹对话框：上方展示该模块的标题、元素类型、开发状态、Agent 模型（含继承来源）、项目根、下层元素与最近一次要求（生效的预设与思考强度同样下达，只是这一栏不另起两行），下方让用户填写「本次希望开发 / 迭代的内容」；确认后才新建一个绑定该模块的会话（标题=开发 · 模块名，工作区=项目根，首条消息=该块开发任务书）并在其中运行。节点状态自动转为 wip。需求一次填写完整：对话框确认后任务书一次性写入，不要在会话里再分两次输入补充需求（会造成上下文割裂、重复开工）——有补充请在本次需求文本里写全
• 「细化」按钮（模块 / 文件）→ 也先弹对话框：确认是否要把该模块继续展开；用户可选填细化范围。确认后同样新建会话运行细化任务，Agent 必须先报多层梗概树、经用户确认才建子节点，且默认按深度细化一次拆到无法再细（见「细化纪律」）；若判断无需或无法继续细化（例如类/接口/枚举已是最细粒度、项目里没有对应下层内容），要直接告知用户原因，不建任何节点
• 运行中指示：当开发节点自身、块内任意后代节点、或绑定的开发 / 细化会话在运行时，节点头部出现「运行中」徽标（旋转圆环），边框按元素类型颜色做呼吸灯动画——这是纯 UI 反馈，不改节点数据、不参与执行；会话完成 / 节点停止后自动消失。同一判定也把运行中的开发节点列进左下角运行队列（与处理节点同款行：模块绿标题 + 来源 tooltip，「■」可逐条停止——递归停掉块内运行后代与绑定会话），会话开始 / 结束即时进出
• 「建议」的评估只在对话框内完成（只读、不新建会话、不改画布）；每次「开发 / 细化」都是一个新会话（上下文干净）；节点记录其名下的历史会话，可用节点上的「会话 N」按钮或右键菜单回到最近一次
• 概述供后续 Agent 快速定位：写概述时假设读者是「第一次见这个项目的 Agent」

兼容旧版应用：若 create 传 dev/devKind 字段报 schema 错误，降级为普通 super + note（标题前加「〔开发〕」），其余流程不变，并告知用户升级应用后可获得「建议 / 开发 / 细化」按钮。

功能色卡（按功能分类给功能块上色）

上色纪律（每次创建 / 细化开发节点都要执行，不要留一堆同色块让用户自己改）：

• 模块用功能色：devKind:"module" 的功能块，先按下表 8 类判据给它定性，create / update 时传 `devColor` = 对应 hex；
• 文件类用类型默认色：file / class / interface / enum 一律不传 `devColor`（留空），保持元素类型配色，层级一眼可辨；
• 未分类留空：8 类判据一个都不命中 → 不传 `devColor`（= 模块默认绿），禁止凭感觉挑一个颜色硬凑；
• 判据取自该块的标题 + 概述：标题命中权重 2、概述命中权重 1，取最高分类；同分按本表声明顺序取先者（与应用侧推断规则一致）；
• 优先级：用户手选 > 功能色 > 元素类型默认色。应用在两个创建入口也会按同一张表自动上色，但调用方显式传的 `devColor` 优先——所以技能侧必须自己按色卡传值，保证 Agent 建的图与用户手建的图完全一致；
• 唯一真源：本表与 renderer/app-devnode.js 的 DEV_FUNC_COLORS 逐项对应；换色先改那份常量再同步本文，不要在别处自创色值或改动 hex。

留空时生效的元素类型默认色（DEV_KIND_COLOR，无需传参）：module #6fe3a5 绿 · file #6db4ff 蓝 · class #ffb454 橙 · interface #c792ea 紫 · enum #ff8fa3 粉。

关系线（表达元素之间的关系）

• 创建：connect 项加 rel: true，可选 relLabel（线上文字，如「调用」「依赖」「实现」「包含」）与 relArrow（forward/backward/both/none，默认 forward；关联类关系常用 both）
• 关系线是普通直线（不再走直角折线）、不占端子、不参与数据流与执行，仅用于表达关系（UML 风格，无需严格遵守）
• 用户点选某个元素时，与它相关的关系线会亮起（青色 + 光晕、箭头同步变色），与它无关的关系线自动淡出
• 引擎会把同一层的整个关系线集合一起规划：同一条边上的多条线按对端位置扇形分散到不同锚点、同走廊的线分车道错开、优先走不穿过任何方块的干净车道，线上文字自动避让——不要为了避让而手写坐标，也不要重复连同一条关系线
• 箭头方向 relArrow 会如实渲染（forward 终点箭头 / backward 起点箭头 / both 双向 / none 无箭头）
• 用途：模块间调用/依赖、类对接口的实现、文件间引用等；同层元素或直属父子之间可连
• 数据流管线仍用普通连线；开发节点架构图中优先用关系线

执行节点（启动器 · 放在开发节点菜单里，可落进功能块内部）

• kind: "execute"：绑定一个可执行 / 可被系统打开的文件（execPath 绝对路径），可设 execIcon / execColor 便于定位；没有数据端子，用户双击节点或连点两下播放键即通过系统默认方式启动
• 创建入口：右键画布 → 开发节点（项目架构 · 功能块） → 执行；用户也可在功能块上右键「在内部新建执行节点（启动器）」。Agent 侧用 mtnode_canvas_edit create kind:"execute"，要放进某个功能块时设 parentSuperId = 该块 id
• 用法建议：模式 A / B 收尾时，为项目放上常用启动器（build.cmd、run-dev.bat、打开产物目录的脚本），作为该模块的子节点与架构并排；不要把它接进数据流，也不要用它替代节点上的「开发」按钮

模式 A：扫描已有项目 → 生成架构画布

1. 明文要求项目文件夹（必填）：先要求用户给出项目根目录（绝对路径），确认后写入顶层开发节点的 devPath；同时确认画布是新建还是追加。用户未提供项目文件夹则不建图、不臆测默认目录——路径不明就停下来向用户索要，绝不替用户猜目录、绝不以当前工作区或常见路径充当项目根。
2. 限额扫描（严禁全量读源码）：

• 目录树（2~3 层，跳过 node_modules/.git/dist/产物）
• 依赖清单：package.json / requirements.txt / go.mod / Cargo.toml 等
• 入口与配置：README、主入口文件、构建配置（各文件只读前 ~150 行）
• 用 glob/grep 定向取证，不臆测

1. 模块地图草案：按目录/职责归纳功能块；每个候选块先写两段式梗概（【功能】非技术说明 + 【实现】工程梗概，同「概述书写规范」）。
2. 不确定必问（ask_user_question）：

• 是否纳入：插件、示例、脚本、生成产物、测试、文档
• 粒度：某目录是独立块还是并入父块
• 技术选型歧义（多框架共存等）

1. 建画布（一次 mtnode_canvas_edit）：

• 顶层开发节点：dev:true, devKind:"module", devPath, note=项目总述——同样分两段：第一段非技术功能说明（这个项目整体是干什么的）+ 第二段工程实现梗概（技术栈 + 目录映射）
• 一层子块：parentSuperId=顶层，各自 note 按两段式概述书写（同「概述书写规范」）
• 每个块都按「功能色卡」传 `devColor`：模块块取 8 类判据命中的功能色 hex，判不出类别就留空；file / class / interface / enum 一律留空走元素类型默认色（一次 create 里就把色带上，不要建完再补）
• 每个模块块同时传 `devFiles`：把扫描取证到的本模块核心文件（≤10 条、相对 devPath）一并写进节点——这是用户在功能块上点「文件 N」看到的那份清单，建块那一轮就填，别留给以后补；顶层（项目）开发块不传 `devFiles`（会被拒绝并回报）
• 模块关系用关系线（rel:true + relLabel）；跨层仍可用 superConnect（普通连线）
• 顶部放 input_text「项目总览」：所有块标题 + 两段式梗概清单（Agent 导航索引，直接复用第 3 步的梗概）
• 最外层 `agent.md` 入口节点：在顶层功能块下建一个 file 类型入口节点（标题 agent.md，代表项目根的 Agent 共识入口文件）；用户点该节点「打开」即可在应用内 Markdown 阅读器里查看 / 编辑 / 保存（应用打开时若项目根无 agent.md 会自动回退到既有 AGENTS.md）
• createMarks 分区 + layout
• 同步产出 `AGENTS.md`（见「AGENTS.md 共识文件」）：在项目根写 / 更新共识文件，目录约定与「不要修改」清单以扫描证据为准，不确定的保护路径先问用户

1. 报告：模块清单、覆盖的目录、询问过的取舍；并说明本图建到了哪一层（通常只到一层子块）——哪些块已按「叶子判定标准」确认无下层、哪些块仍待下钻。提示用户「展开某个块、点『细化』继续下钻；细化默认按深度口径一次把该块拆到无法再细（一般文件级），先给多层梗概树、确认后才逐层建节点」，不要说成"每次只能细化一层"。

模式 B：新项目先架构 → 确认后搭建

1. 用户给出新项目文件夹（空目录）与目标；协助搭开发节点（可先由用户手绘式提需求，助手建块）。
2. 架构审阅迭代：检查覆盖完整性（入口/核心逻辑/数据/界面/构建）、关系是否闭环、概述是否齐全；模糊处 ask_user_question，逐轮迭代画布；每轮新建的块都按「功能色卡」传 `devColor`（模块用功能色、文件类元素与未分类块留空）。
3. 确认门禁（强制）：只有用户明确说「确认」（按当前架构搭建）之后才允许写项目代码。确认前复述：块清单 + 搭建顺序 + 技术栈；同场确认 `AGENTS.md` 共识文件（目录约定 + 「不要修改」清单，见「AGENTS.md 共识文件」）与最外层 `agent.md` 入口节点（file 类型，指向共识文件，应用内 Markdown 阅读器可查看 / 编辑 / 保存），确认后动工前把共识文件写到项目根。
4. 按依赖顺序实现：被依赖者优先（如 数据层 → 核心逻辑 → 界面 → 入口）。每块：

• 优先引导用户点击该块「建议」按钮（让 AI 依据真实代码评估下一步该做什么，勾选后点同一对话框的「开发」开工）；用户已有明确需求时则点击该块「开发」按钮：在弹出的对话框里填写本次需求，确认后由新建的绑定会话施工（会话首条消息即该块任务书）
• 或由助手直接实现（工作区=项目根）
• 完成后 update：devStatus: "done"；note 按「概述书写规范」回写——在第二段末尾追加一行「关键文件 / 对外接口」（如 关键文件：src/auth/login.tsx；对外接口：POST /api/auth/login），第一段非技术功能说明保持不变；同时用 devFiles 补丁回写本块真实核心文件（≤10 条 · 相对项目根），让用户在功能块上点「文件 N」就能直接定位过去

1. 整体自检：全部 done 后运行构建/启动/测试（视项目类型），回报结果；失败块改回 wip 并修复。

局部画布（scope）：只读 / 只改某颗壳内部

开发节点架构图动辄上百块（深度细化尤其如此），整图灌进上下文既慢又贵。只要这一段工作只涉及某一颗壳（补某个模块的子块、改它的概述 / 状态 / 核心文件、给它内部连线），就用局部口径：

• 读：mtnode_canvas_get({ scope: "<壳标题或 id>", detail: "standard" }) —— 默认只回那颗壳 + 直接子节点；要看整棵子树加 scopeDepth:"all"；确需整图才 scope:"global"。返回里的 scopeInfo（恒保留）说明本次 mode / origin / depth / host，钻进子块时还带 above 祖先链。
• 改：mtnode_canvas_edit({ scope: "<壳标题或 id>", ... }) —— 界外节点 / 绘制 / 连线 / 成组 / 自动排版一律跳过并在 warnings 逐条说明；壳内新建节点缺 parentSuperId 时默认落进这颗壳，不会飘在根画布上。
• 用户此刻停在某颗壳里时，快照 scopeInfo 会点名它，照抄标题当 scope 即可；要跨壳作业（建兄弟块、连跨壳关系线）就别传 scope（或 scope:"global"）。

细化纪律（剥洋葱 = 逐层下钻到底，不是单层）

核心口径：细化是「深度」概念，不是「单层」概念。「剥洋葱」指的是像洋葱一样一层层剥到芯——一次细化要把这个块一直拆到无法再细为止（一般会拆到文件级），画布上最终留下多层嵌套的开发节点。绝不能理解成"本轮只建一层，剩下以后再说"，那只会得到一张一层到底的假架构图。