ContextWeave Skill

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

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

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

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

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

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

| 悬空引用 | 解引用动作 | |---|---| | 文件路径（"请参考 /path/to/x"） | 必须先自行使用本地工具读取文件，将其核心逻辑拍平（Flatten）成纯文本写入 # Request | | 专有名词/缩写（未释义的术语） | 补全最小信息集：角色（对象类型与责任边界）、层级（所属模块/抽象层）、动作（关键行为）、上下游关系 | | 旧图上下文（"基于上一张图修改"） | 把现有 CW 文本放入 input_file 的 # CW 段随请求提交；session_id 从上一轮返回 JSON 中提取复用，不要求用户重复输入 |

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

不变式 2：论证而非展示

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

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

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

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

二、快速开始（Happy Path）

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

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

# CW
```cw
```
```
首次生成允许 # CW 为空；修改已有图时放入现有 CW 文本。

执行：

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

回填：从返回 JSON 提取 session_id 与产物字段，按 §四的 JSON 格式回复。脚本会自动将 cw_code（含 session_id 注释）落盘为 <output_dir>/<output_name>.cw 并下载 SVG/HTML。

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

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

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

挖掘信号清单：

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

展示意图边界（重要）：

| 支持：语义级展示意图（可转发给后端） | 不支持：像素级精确诉求（必须降级翻译） | |---|---| | 配色基调（"基础设施用蓝色系"） | 指定具体 hex 色值并要求严格一致 | | 重点突出（"高亮这条链路""这个模块要醒目"） | 指定精确坐标 / 像素位置 | | 聚类分组（"订单域的模块放在一起"） | 指定字号、线宽、间距的具体数值 | | 分层结构（"按接入层/应用层/数据层上下排"） | 指定复杂的自定义布局算法 |

图元布局、坐标计算与渲染由后端引擎负责，客户端无法也不应承诺像素级的精确呈现。
遇到像素级诉求时：将其翻译为最接近的语义级意图传入 # Request（如"放在右上角"→"作为边缘支撑组件，与主链路分离"），并可告知用户最终布局由渲染引擎自动决定。
若用户坚持花哨设计，优先保证图的论证性（不变式 2），展示诉求让位于结构正确性。

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

后端的图表风格自动推演依赖关键词匹配，存在误判风险（如思维导图被"层级"关键词劫持为拓扑图、空间包裹语义被误判为流程）。因此风格决策前置到 Skill 层：意图不明确时必须先向用户澄清，后端关键词推演仅作为兜底。

触发条件：用户的呈现逻辑（图类型）、构图范式或配色基调不明确时，在落盘 input_file 前必须先向用户发起澄清提问。
提问设计：最多三个核心问题：
1. 呈现逻辑倾向（四选一）：组件拓扑（系统/模块/服务之间的关系）/ 流程逻辑（步骤/分支/因果）/ 混合（流程为骨架、组件为落点）/ 思维导图树形（根节点逐层展开的细节蓝图）。
2. 构图范式倾向（Morphology，三选一）：包容式 container（强调底板分区与包裹，用浅色 Zone 底板将节点按域圈定，适用于系统架构、中台能力等组件化视图）/ 流转式 flow（强调连线与信号，以流向和链路为叙事主线，适用于流程、数据流、调用链视图）/ 陈述式 editorial（强调文本排版与留白，适用于科研框架、逻辑推导等文本密集型视图）。
3. 配色基调倾向：如科技蓝、暖色、深色等语义级描述。
映射规则：用户确认后，拓扑→--diagram_style topology、流程→logic、混合→hybrid、思维导图→mindmap，随 generate_contextweave.cjs 调用显式传入；构图范式→--morphology <value>（取值 container / flow / editorial，对应包容式 / 流转式 / 陈述式），同样随脚本调用显式传入；配色翻译为语义级意图写入 # Request（遵守上方展示意图边界：不承诺 hex 色值严格一致）。
豁免：用户请求已明确图类型、构图范式与配色（如"画一张蓝白配色的分层架构图"）时跳过提问，直接映射显式参数。
用户回答"随便/你决定"时：agent 自主选择最匹配的显式风格传入，并在 # 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 引导用户免费领取额度后重试：
1. 询问用户邮箱
2. 运行 node scripts/request_quota_code.cjs --email "<邮箱>" 发送验证码
3. 询问用户收到的验证码
4. 运行 node scripts/redeem_quota_code.cjs --email "<邮箱>" --code "<验证码>"
5. 提示用户查收邮件，按指引将 CONTEXTWEAVE_MCP_API_KEY 配置到环境变量
6. 重试原请求
API_ERROR：脚本已内置 3 次指数退避自动重试（覆盖超时/连接重置/5xx）；仍失败时检查网络与服务状态后重试

等待与失败兜底策略

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

安全边界

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

五、进阶指南

5.1 多视图拆分（Layers / Scenarios）

| 用户意图 | 应选机制 | |---|---| | 架构庞大，需拆为多个独立视图/模块/层级 | layers | | 同一架构上高亮不同链路（如 Query 链路 vs Callback 链路） | scenarios |

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

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

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

⛔ 视图拆分确认门

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

5.2 Link 属性注入（两步法）

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

结构生成：调用 generate_contextweave.cjs，# Request 中完全忽略链接要求。

批量注入：拿到 session_id 后，调用 edit_contextweave.cjs，# Request 中使用如下 JSON 指令（base_path 必填；路径无需 file:/// 前缀；指向特定代码块时追加 #L<起始>-L<结束>）：

{
  "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 启用大纲规划模式（适合特别复杂的逻辑结构）；--diagram_style 显式指定呈现逻辑（取值：topology / logic / hybrid / mindmap），优先级高于后端关键词自动推演（见 §三意图澄清交互）
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 | # Request 中出现"请参考文件 /path/to/x" | 不变式 1 | 自行读文件，拍平为纯文本写入 # Request | | 2 | 术语未释义直接作为节点/分组标签 | 不变式 1 | 补全角色、层级、动作、上下游后再出图 | | 3 | 修改已有图时不带 # CW 段 | 不变式 1 | 将现有 CW 文本放入 # CW 随请求提交 | | 4 | 用"元素靠得近"表达关系 | 不变式 2 | 显式连线 + 方向，可复述为"A 依赖 B" | | 5 | 一张图塞入所有细节 | 不变式 3 | 按受众定层级，复杂时拆 layers/scenarios | | 6 | 承诺像素级布局/精确样式 | §三边界 | 翻译为语义级展示意图，渲染交给后端 | | 7 | 只输出语义分析文本而不调用脚本 | §二 | 任何绘图意图必须落到脚本调用 | | 8 | 绘图与 Link 注入合并为一次请求 | §5.2 | 先生成结构，再批量注入链接 | | 9 | 长耗时让用户干等或直接抛错 | §四 | 安抚 + 主动 recompile 轮询 | | 10 | 失败后不给用户留联系方式入口 | §四 | 引导留邮箱 + submit_feedback 上报 | | 11 | 未经用户确认擅自拆分多视图 | §5.1 确认门 | 先输出拆分推荐方案并阻塞等待用户确认 | | 12 | 意图不明时直接落盘，把风格决策丢给后端关键词猜测 | §三意图澄清交互 | 先提问澄清呈现逻辑与配色，显式传 --diagram_style |

附：输出前自检

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