Imported from qhyw99/contextweave (skills/interactive-architecture-diagram/SKILL.md). Install upstream with npx skills add qhyw99/contextweave --skill interactive-architecture-diagram. Copyright stays with the author (MIT).

ContextWeave Skill

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

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

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

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

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

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

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

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

不变式 2：论证而非展示

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

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

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

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

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

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

二、普通单图：六步完成

1. 解析材料

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

2. 写出一句话重点

例如：

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

3. 确定呈现方式与配色

使用“三、核心参数：先理解再映射”中的通俗判断表。需求明确时直接使用用户选择；确有歧义时才提问。用户说“随便”或“你决定”时，自主选择并继续。

4. 写入请求文件

在当前工作区创建 .cw_skill/requests/request_<timestamp>.md，并使用绝对路径：

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

# CW
```cw
```

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

5. 执行脚本

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

node scripts/generate_contextweave.cjs --input_file "<绝对路径>" --output_name "<语义化英文名>" --output_dir "docs/diagrams"

• input_file 必须存在且为绝对路径。
• output_name 必填，例如 order_payment_flow。
• user_request 默认长度为 50-5000 字符，可由 CONTEXTWEAVE_MIN_REQUEST_LENGTH / CONTEXTWEAVE_MAX_REQUEST_LENGTH 调整。
• 已确定的呈现逻辑、构图范式和精确配色必须按第三节显式传参。
• 脚本会保存 <output_name>.cw，并下载 SVG/HTML 产物。
• 用户要求 Visio/VSDX 时，取得 session_id 后读取 高级操作，调用 export_session_asset.cjs --format vsdx；不要用 PPTX 或嵌入 SVG 冒充原生 Visio。

6. 按固定格式回复

最终回复必须是单个 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":"未完成落盘或未执行脚本"}}

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

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

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

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

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

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

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

构图骨架：只在用户明确选择时附加薄 OutlineIntent

仅当用户明确选择 layered、three_lane、stage_grid，或明确要求中央主链配固定左右侧轨等空间骨架时，读取 构图骨架规划，生成一个短小的 OutlineIntent JSON 文件，并附加：

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

普通容器分组、普通单轴流程，以及仅因节点多、文本长或内容复杂的请求都不生成、不传 --outline_file，沿用普通生成。OutlineIntent 只声明顶层空间骨架和有原文证据的必要跨区关系，不描述最终节点图，也不暴露后端插件。

3.3 最少澄清问题

只有缺失信息会显著改变结果时才询问，最多覆盖四项：

1. 想看组件关系、步骤流转、两者混合，还是思维导图？
2. 更强调区域分组、流向，还是文字说明？
3. 希望使用什么整体配色或主色？
4. 是否需要高亮特定节点、分组、语义类别或链路？分别使用什么颜色？

用户已经明确图类型、构图范式和配色时跳过提问。用户回答“你决定”时，自主选择最匹配的组合，并在 # Request 中简述依据。

3.4 整体配色：base_palette

• “科技蓝”“暖色”“深色”等语义色调写入 # Request。
• 用户给出 6 位 Hex、受支持色名（红/蓝/绿/橙/紫/金及对应英文）或风格预设（corporate_red / corporate_blue / tech_blue）时，组装为 base_palette，通过 --base_palette 传入。
• Hex 色值只能出现在 base_palette 或 accent_targets 中，不能写入 # 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 展示意图边界

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

四、多视图触发与确认门

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

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

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

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

五、按需读取的进阶文档

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

六、协议与安全硬约束

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

七、完整反模式清单

八、输出前自检

• 本地文件和旧图引用已展开为后端可理解的内容。
• 专有名词已补充角色、层级、动作和上下游。
• 每条关键关系都能复述成明确语句。
• 图只回答一个核心问题；需要拆分时已读取参考文档并获得确认。
• --diagram_style 与 --morphology 已按用户意图显式设置。
• 精确主色和高亮色只通过 base_palette / accent_targets 传递。
• 已简要说明本任务的外发数据类别与用途并获得授权；新增敏感类别时已补充确认。
• 已真正落盘并执行脚本，最终回复是合法的单个 JSON 对象。

九、常见问题（FAQ）

1. 报错如何处理？

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

2. 网络超时怎么办？

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

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

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

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

4. CW 和 D2 是什么关系？

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