# SourceCanvas AI Skills 使用指南 / User Guide

Skill 包版本：1.0.0。更新：2026-10-07。安装方式参考文档见末尾链接。

## 这两份 Skill 做什么

| 下载包 | 用途 | 前提 |
| --- | --- | --- |
| `sourcecanvas-diagrams.zip` | 用 AI 创建可编辑图表及 SVG 图标：流程图、时序图、ER 图、甘特图、思维导图、架构依赖图、UML 等 | 支持本地 Agent Skills 的 AI 应用；不依赖 MCP 也能生成源码 |
| `sourcecanvas-live-preview.zip` | 调用 SourceCanvas MCP 弹出本机预览，并在编程、排查或规划过程中持续更新同一个图表 | macOS、SourceCanvas、支持本地 stdio MCP 的 AI 应用、有效的自动化权益 |

官网入口为 [Skills 下载与使用](https://sourcecanvas.ioncreate.com/skills.html)。该地址须在本站更新部署后才提供本批下载文件。两个 ZIP 都包含一个与 Skill 同名的顶层文件夹，里面有 `SKILL.md`、参考文档、示例及许可证。仅需其中一个流程时，可以只安装一个包。

这些 Skill 是给 AI 的操作说明，不是 App 插件、模型或后台进程。它们不安装软件、不更改 AI 应用的信任设置，也不解锁 Pro。Skill 内容采用英文以便跨 AI 应用复用，AI 应按你的语言生成说明和图表标签。

## 安装到 AI 应用

1. 下载 ZIP 并解压。先阅读 `SKILL.md`；本批包不含可执行脚本。
2. 将整个 `sourcecanvas-diagrams` 或 `sourcecanvas-live-preview` 文件夹放入下表的一个位置。不要只移动 `SKILL.md`，也不要多套一层 ZIP 文件名文件夹。
3. 如果已有同名 Skill，先备份旧文件夹，再替换；不要覆盖自己的修改。只选择个人或项目一种范围，避免重复加载。
4. 新开一次 AI 会话，并检查 Skill 列表。必要时重启 AI 应用。

| AI 应用 | 个人目录 | 当前项目目录 | 显式调用 |
| --- | --- | --- | --- |
| Codex | `~/.agents/skills/` | `.agents/skills/` | `$sourcecanvas-diagrams`、`$sourcecanvas-live-preview` |
| Claude Code | `~/.claude/skills/` | `.claude/skills/` | `/sourcecanvas-diagrams`、`/sourcecanvas-live-preview` |

例如 Codex 个人目录中的文件应为 `~/.agents/skills/sourcecanvas-diagrams/SKILL.md`。`~` 代表你的用户主目录。Claude Code 与 Claude Desktop 是不同应用，不能把上面的 Claude Code 路径当作 Claude Desktop 的安装步骤。

其他 AI 应用若支持 Agent Skills，可按其当前文档导入完整目录。仅支持 MCP 不代表支持 Skill。暂不支持 Skill 的应用，可以手工将 `SKILL.md` 的工作流程作为提示词，并按需附上参考文件；这不等于自动安装或自动发现。

## 连接本机 SourceCanvas MCP

1. 在 Mac 安装并打开 SourceCanvas。打开“设置 → MCP 与 AI 应用”，启用 AI 应用连接。
2. 在所需 AI 应用所在行点击连接，或按应用内的连接配置说明设置本地 stdio MCP。macOS 要求时，在“系统设置 → 通用 → 登录项与扩展”批准 SourceCanvas。只配置你打算使用的应用。
3. 点击“检查连接”。如果失败，先解决服务、系统批准或路径问题，再开始绘图。将 SourceCanvas 移到新位置后，需要更新原来的 MCP 配置路径。
4. 在 AI 应用内重新连接 MCP 或重新打开会话，确认发现 SourceCanvas 的 `list_formats`、`render_diagram` 等工具。配置写入成功不代表连接已经成功。
5. 只有读取/导出本地文件时，才在“文件与隐私”中授权所需文件夹；AI 应用的工作区访问范围也需要覆盖它。不要授权整块磁盘来解决单个目录问题。

标准安装的辅助程序是 `/Applications/SourceCanvas.app/Contents/Helpers/sourcecanvas-mcp`，启动参数为 `serve --stdio`。不要把辅助程序移出 App，也不要手工反复启动常驻服务。使用其他安装位置时，以应用内复制的配置为准。

本机 MCP 不是互联网地址，不能把官网 URL 填入只支持远程 HTTP MCP 的云端连接器。iOS、iPadOS、visionOS 可以打开生成的 `.svg`、`.mmd`、`.dot` 或 `.puml` 源码，但不运行这套 macOS MCP 服务，也不自动接收 Mac 的实时窗口。

自动化功能依当前版本的 SourceCanvas Pro 权益判断。出现需要购买或重新验证提示时，到 App 的权益中心处理；已符合原付费用户权益条件的用户应恢复/重新验证，不要为了 Skill 重复购买。Skill 免费下载不代表 App 的所有功能免费。

## 用法一：AI 生成图表

在 Codex 中输入（Claude Code 将 `$` 换成 `/`）：

```text
$sourcecanvas-diagrams 用中文绘制订单支付流程图，包含支付失败、重试和取消。
输出 Mermaid 源码，保留可编辑文件。未说明的业务规则先列为假设。
```

然后需要本机预览时：

```text
$sourcecanvas-live-preview 用 SC 打开刚才的流程图预览。
后续修改继续更新同一个窗口，不要每次新建窗口。
```

其他可直接使用的请求：

- “根据这些数据库模型画 ER 图，推测的关联单独说明。”
- “把以下真实任务日期转为甘特图，不更改日期；用官方 Mermaid 模式预览。”
- “检查当前项目依赖，用 Graphviz 绘制实际服务关系，不要把建议架构混进去。”
- “用 PlantUML 画登录时序图，包含认证失败路径，不引用外部文件。”
- “制作一个 24×24 的 SVG 完成状态图标，透明背景，小尺寸仍清晰。”

检查预览中的文字、箭头、日期和分组后，可以继续要求修改。需要导出时说明格式和目标文件夹，例如“将当前图导出为 PDF 到我已授权的项目 outputs 文件夹，若同名文件存在请先询问”。未连接 MCP 时，AI 仍能给出源码；将源码保存为对应扩展名后用 SourceCanvas 打开即可。

## 用法二：长时间工作的动态状态图

```text
$sourcecanvas-live-preview 排查这个项目的登录错误。
先在 SC 展示排查流程，后续在确认原因、完成修改、获得测试结果时更新同一个图。
区分待处理、进行中、已完成和受阻，只标记真实完成的步骤。
首次弹出窗口，后续后台刷新；任务结束时保留最终状态。
```

AI 会保持 `preview_id` 不变、逐次增加 `revision`。第一次使用 `activate` 请求弹出，后续通常用 `background` 更新，减少抢焦点和重复窗口。只有重要状态变化才更新，不按每一次工具调用刷新。需要重新显示已关闭的窗口时，明确说“重新显示这个预览”。

这不是独立的后台监控：AI 会话停止后，不会自行继续查询项目或刷新图表。想持续监控，需要另外明确配置支持该能力的 AI 调度机制。SourceCanvas 不会因为安装 Skill 就接管你的编程任务。

## 成功标准与排查

| 现象 | 操作 |
| --- | --- |
| 找不到 Skill | 检查文件夹层级和所用 AI 应用的安装目录，重新开会话 |
| 找不到 SourceCanvas 工具 | 检查是否使用本机 stdio MCP；重新连接 AI 应用 |
| 一直超时 | 在 SourceCanvas 中“检查连接”，检查系统批准及配置路径；不要重复开启许多服务进程 |
| AI 说成功但没有窗口 | 区分“已渲染”和“已请求显示”；让 AI 检查 presentation 结果，并重新请求显示，而不是重新生成无关预览 |
| 甘特图布局异常 | 核对日期、依赖和支持版本，尝试 `render_mode: official`；不要修改真实日期来迎合截图 |
| 目录无权限 | 仅授权目标目录，并与 AI 工作区范围对齐 |
| PlantUML 引用被拦截 | 使用单文件内联定义，不关闭安全限制 |
| 预览被你手工编辑过 | 保留草稿；出现冲突时明确选择保留哪个版本 |

首次验收：应发现工具、返回无错误的渲染结果、实际看到图表；第二次更改应更新同一窗口。下载包中的 `preview-calls.json` 是接口示例，不是自动执行脚本；其中“Tests passed”只能在真实测试通过后使用。

本地渲染不需要上传源码给绘图服务器，但 AI 应用自身可能调用云模型。不要在图表中包含密钥、令牌或无需展示的隐私信息。

## English Quick Start

The two independent packages are **SourceCanvas Diagrams** (editable SVG icons, Mermaid, Graphviz and PlantUML source) and **SourceCanvas Live Preview** (local macOS MCP preview and milestone updates). Skill instructions and examples are reusable under the included MIT license; the app and Pro access are separate.

1. Download and inspect a ZIP. Extract its complete named folder, including `SKILL.md`, references and examples.
2. For Codex, put it in `~/.agents/skills/` (personal) or `.agents/skills/` (project). For Claude Code, use `~/.claude/skills/` or `.claude/skills/`. Back up an existing same-name folder before replacing it. Do not install duplicate copies at both scopes.
3. Start a new session. In Codex invoke `$sourcecanvas-diagrams`; in Claude Code invoke `/sourcecanvas-diagrams`. Use the analogous live-preview name for MCP rendering. These Claude Code instructions are not Claude Desktop instructions.
4. On a Mac, open SourceCanvas Settings, enable AI app connection under MCP & AI Apps, connect your chosen local host, approve macOS prompts and check the connection. Reconnect the host and confirm SourceCanvas tools are available. Authorize only the folders needed for file input/export.
5. Ask: "Use $sourcecanvas-diagrams to draw the checkout process, including payment failure and retry." Then: "Use $sourcecanvas-live-preview to show it in SC and update the same preview when I revise it."
6. For an active coding task: "Show the investigation, implementation and test milestones in SC. Update only when evidence changes; keep one window, with background updates after the first display." SourceCanvas is not an unattended agent scheduler.

The authoring Skill works without MCP and can return source to open on any supported Apple platform. Live preview needs macOS, a local stdio-capable AI host, the configured SourceCanvas helper and valid automation access. Skills do not unlock paid features or install a remote MCP service. Cloud-only chat clients cannot reach the local Mac helper simply by adding a website URL.

Use raw source for MCP; keep one `preview_id`, increase `revision`, use `activate` first and `background` for later updates. Verify diagnostics and presentation output. Rendering an image is not proof that a visible window appeared. Preserve local drafts and stop for conflicts. Do not export/overwrite files without the user's requested destination and approval. On a timeout, check the connection before a single retry; never spawn repeated helper processes.

The bundled examples include flowchart, Gantt, Graphviz, PlantUML and SVG. If an installed renderer rejects a feature, use its reported capabilities rather than assuming parity with another website. Local rendering does not change your AI host's privacy policy.

## 安装依据 / Installation References

- [Codex Skill scope and discovery](https://learn.chatgpt.com/docs/customization/overview#skills)
- [Codex Skills](https://developers.openai.com/codex/skills)
- [Claude Code Skills](https://code.claude.com/docs/en/skills)
- [SourceCanvas 支持](https://sourcecanvas.ioncreate.com/support.html)

## 项目维护与发布

源文件位于 `docs/skills/`，本文是可下载指南的唯一来源。`npm --prefix web test` 会重建网站和下载包并运行配对校验。交付目录为 `docs/skills/downloads/`，网站副本位于 `web/downloads/`，包含两份 ZIP、本文副本、清单和 `SHA256SUMS.txt`。下载包不包含个人配置、认证信息、App 二进制或第三方渲染器。Web 开发交接见同目录的 `WEB_HANDOFF.md`。

发布网站时部署生成的 `web/` 静态内容，保留现有站点托管方式。若只发布 Skills，需要包含六语言 `skills.html`、`downloads/`、`skills.css`、入口页面、共享样式和 sitemap；先核对入口页面中的其他未发布更改。不要把 IAP 价格、商店发布或 App 版本更新当作此下载任务的一部分。

生产验收：六种语言的下载页可访问；ZIP 返回正常状态、可解压且 SHA-256 与清单一致；首页和支持页的 Skills 链接可打开；窄屏与阿拉伯语 RTL 不横向溢出；下载不会要求登录或安装额外软件。