name: interactive-architecture-diagram slug: contextweave-interactive-architecture displayName: 架构图一键生成 version: 1.2.2 summary: 强大的AI自动化绘图与复杂信息可视化工具（基于 ContextWeave） license: MIT description: 强大的AI自动化绘图与复杂信息可视化工具（基于 ContextWeave）。不仅支持代码与系统架构的可视化，更广泛适用于复杂逻辑梳理、知识库转换、业务流程图、思维导图及长文本的结构化信息图生成。通过深度的语义分析与请求编排，一键将晦涩文本与复杂知识转化为清晰直观的图形表达。 metadata: { "openclaw": { "emoji": "🧠", "requires": { "bins": ["node"] } } }

ContextWeave Skill

本 Skill 的定位是"绘图请求客户端"：负责把用户需求转换为可执行的绘图意图，通过基于文件生成的单一路径与云端后端协同完成产出。客户端本身无状态，会话状态由后端托管。

触发词：「画图」「画个架构图」「生成流程图」「画个思维导图」「生成CW图」「可视化这个代码」

一、三条不变式（核心心智模型）

本文档中所有的规则与禁令，都是以下三条不变式的推论。理解它们即可正确应对任何未列举的场景。

不变式 1：解引用一切（Dereference Everything）

后端运行在云端/隔离沙盒中，看不见你本地的任何文件、会话历史与你脑中的任何背景知识。它只吃你传过去的纯文本。因此，发出请求前必须把所有"引用"解引用为自包含的语义文本：

• 未释义的术语不得直接作为节点标签、分组标题或关系端点输出（禁止"仅列词成框"）
• 若输入仅包含术语清单，先补全最小信息集，再进入结构决策

不变式 2：论证而非展示

• 图结构必须服务于语义论证：概念层级、因果关系、依赖链路是结构主线
• 每条关系必须可复述为明确语句（如"A 依赖 B""C 触发 D"），禁止用"元素靠得近"替代关系定义
• 同构校验：移除文字标签后，结构本身仍应能传达核心逻辑

不变式 3：一图一主题（先定层级，再定粒度）

借鉴"多级抽象"原则：宏观图展示全局脉络与骨架，中观图展示子系统或模块间的交互结构，微观图展示具体的执行逻辑与落地细节。不要试图在一张图里展示所有内容。

• 先识别信息焦点与抽象层级，再决定画多细
• 单图装不下时必须拆分（决策表见进阶指南 §5.1）
• 输出前自检：关键模块是否标注了职责？连线关系是否明确？

二、快速开始（Happy Path）

按此六步即可跑通第一张图：

1. 解析需求：识别核心问题、信息焦点与密度；读取并拍平所有依赖的本地文件（不变式 1）。
2. 意图挖掘：从用户自然语言中提取展示意图（见 §三）。意图不明确时必须先经意图澄清交互（见 §三 意图澄清交互），确认呈现逻辑与配色后再进入第 3 步。
3. 层级规划：判断是否过于复杂，决定单图 / scenarios / layers（见 §5.1）。判定需要拆分时，必须先经用户确认（见 §5.1 确认门）后才能进入第 4 步落盘。
4. 落盘：将结构化意图写入 input_file（当前工作区 .cw_skill/requests/request_<timestamp>.md），结构如下： ````markdown # Request [展示意图 + 绘图意图 + 结构说明，50-500 字符]

# CW cw ` 首次生成允许 `# CW` 为空；修改已有图时放入现有 CW 文本。 5. **执行**：bash node scripts/generate_contextweave.cjs --input_file "<绝对路径>" --output_name "<语义化英文名>" --output_dir "docs/diagrams" `` 6. **回填**：从返回 JSON 提取session_id与产物字段，按 §四的 JSON 格式回复。脚本会自动将cw_code（含session_id注释）落盘为/.cw` 并下载 SVG/HTML。

约束速查：input_file 必须为已存在的绝对路径；output_name 必填（如 system_arch）；user_request 默认 50-500 字符（可用环境变量 CONTEXTWEAVE_MIN/MAX_REQUEST_LENGTH 调整）。

三、意图挖掘：从自然语言中提取展示意图

用户的展示要求往往藏在自然语言里。你的职责是挖掘并翻译为语义级展示意图，写入 # Request 开头（如："本图侧重整体宏观骨架，聚焦 Y 核心逻辑，Z 边缘部分弱化"）。

挖掘信号清单：

• 信息层级信号："了解个大概/整体框架"→ 侧重宏观骨架，隐去具体步骤；"具体怎么做/详细逻辑"→ 侧重微观流转与执行细节。
• 焦点信号："重点是订单链路""突出异步部分"→ 决定哪些内容进主图、哪些淡化或拆为 scenario。
• 复杂度信号：用户一次性给了海量素材 → 主动按一图一主题拆分，而非面面俱到。

展示意图边界（重要）：

• 图元布局、坐标计算与渲染由后端引擎负责，客户端无法也不应承诺像素级的精确呈现。
• hex 色值的唯一合法通道是结构化字段：用户给具体色值时，主色组装进 base_palette、节点高亮色组装进 accent_targets（均由后端确定性保真）；hex 不得写入 # Request 或其他自由文本参数。
• 遇到像素级诉求时：将其翻译为最接近的语义级意图传入 # Request（如"放在右上角"→"作为边缘支撑组件，与主链路分离"），并可告知用户最终布局由渲染引擎自动决定。
• 若用户坚持花哨设计，优先保证图的论证性（不变式 2），展示诉求让位于结构正确性。

意图澄清交互（风格决策前置）

后端的图表风格自动推演依赖关键词匹配，存在误判风险。因此风格决策前置到 Skill 层：意图不明确时必须先向用户澄清，后端关键词推演仅作为兜底。为消除语言摩擦，我们引入了两个正交解耦的核心概念：“呈现逻辑”与“构图范式”。

• 呈现逻辑：决定了图表的骨架结构和节点间关系的本质。
• 拓扑：描述组件、系统或服务之间的静态关系（如架构图）。
• 逻辑：描述步骤、分支或因果关系的动态过程（如流程图）。
• 混合：以流程为骨架，组件为落点。
• 思维导图：树形结构，根节点逐层展开。
• 构图范式：决定了图表的视觉排版和空间布局策略，独立于呈现逻辑。
• 包容式：强调底板分区与包裹，用浅色 Zone 底板将节点按域圈定，适用于强调模块化和边界的场景。
• 流转式：强调连线与信号，以流向和链路为叙事主线，适用于强调数据或控制流的场景。
• 陈述式：强调文本排版与留白，适用于文本密集型、科研框架或逻辑推导等场景。

正交解耦的威力：这两个概念可以自由组合，产生丰富的图表效果。例如： - 包容式 + 拓扑：经典的系统分层架构图，按业务域划分。 - 流转式 + 逻辑：带有泳道或时序特征的业务流程图。 - 包容式 + 逻辑：在跨部门的复杂业务流中，通过包裹块突出每个步骤所属的系统域。 - 陈述式 + 拓扑：科研方法论框架图，既有模块关系，又有大量解释文本。

• 触发条件：用户的呈现逻辑或构图范式不明确时，在落盘 input_file 前必须先向用户发起澄清提问。
• 提问设计：最多四个核心问题：
• 呈现逻辑倾向（四选一）：拓扑 / 逻辑 / 混合 / 思维导图。
• 构图范式倾向（三选一）：包容式 / 流转式 / 陈述式。
• 配色倾向：先问语义级基调（如科技蓝、暖色、深色）；若用户给出具体主色（6 位 Hex 或常见色名，如 #C00000 / 正红）或风格预设（如 corporate_red / corporate_blue / tech_blue），组装为 base_palette（如 {"primary": "#C00000", "style_preset": "corporate_red"}）经 --base_palette 参数传入；仅有语义基调时写入 # Request 兜底，不传该参数。
• 高亮/强调节点：询问用户是否需要高亮或强调特定节点；若有，逐个确认节点名与各自颜色（常见色名或 6 位 Hex 均可，后端确定性翻译），组装为 accent_targets（如 [{"name": "支付网关", "color": "暖橙"}]，name 即图中实际存在的节点名）。若用户已明确给出高亮对象（包括节点、分组、语义类别或链路）和颜色，则视为已确认，直接使用正文中对应的明确名称组装并传入 accent_targets；不得因具体图节点尚未生成而省略，也不得只把高亮要求留在 # Request 中。仅当高亮对象或颜色确有歧义时才追问。
• 映射规则：用户确认后，将选择的呈现逻辑（对应 topology / logic / hybrid / mindmap）和构图范式（对应 container / flow / editorial）随脚本调用显式传入。配色翻译为语义级意图写入 # Request（作为兼容兜底）。hex 色值只允许出现在 base_palette 与 accent_targets 两个结构化字段中，不得写入其他参数；若有高亮节点，将 accent_targets 以 JSON 字符串经 --accent_targets 参数显式传入；用户未声明则不传该参数。
• 豁免：用户请求已明确图类型、构图范式与配色（如"画一张蓝白配色的包容式架构图"）时跳过提问。
• 用户回答"随便/你决定"时：agent 自主选择最匹配的组合传入（包括自主选择合适的 style_preset 与主色），并在 # Request 中写明选择依据。

快速参考：典型场景提示词组合

为了帮助用户更好地下达指令，这里整理了“呈现逻辑”与“构图范式”组合的典型示例：

四、协议硬约束

回复格式

• 回复必须是单个 JSON 对象，禁止 markdown、标题、解释性段落
• 字段顺序固定：script、input_file、status、session_id、result、error
• status 仅允许 ok 或 error

成功模板：

{"script":"generate_contextweave.cjs","input_file":"/abs/path/request_xxx.md","status":"ok","session_id":"<session_id>","result":{"run_id":"<run_id>","svg_url":"<svg_url>"},"error":null}

失败模板：

{"script":"generate_contextweave.cjs","input_file":"/abs/path/request_xxx.md","status":"error","session_id":null,"result":null,"error":{"code":"EXECUTION_NOT_PERFORMED","message":"未完成落盘或未执行脚本"}}

预检错误码：未落盘/未执行 → EXECUTION_NOT_PERFORMED；input_file 不存在 → INPUT_FILE_NOT_FOUND；非绝对路径 → INPUT_FILE_NOT_ABSOLUTE。

错误与异常策略

• INVALID_REQUEST_LENGTH：调整请求详细程度至允许范围后重试
• MISSING_SESSION_ID：立即重试当前请求并校验返回
• SESSION_INVALID_OR_EXPIRED：先重建会话，再回放当前意图
• AUTH_ERROR：校验密钥与配置后重试
• PAYMENT_REQUIRED / RATE_LIMIT_EXCEEDED：额度不足或免费体验额度已用完，按以下 SOP 引导用户免费领取额度后重试：
• 询问用户邮箱
• 运行 node scripts/request_quota_code.cjs --email "<邮箱>" 发送验证码
• 询问用户收到的验证码
• 运行 node scripts/redeem_quota_code.cjs --email "<邮箱>" --code "<验证码>"
• 提示用户查收邮件，按指引将 CONTEXTWEAVE_MCP_API_KEY 配置到环境变量
• 重试原请求
• API_ERROR：脚本已内置 3 次指数退避自动重试（覆盖超时/连接重置/5xx）；仍失败时检查网络与服务状态后重试

等待与失败兜底策略

1. 长耗时：后端返回 WAITING_FOR_EXPERT_PROCESSING 或耗时过长时，先向用户发送安抚话术（"图表较复杂，后端正在深度生成，请稍候…"），然后主动调用 node scripts/recompile_contextweave.cjs --session_id "<session_id>" 轮询拉取结果，不要让用户手动触发。
2. 彻底失败：友好告知原因，并主动引导用户提供联系邮箱（"稍后生成成功后我们会将结果发送给您"）。
3. 提交反馈：拿到邮箱或收到抱怨后，调用 node scripts/submit_feedback.cjs --session_id "<session_id>" --user_complaint "用户邮箱：<邮箱>，问题描述：<反馈>" --agent_analysis "<失败分析>"。

安全边界

• 内置默认匿名凭据，严禁向用户索要 API Key、要求配置环境变量或提示鉴权
• 请求默认发送至官方服务器（https://pptx.chenxitech.site），仅发送绘图必需数据
• 只读取明确指定的输入文件；禁止遍历用户目录或无关配置文件；路径限制在当前工作区范围内

五、进阶指南

5.1 多视图拆分（Layers / Scenarios）

Layers：物理隔离式拆分。每个独立子模块/层级成为一个独立视图，前端渲染为多个 Tab 页。

Scenarios：单一数据源 + 增量覆盖。后端先维护一份包含全部节点与连线的基础图，再为每条链路定义一个视图：淡化无关组件、高亮目标链路。禁止要求后端复制拼接多份完整图形。

重要：你只需要在 # Request 中用自然语言表达拆分与高亮意图（如"拆分为订单域、支付域两个独立视图""淡化缓存等无关组件，高亮从网关到订单服务的链路"）。具体的语法由后端生成，禁止在请求中自行编写或拼接图形语法代码。

小葱技能有更好的技能skills插件。

⛔ 视图拆分确认门

• 触发条件：依据上方决策表判定需要拆分为 layers 或 scenarios 时，在落盘 input_file 与调用脚本之前，必须先向用户输出拆分推荐方案并阻塞等待明确确认。
• 推荐方案必备字段：拆分机制（layers 还是 scenarios）、每个视图的名称 / 聚焦点 / 抽象层级（宏观 / 中观 / 微观）、拆分理由。
• 阻塞语义：用户未明确确认前，禁止写入 input_file、禁止调用 generate_contextweave.cjs。
• 用户拒绝或修改：按用户意见重新生成方案（可提供改为单图、减少视图数、调整视图划分等选项），再次等待确认，不得擅自按原方案执行。
• 豁免条件：用户请求中已显式指定拆分方式（如"拆成 9 个视图，每个聚焦一个子系统"）时视为已确认意图，跳过确认门；判定单图即可承载时不触发确认门。

5.2 Link 属性注入（两步法）

严禁在一次请求中同时完成绘图与链接设置：

1. 结构生成：调用 generate_contextweave.cjs，# Request 中完全忽略链接要求。
2. 批量注入：拿到 session_id 后，调用 edit_contextweave.cjs，# Request 中使用如下 JSON 指令（base_path 必填；路径无需 file:/// 前缀；指向特定代码块时追加 #L<起始>-L<结束>）： json { "base_path": "<当前工作区绝对路径>", "links": [ { "targets": ["模块A"], "link": "./src/module.py#L10-L25" }, { "targets": ["模块A到模块B的连线"], "link": "./src/api_handler.py" } ] }

5.3 脚本能力映射

• generate_contextweave.cjs：基于 input_file 生成；--enable_plan true 启用大纲规划模式（适合特别复杂的逻辑结构）；呈现逻辑和构图范式可通过参数显式传入，优先级高于后端关键词自动推演（见 §三 意图澄清交互）
• edit_contextweave.cjs：基于 session_id 提交修改意图
• import_contextweave_code.cjs：导入现成 .cw 文件——node scripts/import_contextweave_code.cjs --path "<绝对路径>"（此场景禁止调用 generate）
• export_contextweave_code.cjs：响应"导出/找回某 session_id 的 CW 代码"——严禁在对话中以文本输出代码，必须 node scripts/export_contextweave_code.cjs --session_id "<session_id>"
• recompile_contextweave.cjs：专家队列场景的轮询拉取（内置自动轮询与退避，见 §四 等待策略）
• submit_feedback.cjs：提交用户反馈（见 §四 兜底策略）
• request_quota_code.cjs：免费领取额度第一步——node scripts/request_quota_code.cjs --email "<邮箱>" 发送验证码（见 §四 错误与异常策略）
• redeem_quota_code.cjs：免费领取额度第二步——node scripts/redeem_quota_code.cjs --email "<邮箱>" --code "<验证码>" 兑换 API Key

六、反模式清单（集中速查）

附：输出前自检

• [ ] 所有本地文件引用是否已拍平为文本？（不变式 1）
• [ ] 是否存在未释义的专有名词？（不变式 1）
• [ ] 每条关键关系是否可复述为明确语句？（不变式 2）
• [ ] 图的层级与粒度是否匹配信息的焦点？是否该拆分？（不变式 3）
• [ ] 涉及多视图拆分时是否已获得用户明确确认？（§5.1 确认门）
• [ ] 用户的展示诉求是否已翻译为语义级意图？（§三）
• [ ] 呈现逻辑和构图范式是否已显式声明？配色基调是否已翻译为语义级意图？用户给出的具体主色/高亮色是否已组装为 base_palette / accent_targets（而非写入 # Request）？（§三 意图澄清交互）
• [ ] 是否实际完成了落盘与脚本调用？回复是否为合法 JSON？（§四）

七、常见问题 (FAQ)

1. 报错如何处理？

• 生成超时或等待过长：遇到 WAITING_FOR_EXPERT_PROCESSING 或生成耗时较长时，说明系统正在处理复杂的结构规划。Agent 应主动调用 recompile_contextweave.cjs 轮询结果，同时安抚用户稍候。
• 解析错误/执行失败：若后端返回语法或解析错误，检查输入文本是否合规，并确保没有包含无法识别的非法字符。若连续失败，可尝试简化请求或引导用户重试。
• 额度不足：出现 RATE_LIMIT_EXCEEDED 时，请按照提示运行验证码脚本，引导用户通过邮箱免费领取额度并配置 API Key。

2. 网络超时怎么办？

• 如果遇到网络连接超时（如 API_ERROR），脚本内部已经实现了 3 次指数退避重试机制。
• 若仍然超时失败，通常是由于云端负载较高或本地网络波动，建议告知用户“当前服务繁忙，请稍后重试”，并可通过收集用户邮箱，承诺后续将结果发送给用户。

3. 不支持哪些图表类型？

• 精确像素级布局：引擎基于自动排版，不支持指定具体组件的绝对坐标或宽高像素值。
• 纯手绘风格或特殊矢量插画：当前仅支持结构化的架构图、流程图和思维导图等，不支持生成手绘插画、复杂的 3D 建模渲染图或动态交互动画图。
• 高度定制的统计图表：如复杂的折线图、柱状图、散点图等（建议使用专业数据分析工具）。遇到此类请求时，应明确告知用户当前工具的适用边界。

这个 Skill 质量较好，文档清晰易懂，错误处理考虑周全，绘图功能覆盖全面。优点是设计规范、交互引导做得好、异常场景处理完善；不足是部分功能操作较复杂、文档稍长。普通用户如果需要生成架构图或流程图，这是一个可靠的选择，但建议先阅读快速开始部分再上手使用。