参考资料与维护
献丑 Skill 的主入口应保持简洁，复杂细节放在 references/ 中。Agent 遇到命令参数、接口契约、路径规则或错误处理不确定时，应优先读取这些参考文件。
Skill 目录结构
skills/
├── README.md
├── SKILL.md
└── references/
├── cli-command-guide.md
├── api-generation-guide.md
├── markdown-image-guide.md
├── api-contract-guide.md
└── common-pitfalls.md
参考文件
| 文档 | 何时阅读 |
|---|---|
references/cli-command-guide.md | 不确定安装、认证、命令参数或输出格式 |
references/api-generation-guide.md | 不确定模型查询、生图、生视频、轮询和 settle 流程 |
references/markdown-image-guide.md | 不确定 Markdown/MDX 插图、路径、封面和回写规则 |
references/api-contract-guide.md | 不确定 /api/cli 接口契约或错误格式 |
references/common-pitfalls.md | 遇到 Access Key、projectId、路径、重复插图或内部接口误用问题 |
接口契约摘要
所有远程请求必须统一访问 /api/cli/*。后端可以复用已有服务，但 CLI 不直接访问 /canvas、/run、/toolbar-image、/toolbar-video。
认证使用：
Authorization: Bearer <ACCESS_KEY>
Access Key 由用户在 Web 头像菜单中的 Access Key 弹窗创建并复制。
维护建议
- 新增 CLI 能力时，先扩展
/api/cli契约，再更新 Skill 文档。 - 新增模型能力时，保持“动态查询模型”的规则，不在文档中写死模型 ID。
- 新增 Markdown 写回能力时，明确 dry-run、
--write、资源目录和公开 URL 前缀的行为。 SKILL.md保持短而明确，详细示例放进references/。- 每次发布 CLI 后，用
xianchou --help和关键命令帮助检查文档是否仍然准确。