内容
# Comic Sol
Comic Sol 是一款纯粹的可安装的 Codex 技能，它可以将短提示、粘贴的故事或 `.txt`/`.md` 文件转换为原创的漫画/动画风格的漫画。一次自然语言调用即可驱动规划、角色一致性、图像生成、视觉 QA、选择性修复、确定性字母和构图，以及 PDF 导出。它不是一个 Web 应用程序或托管产品。不需要构建服务。
## 安装
要求是 Python 3.11 和 `Pillow==12.3.0`。图像创建还需要一个通过活动代理会话公开的图像生成能力；Comic Sol 永远不会嵌入提供者凭证。
直接将公共存储库克隆到 Codex 技能目录中，然后安装一个固定的依赖项：
```bash
git clone https://github.com/wenn-id/comic-sol.git \
"${CODEX_HOME:-$HOME/.codex}/skills/comic-sol"
cd "${CODEX_HOME:-$HOME/.codex}/skills/comic-sol"
python3.11 -m pip install -r requirements.txt
```
主机无关规则是：将此存储库作为一个 `comic-sol` 文件夹安装在 Codex 技能目录下，由 Codex 安装配置。保持 `SKILL.md`、`scripts/`、`references/`、`templates/` 和 `assets/` 在一起。
Windows PowerShell:
```powershell
git clone https://github.com/wenn-id/comic-sol.git `
"$env:USERPROFILE\.codex\skills\comic-sol"
Set-Location "$env:USERPROFILE\.codex\skills\comic-sol"
py -3.11 -m pip install -r requirements.txt
```
支持的环境包括 Linux、macOS、Windows 和 WSL，Python 3.11 和 Pillow 12.3.0。确定性测试套件不需要图像提供者。
## 原生 Hermes MCP 服务器（可选）
Comic Sol 包括一个可选的 `stdio` MCP 服务器，作为 Hermes Agent、Claude Desktop、Cursor 或任何 MCP 客户端的标准工具公开确定性管道。
要运行 MCP 适配器，请在 Pillow 一起安装 SDK：
```bash
python3.11 -m venv ~/.venvs/comic-sol-mcp
~/.venvs/comic-sol-mcp/bin/pip install -r requirements.txt -r requirements-mcp.txt
```
从存储库根目录，使用存储库相对脚本路径和绝对选定输出根目录启动开发服务器：
```bash
OUTPUT_ROOT="$(pwd)/comic-sol-output"
python3.11 scripts/mcp_server.py --root "$OUTPUT_ROOT"
```
对于 MCP 客户端配置，请将 `python3.11`、`scripts/mcp_server.py` 和选定的输出根目录解析为绝对路径，从当前检出中获取。不要从另一台机器复制路径。便携式安装的 CLI 尚不可用。禁用采样并将服务器锁定到该输出根目录。服务器公开了完整的确定性生命周期，包含 17 个 `comic_*` 工具。
## 调用
打开 Codex 并安装技能后，例如说：
> 制作一个关于快递员向地下城市运送阳光的 2 页漫画。
这是完整的用户调用。Comic Sol 检测提示、粘贴故事、源文件或恢复模式；应用记录的默认值；并仅在材料缺失时提问。如果代理会话无法返回本地光栅图像，它会报告明确的错误。请参阅 [`references/capability-detection.md`](references/capability-detection.md) 以获取确切的能力检查和保留项目恢复过程。平台特定的图像提供者设置记录在 [`references/image-provider-setup.md`](references/image-provider-setup.md) 中。
用于确定性诊断：
```bash
python3.11 scripts/comic_sol.py doctor --output-root /tmp/comic-sol-doctor
```
## 检查结果
每次运行都在生成的项目目录下保留可编辑的语义和视觉中间件。重要的输出是：
```text
project.json 项目清单和当前状态
plan/ 故事计划、角色圣经和故事板
prompts/ 可编辑的参考和面板提示
references/ 规范的角色和场景图像
panels/raw/ 生成的面板 PNG
panels/clean/ 接受的干净面板 PNG
panels/*/lettered.png 确定性加字面板 PNG
pages/page-001.png 有序的 1600×2400 页面 PNG
exports/<project-id>.pdf 有序的漫画 PDF
qa/panels/*.json 七项检查面板 QA 记录
qa/report.md 人类可读的 QA 报告
logs/ 净化的事件、缓存和重试计算
```
提交的 [单页合成装置](tests/fixtures/valid-one-page) 提供了无需外部提供者的样本输出检查。其三个几何面板 PNG 是确定性测试数据，而不是生成的艺术品或声称的实时样本。
## 架构
`SKILL.md` 协调十个代理阶段，并从 `references/` 中逐步加载指导。代理推理创建可编辑的故事、角色、故事板、提示和 QA 决策。Python 脚本仅处理确定性项目状态、验证、恢复规划、字母、页面组成、PDF 导出和报告渲染。提供者访问保留在代理能力平面中；机密和提供者 SDK 不进入确定性脚本。
## 混合字母
对话使用捆绑的 Comic Neue Regular，内联 `**bold**` 强调使用 Comic Neue Bold，换行和居中度量跨混合运行。字体选择按字符进行：捆绑的 Noto Sans 涵盖希腊语和西里尔语，当 Comic Neue 不支持时，而一个字符如果在两种字体中都不存在，则保留为 Noto Sans `.notdef` 而不是静默删除。 `--font` 选项仍然覆盖常规对话字体；其粗体对应项可能会回落到 Comic Neue Bold。
Pillow 将对话放入自适应椭圆气泡中，将每个尾部附着在最近的椭圆边界上，朝向其目标，并绘制紧凑的浅色标题条，尺寸适合其文本。作者的 SFX 采用混合管道的另一半：图像模型将确切的 SFX 绘制到艺术品中，视觉 QA 验证拼写、计数和授权。Pillow 验证并计算 SFX，但不保留位置和更改像素。
## 测试
运行完整的离线套件：
```bash
python3.11 -m unittest discover -s tests -v
python3.11 scripts/comic_sol.py doctor
```
### 基础环境（仅 Pillow，跳过 MCP 测试）
创建干净的虚拟环境并仅安装基础依赖项：
```bash
python3.11 -m venv /tmp/comic-sol-base
/tmp/comic-sol-base/bin/pip install -r requirements.txt
/tmp/comic-sol-base/bin/python -m unittest discover -s tests -v
```
当缺少 `mcp` 包时，MCP 测试（`test_mcp_server.py`）会被跳过。
### MCP 额外环境（Pillow + MCP，所有测试运行）
```bash
python3.11 -m venv /tmp/comic-sol-mcp-extra
/tmp/comic-sol-mcp-extra/bin/pip install -r requirements.txt -r requirements-mcp.txt
/tmp/comic-sol-mcp-extra/bin/python -m unittest discover -s tests -v
```
干净室 Linux/macOS/WSL 检查：
```bash
tmp_dir=$(mktemp -d)
python3.11 -m venv "$tmp_dir/venv"
"$tmp_dir/venv/bin/python" -m pip install Pillow==12.3.0
"$tmp_dir/venv/bin/python" scripts/comic_sol.py doctor --output-root "$tmp_dir/output"
```
Windows 干净室等效项：
```powershell
$TempRoot = Join-Path $env:TEMP "comic-sol-clean-room"
py -3.11 -m venv "$TempRoot\venv"
& "$TempRoot\venv\Scripts\python.exe" -m pip install Pillow==12.3.0
& "$TempRoot\venv\Scripts\python.exe" scripts\comic_sol.py doctor --output-root "$TempRoot\output"
```
## 支持矩阵
| 区域 | 支持 | 备注 |
|---|---|---|
| 输入 | 短提示、粘贴散文、UTF-8 `.txt` 和 `.md`、恢复 | 源限制和默认值记录在工作流参考中。 |
| 输出 | 面板 PNG、页面 PNG、漫画 PDF、清单、QA 报告 | 可编辑的中间制品保留在本地。 |
| 字母 | Comic Neue Regular/Bold；每个字符的 Noto Sans 回落 | 自适应椭圆对话、实际内联粗体强调、紧凑标题和混合作者 SFX 支持。字体许可证和摘要在 `assets/README.md` 中。 |
| 图像生成 | 代理公开的图像模型返回本地光栅 | 参考和精确尺寸在支持时使用；精确作者 SFX 由视觉 QA 检查。 |
| 确定性脚本 | Python 3.11 和 Pillow 12.3.0 | 离线和提供者中立。 |
| 原生 MCP | Python 3.11 和 MCP SDK 1.28.1 通过 `stdio` | 公开 17 个工具，涵盖完整确定性生命周期，安全锁定到一个输出根目录。 |
## 隐私、IP 和限制
项目工件保留在选定的本地输出目录中。发送到选定的图像工具的提示和参考图像受其外部提供者策略的约束。最小化私有源材料，永远不要在故事文本或提示中放置机密。日志包含净化的路径、哈希、类别和状态更改，而不是原始凭证或故事内容。
Comic Sol 请求原始的漫画/动画方向，并将禁止的艺术家或特许经营模仿转换为高级视觉特征。它不承诺完美的角色连续性：结果取决于可用的图像能力，特别是其参考图像和尺寸支持。捆绑的字体集不涵盖 CJK；如果两种捆绑字体都不支持某个字符，则保留为可见的 `.notdef` 回落框，除非兼容的常规 `--font` 覆盖支持它。图像模型 SFX 拼写不是确定性的，因此仍然需要视觉 QA 和有限重试。离线装置证明了确定性阶段，而不是实时图像质量。大规模项目（超过四页或十二个面板）需要明确的范围决策。
对于支持，运行 `doctor`，保留打印的项目路径，并检查 `project.json` 和 `qa/report.md`。`BLOCKED` 项目故意是可恢复的；恢复缺失的能力或纠正报告的工件，然后请求 Codex 恢复该 Comic Sol 项目。
## 许可证
Comic Sol 的原始代码和文档在 [`LICENSE`](LICENSE) 下根据 MIT 许可证提供。捆绑的 Comic Neue 和 Noto Sans 字体仍然根据 SIL 开放字体许可证 1.1 单独许可；请参阅 [`assets/README.md`](assets/README.md)。
