微信小程序协作规范
> 来源：亲子成长记施工包 AGENTS.md 的通用规范部分，已剥离该项目专属的 MVP 范围 / 文档索引，成为可复用的协作基线。
这是什么
AI 写代码很容易"行为失控"：擅自重构、硬编码密钥、跳过阶段。本技能在每次新对话开始时，给 AI 一套强制规范，把这类坑提前堵死；并可生成一份项目级 AGENTS.md，让 AI 每次开工先读。还能用 --check 扫描现有工程是否违规。
脚本自带 --self-test：生成规范后回读校验「5 大原则 + 安全边界」齐全，证明可用。
何时使用
- 用户说："开始微信小程序开发" / "帮我定 AI 协作规范" / "给 AI 定工作规范"
- 新建任何需要 AI 协助编码的项目，想把协作规则固定下来
- 想生成一份
AGENTS.md放进项目根目录 - 想检查现有工程是否踩了安全红线（硬编码密钥 / .env 入库）
强制规范（AI 必须遵守）
1. 安全第一
- 禁止在代码 / 日志 / 提交记录出现密码、Token、API Key 明文
- 敏感信息只允许在配置文件或环境变量，且不在对话中展示具体值
- 涉及删除、重置、覆盖等不可逆操作，必须先向用户确认
2. 稳定优先
- 优先小步可验证改动，避免大范围重构
- 修改前说明影响范围，修改后说明验证结果
- 不破坏已在运行的功能
3. 沟通规范
- 全程简体中文沟通
- 不主动展示代码细节，除非用户要求
- 每次完成汇报：做了什么 / 为什么 / 用户能感受到什么变化
4. 最小改动原则
- 只改与当前任务直接相关的代码
- 不顺手重构 / 优化 / 加功能
- 有额外发现先汇报，由用户决定
5. 引用同步强制规则（P0，与安全同级）
- 凡改动涉及文件增删改、模块/函数/接口路径变更，必须立即全局搜索旧名，更新所有引用处
- 每日收口时再次检查当日此类改动是否同步
安全边界（最高优先级，任何角色不得违反）
- [禁止] 不能直接删除文件 —— 删除前必须列路径等用户确认
- [禁止] 不能修改
.env等配置文件 —— 敏感配置禁止自动改动 - [禁止] 不能在代码写明文密码 / Key —— 安全红线，发现须指出并拒绝
- [禁止] 不能自动提交 Git —— 提交前须展示 commit message 等确认
- [禁止] 涉及支付 —— 须完整测试，不允许在生产直接测试
- [禁止] 个人信息保护 —— 用户数据不得明文存储，须有合规隐私处理
代码质量 / 敏感信息 / 进度管理（通用约定）
- 文档语言中文；错误处理保留完整日志，不静默吞异常
.env内容绝不发给 AI；密钥只存.env，讨论配置只说字段名- 每次收口更新
progress.md（今天做了 / 明天计划 / 待决策）；新对话先读 progress.md 复述状态
分包独立开发强化（工具模块实践沉淀）
> 以下为从「」小程序工具模块真实协作规范反哺的增强项，叠加在上方通用基线之上，专治分包/多板块/Canvas 类项目的失控。
1. 命名隔离铁律（双板块/多分包场景）
- 物理 + 命名双层隔离：从源目录复制出独立分包后，所有标识符加统一前缀（如
zt-/ZT_），源文件绝不改。 - 标识符映射：全局常量
ZT_、变量zt、顶级函数ztXxx、HTML idztXxx、localStorage keyzitie_。 - 不影响项：Canvas 内部尺寸、A4 规格、颜色映射、绘制引擎核心逻辑（通用，不需前缀）。
- AI 自查：当前操作的板块/分包是哪个？是否误用了其他板块的名称、文件、变量、函数？
2. 六大模板 P0 锁定（最高优先级）
- 已定版的核心模板（如 6 个课业用纸模板）任何修改必须先征得用户明确同意，违者立即回滚。
- 锁定范围：模板预览主文件、校/机构版元素配置 JSON、网格参数配置、相关 JS/CSS/HTML、页码检测与生成逻辑。
- 禁止：增删改元素、调样式参数（位置/颜色/字体/尺寸）、改页码/绘制/切换逻辑、加功能或删功能——除非用户明确授权（"可以改"/"确认"）。
3. 三层文档追溯（收口总结强制）
- 每次收口问：今日代码改动是否已在「产品规格文档」与「技术方案文档」中反映？ 遗漏立即补。
- 文档权威等级：多文档冲突时以权威文档为准，不得自行裁决后静默处理；发现矛盾立即汇报用户。
- 文档不动原则：只允许既定文档集，禁止 AI 自动创建额外文档（临时信息写入对应章节）。
4. Canvas 专项约束（小程序 Canvas 开发）
- 开发前检查：内部尺寸固定
1240×1754（A4 150dpi）；CSS 缩放用canvas.style.width/height而非改canvas.width/height；绘制函数须能在preview.html与小程序.js间直接复制。 - 常见坑：文字模糊 → 先
ctx.font='48px serif'且canvas.width=cssW*dpr；线不直 →lineWidth偶数 + 坐标整数；导出空白 → 绘制前先赋值canvas.width/height；文字偏移 → 手动ctx.textBaseline='middle'。 - 绘制顺序（不可颠倒）：背景 → 页眉 → 网格 → 文字（最上层）→ 导出。
- 字体缺失：用系统回退
serif继续开发，不卡进度；字体就绪后替换回指定字体。
脚本用法
# 0) 先证明生成的规范齐全（推荐第一次用前跑一次）
python gen_agents.py --self-test
# 1) 生成项目级 AGENTS.md
python gen_agents.py \
--project "亲子成长记" \
--type "微信小程序" \
--role partner \
--out AGENTS.md
# 2) 检查现有工程是否违规（硬编码密钥 / .env 入库 / AGENTS 覆盖度）
python gen_agents.py --check <项目目录>
脚本把上述通用规范 + 你填的项目信息，渲染成标准 AGENTS.md，可直接放进项目根目录让 AI 每次读取。
注意事项
- 本技能提供通用基线。项目专属的 MVP 范围、接口清单、文档索引应放在独立的
AI要怎么做.md/AI开发路径.md中，不要写进 AGENTS.md（避免规范被需求污染）。 - 技术栈默认按微信小程序 + FastAPI + 数据库给出约定；换栈时同步更新"技术栈专属约定"段。
- 规范再好也要人监督——配合
ai-work-acceptance技能在每次交付后做验收。
