✅ {Phase Name} Complete

✅ {Phase Name} Complete

• [x] {evidence-driven assertion 1}
• [x] {evidence-driven assertion 2}
• [ ] Next: {next-phase pointer}

条目必须是**证据驱动**的（`file exists at path X`、`status N is Generated`），而非愿景驱动（`prompts are good`）。

### 11. 全层禁用模式

- 本地化的警告/惊叹引用块（用 `> Note` 或省略）；
- 标题中的装饰性 emoji（`✅` 仅限检查点标题中的这一处合法用法）；
- 笑脸 / 闪光 / 火焰 emoji；
- 脚注（`[^1]`）；
- Markdown 正文中的 HTML（`<details>`、`<br>` 等）——只有 SVG 嵌入示例允许在代码块里使用真实 `<svg>`/`<image>`，绝不允许作为活动 Markdown；
- 未标注强度的 "**Best practice**: ..." 标签——应改用第 4 节的强度标签。**永远不要留下未标注的软性建议**：对模型来说，未加标签的行会被读成硬性规则。

### 12. 与既有文件冲突时

既有文件是 ground truth。若某个现存 `references/*.md` 违反了本条规则，要么 (a) 更新本指南以匹配事实约定，要么 (b) 重构那个文件——不要静默地把一种分叉风格套到单个新文件上。仓库给出了可作为模板的范本映射：

| 如果你在写... | 以它为范本 |
|---|---|
| 角色参考（Image_X / Strategist 风格） | [image-searcher.md](https://gitcode.com/GitHub_Trending/ppt/ppt-master/blob/710d056ed28cd520875218d8398fa46ba5269456/skills/ppt-master/references/image-searcher.md?utm_source=gitcode_repo_files)、[strategist.md](https://gitcode.com/GitHub_Trending/ppt/ppt-master/blob/710d056ed28cd520875218d8398fa46ba5269456/skills/ppt-master/references/strategist.md?utm_source=gitcode_repo_files) |
| 跨角色的共享规格 | [image-base.md](https://gitcode.com/GitHub_Trending/ppt/ppt-master/blob/710d056ed28cd520875218d8398fa46ba5269456/skills/ppt-master/references/image-base.md?utm_source=gitcode_repo_files)、[shared-standards-core.md](https://gitcode.com/GitHub_Trending/ppt/ppt-master/blob/710d056ed28cd520875218d8398fa46ba5269456/skills/ppt-master/references/shared-standards-core.md?utm_source=gitcode_repo_files) |
| 技术 / 格式规格 | [canvas-formats.md](https://gitcode.com/GitHub_Trending/ppt/ppt-master/blob/710d056ed28cd520875218d8398fa46ba5269456/skills/ppt-master/references/canvas-formats.md?utm_source=gitcode_repo_files)、[svg-image-embedding.md](https://gitcode.com/GitHub_Trending/ppt/ppt-master/blob/710d056ed28cd520875218d8398fa46ba5269456/skills/ppt-master/references/svg-image-embedding.md?utm_source=gitcode_repo_files)、[image-layout-spec.md](https://gitcode.com/GitHub_Trending/ppt/ppt-master/blob/710d056ed28cd520875218d8398fa46ba5269456/skills/ppt-master/references/image-layout-spec.md?utm_source=gitcode_repo_files) |
| 阶段运行手册 | `skills/ppt-master/workflows/stages/` 下的 verify-charts 等 runbook |

### 13. 提示词重构评审

提示词压缩只有在**分别**评审 token 削减与语义变化之后才算完成：

| 检查项 | 所需证据 |
|---|---|
| 所有者与消费者 | 每个被移动的字段/能力仍有唯一权威，且每个运行时消费者加载或投影该权威 |
| 强度差 | 对被删除、移动或重写的 `Hard rule` / `Forbidden` / `Default` / `Reference` 指令记录 `before → after` |
| 失败谓词 | 保留支撑每个非自明硬边界的紧凑客观不变量 |
| 自由边界 | 许可没有变成配额、参考没有变成锁、灵活实现没有变成静默重选 |
| 准备时机 | Strategist 拥有的获取与物化没有移入 Executor 或移到最终确认之前 |
| 能力发现 | 条件性深层规格在其加载门前保留短可见菜单或外部可观察触发器 |
| token 差 | 路由/文件预算变更需单独报告；预算通过不能证明语义等价 |

**硬性规则**：一个更短的提示词若改变了决策所有权、约束强度、准备时机或能力可发现性，即使结构与 token 预算审计全部通过，仍是语义回归。

## Python 代码风格规范（code-style.md）

[code-style.md](https://gitcode.com/GitHub_Trending/ppt/ppt-master/blob/710d056ed28cd520875218d8398fa46ba5269456/docs/rules/code-style.md?utm_source=gitcode_repo_files) 约束 [skills/ppt-master/scripts/](https://gitcode.com/GitHub_Trending/ppt/ppt-master/blob/710d056ed28cd520875218d8398fa46ba5269456/skills/ppt-master/scripts/?utm_source=gitcode_repo_files) 下所有 Python。它自述为"务实而非穷尽"——只捕捉读者实际会遇到的约定，PEP 8 免费提供的内容不再赘述。仓库里约 240 个 Python 文件正是这套规范的实际产物，下述多数约定都能在真实脚本中直接验证。

### 1. 文件头（File Header）

`scripts/` 下每个脚本必须以固定结构开头：

```python
#!/usr/bin/env python3
"""
PPT Master - Short Tool Name

One-paragraph description of what this script does.

Usage:
    python3 scripts/<name>.py <required_arg> [options]

Examples:
    python3 scripts/<name>.py projects/<project_name> -o output_dir

Dependencies:
    None (only uses standard library)        <-- or list third-party deps
"""

元素	规则
Shebang	#!/usr/bin/env python3（即使是非 CLI 辅助模块也要有）
模块 docstring	工具名 + 用途 + Usage + Examples + Dependencies
内部辅助模块	可加早期 --help 短路（见第 4 节）

2. 导入分组

# 1. Standard library
import os
import sys
import argparse
import re
from pathlib import Path
from typing import Optional

# 2. Third-party
import requests

# 3. Local — sometimes need sys.path injection first (see §3)
from image_sources.provider_common import (
    AssetCandidate,
    ImageSearchRequest,
)

规则：分组顺序 std → third-party → local，组间空行；组内短导入按长度、≥ 4 个导入按字母序；from x import 列表在 ≥ 4 个名字时每行一个并带尾逗号；当文件使用 PEP 604 的 X | Y 联合语法且可能运行在 Python < 3.10 时，在顶部加 from __future__ import annotations。

3. sys.path 注入（项目约定）

scripts/ 不是 Python 包，而是扁平的脚本目录。每个需要导入兄弟模块的入口脚本都要自己把 scripts/ 注入 sys.path：

import sys
from pathlib import Path

_SCRIPTS_DIR = Path(__file__).resolve().parent
if str(_SCRIPTS_DIR) not in sys.path:
    sys.path.insert(0, str(_SCRIPTS_DIR))

from image_backends.backend_common import download_image  # noqa: E402

规则：只在入口点注入（image_sources/、image_backends/ 等库模块之间正常互相导入）；用 Path(__file__).resolve().parent 以在符号链接与别名场景下保持稳健；注入后的导入用 # noqa: E402 诚实抑制 lint 警告，而不是整文件 noqa。scripts/ 下 image_sources/、image_backends/ 等子目录（含 provider_common、backend_common 等共享模块）的存在印证了这一约定。

4. CLI 入口点

def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="One-line description.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument("query", help="...")
    parser.add_argument("-o", "--output", default=".", help="...")
    return parser


def main(argv: Optional[list[str]] = None) -> int:
    parser = build_parser()
    args = parser.parse_args(argv)
    # ... do the thing ...
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

规则	备注
main(argv=None) -> int	返回退出码；可传入 argv 以便测试
raise SystemExit(main())	优于 sys.exit(main())
formatter_class=argparse.RawDescriptionHelpFormatter	让 docstring 格式在 --help 中原样保留
内部辅助模块的 --help	模块级 if __name__ == "__main__" and any(...) 早退
输出	进度 / 状态写 stderr；主输出（若有）写 stdout

帮助与参数校验要求：-h / --help 必须由 argparse（首选）或显式早期守卫处理，且须在任何副作用之前——不得创建目录、写文件、发网络请求、装包或启动常驻服务；帮助标志绝不能被当作位置参数值（init --help 不能创建一个名为 --help 的项目，export --help 不能写出名为 --help 的文件）；带子命令的脚本用 argparse subparsers，每个子命令要有自己的帮助并先校验必选参数再干活；缺失必选参数与未知标志必须打印 usage/error 并非零退出，禁止静默忽略。可直接执行仅供诊断的内部辅助模块，非帮助调用要么执行文档化的诊断命令，要么打印简短的 "use via ..." 提示并非零退出，不得以 import 回溯告终。

控制台编码：每个可直接运行的入口脚本都必须在启动时调用一次 configure_utf8_stdio()（来自 console_encoding.py，见第 9 节），且须在任何面向用户的 print 或导入可能打印的可选依赖之前。它强制 stdout/stderr 为带 errors="replace" 的 UTF-8，使非 UTF-8 的 Windows 区域设置（如 GBK）不会因 Unicode 状态输出而崩溃；本身已是 UTF-8 的系统上行为不变。文件 I/O 仍需显式传 encoding="utf-8"（第 13 节），此规则只管控制台。该函数在 console_encoding.py 中实现。

5. 类型注解

所有新公开函数必须加注解；内部 _helpers 可选。

模式	用途
def f(x: str, *, y: int = 0) -> bool:	公开函数
tuple[int, int] | None	PEP 604 联合（必要时配合 from __future__ import annotations）
Optional[X]（来自 typing）	X | None 的可接受替代
list[X]、dict[K, V]	内置泛型（Python 3.9+）
Any	克制使用——只在对接真正异构数据时用

禁止过度规格化：如 Callable[[int, str], dict[str, list[Optional[Union[int, str]]]]] 应拆成带类型的 dataclass；Literal["a","b","c"] 不要到处用——除非类型本身就是 API。

6. 命名

种类	约定	示例
模块文件	snake_case.py	image_search.py、svg_to_pptx.py
脚本入口	动词或名词短语	finalize_svg.py、notes_to_audio.py
公开函数	snake_case	download_image、parse_results
私有辅助	_snake_case	_load_dotenv_if_available、_measure_actual_image
常量	UPPER_SNAKE_CASE	API_URL、DEFAULT_PAGE_SIZE
类	PascalCase	AssetCandidate、SVGQualityChecker
dataclass 字段	snake_case	license_tier、download_url
模块私有正则	私有 + _RE 后缀	_TAG_RE、HEADING_RE

7. 错误处理

情形	模式
可选依赖	try: import x; HAS_X = True + except ImportError: HAS_X = False
可选兄弟模块	try/except 包裹并回退默认值 + 警告
可恢复运行时失败	捕获具体异常、记 stderr、return / continue——不得终止管线
用户可见错误	从 main() 打印到 stderr 并 return 1
编程错误	Raise——不用补丁掩盖 bug

硬性规则：永远不要裸 except:，必须指名异常类。禁止安全相关代码的静默回退：没有域名白名单 + WARNING 不得禁用 SSL 校验；下载路径中捕获所有异常却不记录原因同样被禁。

8. 依赖分层

层级	可被要求的位置
标准库	任何地方
requests、Pillow、lxml	常用依赖，主脚本可安全要求
Provider SDK（google-genai、openai、anthropic 等）	在使用它的函数内部惰性导入；以 ImportError → 含安装指引的 RuntimeError 软失败
python-dotenv	可选——try/except 包裹，缺失时无操作

def _require_api_key() -> str:
    key = os.environ.get("PEXELS_API_KEY") or ""
    if not key:
        raise RuntimeError(
            "PEXELS_API_KEY is not set. Add it to your environment or .env file. "
            "Get one at https://www.pexels.com/api/"
        )
    return key

错误消息必须包含修复方法——"要设哪个环境变量""到哪里拿 key""要装哪个包"。仓库 requirements.txt 与 skills/ppt-master/requirements.txt 的分层依赖与此对应。

9. 共享辅助层

公共功能必须放在指定子模块中，新脚本使用这些实现而非各自复制一份：

模块	职责
backend_common.py	HTTP 下载、重试、图像格式检测、Pillow 转码保存
provider_common.py	许可分类、查询简化、评分、署名文本、dataclass
project_utils.py	画布格式、项目路径约定
slide_roster.py	数字幻灯片文件名排序与 SVG 名册发现
error_helper.py	面向用户的错误消息模板
console_encoding.py	configure_utf8_stdio()——CLI 入口强制 UTF-8 控制台

禁止复制共享辅助中已存在的逻辑——辅助缺功能就扩展辅助，不要在自己的新脚本里 fork 一份。

10. Docstring

短小、祈使式。除非签名确实复杂，否则不加 Args/Returns/Raises 段。

def classify_license(
    license_name: str,
    license_url: str = "",
    provider: str = "",
) -> Optional[str]:
    """Classify a license string into one of the two tiers, or reject it.

    Returns:
        ``"no-attribution"`` / ``"attribution-required"`` / ``None``.

    The provider hint lets us treat Pexels and Pixabay's own licenses as
    ``no-attribution`` even when the upstream API only returns a short
    label like ``"Pexels"``.
    """

用 Google/Sphinx 风格块的判据：函数返回多个语义有差异的分支；参数 > 3 且角色不明显；维持了非平凡不变量。反之单行自解释即可。

11. 测试约定：仓库不随附自动化测试

硬性规则：本仓库不发布自动化测试。被禁的包括：tests/ 目录、test_*.py 文件、unittest / pytest 导入、以及运行自测套件的 if __name__ == "__main__": 块。取而代之的是：

• 对真实项目样例用 python3 -c "..." 做行内冒烟命令，把输出展示在对话 / PR 描述中；
• 运行手册中的手工验证步骤；
• 对 projects/_smoke_* 目录（已 gitignore）做 live-API 冒烟运行。

这是刻意的项目约定。外部贡献者若附带了测试，评审时请他们移除（prompt-style.md 第 11 节对参考文档有并行规则）。这一点与"参考文档层由运行时 LLM 驱动、检查器不得检查口味"的整体设计一脉相承——验证方式转向基于真实产物的冒烟检查。

12. Dataclass

值类型优先用普通 @dataclass，而非 pydantic / attrs，保持简单：

@dataclass
class AssetCandidate:
    provider: str
    title: str
    asset_id: str = ""
    license_tier: str = ""
    width: int = 0
    height: int = 0
    raw: Any = None