Agent Skill

架构图一键生成

使用 ContextWeave 生成或修改架构图、流程图、思维导图和复杂信息图。适用于需要从代码、文件或自然语言中提取结构与关系并实际产出 CW、SVG、HTML、可编辑 PPTX 或原生 VSDX 的请求;未特别说明时,PPTX 与 Visio 使用原生形状和连接器导出。不适用于统计图表、手绘插画或像素级排版。

设计多媒体·ContextWeave·来自 skill_hub·skillhub.cn ↗
skillhub install @user_bddf3fe6/contextweave-interactive-architecture
288 Stars·54.7万 综合热度·8,584 字文档·源站更新 2026-11-22

README 文档

8,584 字

ContextWeave Skill

HTML 与 SVG 分别保存;未通过完整验收的可用预览也保留 HTML,页面中的未验收标记继续有效。

本 Skill 是 ContextWeave 的绘图请求客户端:把用户需求整理成自包含的绘图意图,通过本地脚本与云端后端协同生成结果。客户端本身无状态,会话状态由后端托管。

常见触发语包括:“画图”“画个架构图”“生成流程图”“画个思维导图”“生成 CW 图”“可视化这段代码”。

结构化备注

需要旁注、补充说明或待确认事项时,读取 结构化备注,使用 annotations 或 --annotations_file;不要把备注排成普通业务容器。真实步骤、判断条件和关系仍保留在主图。只修改备注时使用备注专用编辑调用,保留主图布局与原验收状态。

结构化生成优先路由

先判断能否完整保留用户的内容和关系:顺序跨角色交接用泳道,分区嵌套用层级卡片,各列共享行与跨行用矩阵。适配时自动选用结构化路径,无需用户知道模板名称,也无需为此等待普通骨架选择;不适配时使用普通生成并显式传 --diagram_type general。

读取 结构化调用与编辑,再按当前结构只读取一份协议:泳道 JSON、层级卡片或共享轨道矩阵。新建泳道与共享轨道矩阵默认 JSON,层级卡片可用薄 HTML,已有 JSON 直接复用;每次只写一种输入。

这条路径以 --authoring_file 取代普通流程的请求文件和 CW,直接表达内容、分组、顺序、真实关系、必要的布局约束与跨度;不写 D2、宽高、坐标或 CSS。规范模型由脚本保存,后续编辑保留其 ID。 卡片内部列数优先交给自动 Grid;若无法可靠判断分组、主次或阅读顺序,先给出简短结构草案让用户确认,再提交。用户已明确或已确认的结构直接沿用,不要求逐一确认行列数字。仅普通路径遵循下文的 # Request / # CW 和骨架选择流程。生成与导出仍使用当前变体的既有入口和授权范围。

一、三条不变式(核心心智模型)

新手可以先记住三个通俗结论:把背景说完整、把关系说清楚、一张图只回答一个核心问题。下面的正式规则必须完整遵守,它们也是处理未列举场景时的推理依据。

不变式 1:解引用一切(Dereference Everything)

新手理解: 不要只告诉后端“去参考某个东西”,要先把它真正需要的内容带进本次请求。

后端运行在云端/隔离沙盒中,看不见你本地的任何文件、会话历史与你脑中的任何背景知识。它只接收本次请求中显式提供的纯文本。因此,发出请求前必须把所有“引用”解引用为自包含的语义文本:

悬空引用解引用动作
文件路径(“请参考 /path/to/x”)必须先自行使用本地工具读取文件,将其核心逻辑拍平(Flatten)成纯文本写入 # Request
专有名词/缩写(未释义的术语)补全最小信息集:角色(对象类型与责任边界)、层级(所属模块/抽象层)、动作(关键行为)、上下游关系
旧图上下文(“基于上一张图修改”)结构化图提交保存的规范模型;普通图把现有 CW 文本放入 inputfile 的 # CW 段随请求提交;sessionid 从上一轮返回 JSON 中提取复用,不要求用户重复输入。具体操作见 高级操作
  • 未释义的术语不得直接作为节点标签、分组标题或关系端点输出(禁止“仅列词成框”)。
  • 若输入仅包含术语清单,先补全最小信息集,再进入结构决策。

不变式 2:论证而非展示

新手理解: 图不是把名词摆出来,而是要用结构证明它们之间的逻辑。

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

不变式 3:一图一主题(先定层级,再定粒度)

新手理解: 先决定这张图回答什么,再决定需要画多细。

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

  • 先识别信息焦点与抽象层级,再决定画多细。
  • 单图装不下时必须进入多视图判断,按“四、多视图触发与确认门”及其参考文档处理。
  • 输出前自检:关键模块是否标注了职责?连线关系是否明确?

二、普通单图:六步完成

1. 解析材料

识别核心问题、信息焦点与需要读取的文件。只读取用户明确指定且与绘图有关的内容,并按不变式 1 补全上下文。

2. 写出一句话重点

例如:

展示订单从网关进入订单服务、完成库存校验并发起支付的主链路;日志与监控只作为支撑组件弱化展示。

3. 确定呈现方式、骨架与配色

使用“三、核心参数:先理解再映射”中的通俗判断表,确定呈现逻辑和构图范式,再按 §3.2 评估骨架的阅读收益。需求明确时直接使用用户选择;值得推荐的骨架按下述选择流程处理。用户授权自主选择时,在授权范围内决定并继续。

4. 写入请求文件

在当前工作区创建 .cwskill/requests/request<timestamp>.md,并使用绝对路径:

````markdown

Request

[展示重点、绘图意图、必要背景、明确关系与已确认的展示要求,50-5000 字符]

CW

````

首次生成允许 # CW 为空。修改已有图时,将当前 CW 全文放进该代码块。

5. 执行脚本

本任务首次联网前,按 外部数据传输与授权 简要说明接收方、用途及涉及的数据类别并取得一次明确同意。同一任务内未新增敏感数据类别时不重复询问。

node scripts/generate_contextweave.cjs --input_file "<绝对路径>" --output_name "<语义化英文名>" --output_dir "docs/diagrams" --use_default_palette
  • input_file 必须存在且为绝对路径。
  • outputname 必填,例如 orderpayment_flow。
  • userrequest 默认长度为 50-5000 字符,可由 CONTEXTWEAVEMINREQUESTLENGTH / CONTEXTWEAVEMAXREQUEST_LENGTH 调整。
  • 已确定的呈现逻辑、构图范式和精确配色必须按第三节显式传参。
  • 脚本会保存 <output_name>.cw,并下载 SVG/HTML 产物。
  • 用户要求 Visio/VSDX 时,取得 sessionid 后读取 高级操作,调用 exportsession_asset.cjs --format vsdx;不要用 PPTX 或嵌入 SVG 冒充原生 Visio。

6. 面向用户交付

脚本的 JSON 是机器回执,Agent 读取后用简短自然语言向用户交付。默认提供真实可打开的 HTML/所需文件链接和必要的读图说明;只有用户明确要求机器格式时才展示 JSON。不要回显整份回执、内部脚本参数、空字段或空链接。

  • 已验收:说明已生成,提供图入口并简述核心内容。
  • 可查看草稿:先提供真实草稿入口,明确“未通过完整验收”及具体剩余问题;保留可用的导出和编辑能力,不改称正式图。
  • 没有可用产物:简述实际失败原因与下一步;不伪造链接、session_id 或成功状态。
  • 多图:按视图名称列出实际入口和各自状态;共用交互页时提供一个入口并说明可切换的视图。
  • 返还次数、导出成功等事实只依据真实回执。完整回执和恢复 ID 保留在工具结果/本地记录,不要求用户处理内部字段。

示例(链接必须替换为本次真实产物,不照抄占位链接):

已生成架构图。打开交互图。主链路是申请、校验和业务放行。

两张讨论稿已保存:打开交互图,可切换组件图与流程图。关系证据和局部布局尚未通过完整验收,请暂作为讨论稿使用。

本次未生成可查看的图,原因是输入中的关系端点不存在。需要修正该端点后重试。

三、核心参数:先理解再映射

这些术语和配色参数属于核心能力。先按自然语言判断,再使用表中的真实脚本参数。

3.1 呈现逻辑:图主要讲什么

呈现逻辑通过 --diagram_style 传入。

用户想看什么通俗解释参数
组件、系统或服务之间的关系看“谁与谁相连”--diagram_style topology
步骤、分支、因果或时序看“事情怎样发生”--diagram_style logic
流程与组件归属同时重要看“步骤发生在哪个系统”--diagram_style hybrid
从中心主题逐层展开看“知识怎样分支”--diagram_style mindmap

3.2 构图范式:画面怎样组织

构图范式通过 --morphology 传入。

用户希望怎样呈现通俗解释参数
用区域和底板强调边界强调模块归属--morphology container
用连线和方向强调信号强调数据或控制流--morphology flow
用排版和留白承载文字强调说明与论述--morphology editorial

两组参数彼此独立。例如:topology + container 适合分层架构,logic + flow 适合业务流程,hybrid + container 适合跨系统审批,topology + editorial 适合科研框架。

构图骨架:先评估收益,再按选择或布局授权采用

骨架决定单张图内顶层区域怎样排列,与多视图拆分分别判断。“一个核心问题、一条因果链”或已选 hybrid + container 都不能单独排除骨架;也不要为了套骨架改变原有关系语义。

确定呈现逻辑和构图范式后,按原文结构评估:

内容依据与阅读收益可推荐的骨架
原文有明确职责层级,按层排列能突出层次和依赖分层(layered)
主链之外有两类可独立阅读的说明或证据,分栏能保持主链清楚中央主链配固定左右侧轨(three_lane)
原文有明确命名阶段,分行排列能改善阶段阅读或比较,且保留原有顺序与分支阶段网格(stage_grid)

收益明确时,应主动推荐一个最匹配的方案,用自然语言说明区域安排、来自材料的依据和阅读收益,并保留普通布局选项;不要要求用户先知道参数名。准备推荐或落实骨架时即可读取 构图骨架规划,无需等用户点名。

  • 用户已明确选择骨架(自然语言也算),或接受了具体推荐:直接采用,不重复确认。
  • 用户已明确授权 Agent 决定布局,包括在讨论布局时回答“你决定”:自主选择并简述依据。仅授权配色不等于授权骨架。
  • 有推荐收益但尚无选择或布局授权:提出一次具体方案供用户选择;等待回复期间可整理材料和请求草稿,不能生成 outline_file 或提交依赖该选择的生成请求。沉默不视为接受。
  • 收益不明显、用户拒绝推荐或明确要求普通布局:沿用普通生成,不反复劝选。

采用宏观方案后,按 构图规划 的版本能力选择 OutlineIntent。支持联合生成 v2 时,保留完整原文、用户硬要求、Agent 软建议和开放维度,交给后端联合细分整图;v1 只做既有语义兼容。将 JSON 保存到工作区,并附加:

--outline_file "<工作区内的绝对路径>"

普通容器分组、普通单轴流程无需默认附加骨架。节点多、文本长或内容复杂,以及阶段数量或系统边界本身,都不足以推荐或启用骨架。OutlineIntent 声明宏观意图和有原文证据的要求,不枚举最终节点图。v2 未展开关系允许后端按原文识别;v1 空账本禁止跨区关系,两者不能混用。未通过候选按版本和剩余预算修订,不能以新会话规避同一工作流的预算。

3.3 最少澄清问题

只询问会显著改变结果的未决事项;§3.2 中有明确阅读收益的骨架选择也属于此类。以下是按需澄清的维度,不要逐项问卷式询问:

  1. 想看组件关系、步骤流转、两者混合,还是思维导图?
  2. 更强调区域分组、流向,还是文字说明?若骨架有明确收益,结合具体内容推荐区域安排。
  3. 希望使用什么整体配色或主色?
  4. 是否需要高亮特定节点、分组、语义类别或链路?分别使用什么颜色?

跳过用户已明确或已授权自主决定的事项。图类型、构图范式和配色已明确时,仍需完成骨架适配评估;没有值得推荐的骨架时直接继续。“你决定”按当前讨论事项理解,并在 # Request 中简述实际选择依据。

3.4 整体配色:base_palette

除单主色外,后端声明支持时可选择 red-gold-compact-v1 / blue-compact-v1:用于联合生成的宏观区域,也用于 shared-tracks 矩阵的根、列、格及嵌套节点。通过 stylerole 选择主题内角色,子项继承最近角色;列数、业务 ID 和分区由内容决定,主题不固定七列。只传 stylepreset,不混用 primary,同会话续改继承保存的选择。矩阵先检查 authoring 下的主题/角色能力,详见矩阵协议;联合生成见构图规划。中车式结构是共享轨道的普通示例,不选择案例专用预设。

  • 整体颜色、语义色调和复合主题在提交前整理为 base_palette;正文可保留意图说明,执行选择不能只留在正文。通用双色/背景通过 version:1 的 primary、secondary、background 传递,先核对入口能力;详见结构化配色交接。
  • 新建普通图未指定整体配色时,显式传 --usedefaultpalette;已有图沿用保存色板,不重新选默认。只有局部高亮时,默认整体选择可与 accent_targets 同用。
  • 用户给出 6 位 Hex、受支持色名(红/蓝/绿/橙/紫/金及对应英文)或风格预设(corporatered / corporateblue / techblue)时,组装为 basepalette,通过 --base_palette 传入。
  • Hex 色值只能出现在 basepalette 或 accenttargets 中,不能写入 # Request 或其他自由文本参数。

示例:

--base_palette '{"primary":"#C00000","style_preset":"corporate_red"}'

3.5 局部高亮:accent_targets

用户指定高亮对象与颜色时,组装为数组并通过 --accent_targets 传入:

--accent_targets '[{"name":"支付网关","color":"暖橙"},{"name":"订单服务","color":"#2F6BFF"}]'
  • name 使用图中实际应出现的节点、分组或语义对象名称。
  • 用户已明确对象和颜色时直接组装,不能因为节点尚未生成而省略,也不能只把要求留在 # Request 中。
  • 只有对象或颜色确有歧义时才追问;用户没有高亮要求时不传该参数。

3.6 展示意图边界

可以直接表达必须翻译或拒绝承诺
模块分组、层级、主次、语义色调精确坐标、字号、线宽、透明度、间距
通过结构化参数传递的主色与高亮色在自由文本中散落 Hex、RGBA 或像素值

把“放在右上角”翻译成“作为边缘支撑组件,与主链路分离”。图元布局和坐标由后端决定;结构正确性优先于装饰效果。

四、多视图触发与确认门

出现下列信号时停止普通单图流程,并读取 多视图与 Scenarios:

  • 用户同时要求全局、模块和执行细节;
  • 多个子系统需要独立视图;
  • 同一套组件需要分别突出多条链路或状态;
  • 为了装进单图必须混合多个抽象层级或隐藏关键关系。

如果判断需要拆分,在创建 input_file 和调用脚本前,必须先向用户给出拆分机制、视图名称、各视图焦点、抽象层级和拆分理由,并阻塞等待明确确认。用户原请求已明确指定拆分方式与视图内容时可视为已确认。

核心入口只负责识别触发条件和执行确认门。layers 与 scenarios 的判断、案例、组合边界及单一数据源规则按需从参考文档读取。

五、按需读取的进阶文档

触发条件必读文档
需要拆模块、拆层级或在同一架构上切换链路多视图与 Scenarios
内容适合骨架且准备推荐,或需落实用户选择/布局授权构图骨架规划
修改已有图、导入/导出 CW、添加文件链接高级操作
脚本超时、报错、等待专家处理、额度不足或提交反馈异常恢复
任何准备向 ContextWeave 服务发送数据的操作外部数据传输与授权

只读取当前任务相关的文档,不要默认加载全部参考资料。

六、协议与安全硬约束

  • 只向官方服务 https://pptx.chenxitech.site 发送完成任务所需的数据。首次联网前简要说明本任务涉及的数据类别与用途并取得明确同意;未授权时停止在脚本调用前。
  • 一次授权覆盖当前任务内已披露数据类别的生成、修改、导出和轮询,不重复询问。后续新增完整 CW、绝对 base_path、邮箱、验证码或反馈内容时,只补充说明新增类别并再确认一次。
  • 用户直接提供数据不等于外发授权。说明时只列类别,不回显完整验证码、CW 全文或绝对路径;获得授权后必须真正落盘并执行脚本。
  • 只读取用户明确指定的输入文件;路径限制在当前工作区,禁止遍历用户目录或无关配置。
  • 正常生成使用内置默认匿名凭据;禁止主动索要 API Key、要求用户配置环境变量或提示鉴权。
  • 遇到脚本错误时读取 异常恢复,不要凭错误名称猜测恢复步骤。

七、完整反模式清单

#反模式违反正确做法
1# Request 中出现“请参考文件 /path/to/x”不变式 1自行读取文件,拍平为纯文本写入 # Request
2术语未释义直接作为节点或分组标签不变式 1补全角色、层级、动作、上下游后再出图
3编辑未携带现有业务结构不变式 1结构化图提交规范模型;普通图携带完整 CW,并复用 session_id
4用“元素靠得近”表达关系不变式 2使用明确、带方向且可复述的关系
5一张图塞入所有细节不变式 3按受众确定层级,复杂时进入多视图判断
6承诺像素级布局或精确样式§3.6翻译为语义级意图,布局交给后端
7只输出分析或命令而不调用脚本§二、§六落盘并实际执行对应脚本
8绘图与 Link 注入合并为一次请求高级操作先生成结构,再批量注入链接
9长耗时让用户干等或直接抛错异常恢复说明状态并主动调用 recompile 轮询
10失败后不给用户留下反馈入口异常恢复说明原因,按需收集联系方式并提交反馈
11未经确认擅自拆分多视图§四先给拆分方案并等待用户确认
12意图不明确时把风格决策完全交给后端猜测§三只补问会改变结果的选项,并显式传参
13把用户提供数据或提出绘图请求视为外发授权§六首次联网前简要说明本任务的数据类别与用途,并取得一次明确同意

八、输出前自检

  • [ ] 本地文件和旧图引用已展开为后端可理解的内容(结构化路径使用规范模型)。
  • [ ] 专有名词已补充角色、层级、动作和上下游。
  • [ ] 每条关键关系都能复述成明确语句。
  • [ ] 图只回答一个核心问题;需要拆分时已读取参考文档并获得确认。
  • [ ] 普通路径的 --diagram_style 与 --morphology 已按用户意图显式设置;结构化路径只提交 authoring。
  • [ ] 普通路径已评估骨架的阅读收益;采用时有用户选择或布局授权,相关意图已写入请求并通过 --outline_file 传递。
  • [ ] 配色要求已对应到实际整体参数或高亮对象;普通新建明确选择色板或默认,复合主题不丢第二色/背景,已有图继承。
  • [ ] 已简要说明本任务的外发数据类别与用途并获得授权;新增敏感类别时已补充确认。
  • [ ] 已真正落盘并执行脚本,已解析机器回执,并向用户提供可读说明、真实产物入口和准确的质量状态。

九、常见问题(FAQ)

1. 报错如何处理?

  • Skill 版本缺失或不兼容:出现 OUTDATED_SKILL 时停止直接重试,读取 异常恢复 的“Skill 版本升级”流程,由 Agent 自动更新到服务端要求版本并以新进程重试一次;不要把更新步骤转交给用户。
  • 生成超时或等待过长:遇到 WAITINGFOREXPERTPROCESSING 或生成耗时较长时,说明系统正在处理复杂结构。主动调用 recompilecontextweave.cjs 轮询,同时简短告知用户仍在处理。
  • 解析错误或执行失败:检查输入文本、绝对路径和请求长度。连续失败时可简化请求或引导重试。
  • 额度不足:出现 PAYMENTREQUIRED 或 RATELIMIT_EXCEEDED 时,按 异常恢复 的验证码流程处理,不要提前索要凭据。

2. 网络超时怎么办?

  • 服务端 5xx 与超时、连接重置等瞬时网络错误会由脚本执行最多 3 次指数退避重试;配置、认证等确定性错误不会重试。
  • 出现 PROXYERROR 时检查 HTTPSPROXY / HTTPPROXY;目标应直连时,由部署方将目标域名加入 NOPROXY。
  • 瞬时错误重试后仍失败通常表示云端负载或本地网络异常。需要收集联系方式与提交反馈时,使用 异常恢复 的流程。

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

  • 精确像素级布局:不支持指定组件的绝对坐标、宽高、字号或间距。
  • 纯手绘或特殊矢量插画:不支持手绘插画、复杂 3D 建模或动态动画。
  • 高度定制的统计图表:复杂折线图、柱状图、散点图应使用专业数据分析工具。

遇到超出能力边界的请求时,应直接说明限制,并在可能时建议更合适的工具类型。

4. CW 和 D2 是什么关系?

CW 是 D2 语法的精选子集,面向 AI 稳定生成做了收窄,配合服务端诊断与自动修复生成图表。

同分类其他技能

查看全部 ›