该技能用于指导如何将一项变更交付到 Petrinaut 相关包中,涉及 libs/@hashintel/petrinaut、petrinaut-core 和 apps/petrinaut-website。长期约定(变更集政策、文档与图表位置、CI 特殊行为)记录在 libs/@hashintel/petrinaut/AGENTS.md,本技能则是应用这些约定的操作流程。
一、验证门禁 每完成一个增量、对每个被触及的包运行:yarn fix:format;turbo run build test:unit lint:tsc lint:eslint --filter @hashintel/petrinaut --filter @hashintel/petrinaut-core --force --output-logs errors-only;以及 yarn lint:format。turbo 版本由 .config/mise/config.toml 中的 mise 固定,通过 npx 运行会绕过固定版本并下载最新发布版。过滤器应裁剪到被触及的包;当 apps/petrinaut-website 消费该变更时,追加 --filter @apps/petrinaut-website。build 必须包含在列表中,因为 test:unit 依赖 ^build(构建依赖而非所选包),否则 React Compiler 检查、浏览器入口检查和网站的 Vite 构建都不会运行。
二、结构或文档变更 结构变化(新增文件夹、移动模块)时,还需运行 yarn workspace @apps/petrinaut-docs lint:arch-docs,并添加 AGENTS.md 架构章节要求的层声明。arch-docs 作者内容或 content/diagrams/*.d2 变更时,lint:arch-docs 不编译 MDX 也不渲染 D2,推送前需运行一次站点构建:mise x -- yarn exec turbo run build --filter @apps/petrinaut-docs。含 : 或 [ 的 D2 标签必须加引号。
三、Python 变更 libs/@local/petrinaut-optimizer-core/python 中的 Python 变更通过 Turborepo 处理:turbo run test:unit lint:tach lint:deptry --filter petrinaut-optimizer-core --force。其 test:unit 是 CPython 的 uv run pytest 套件。
四、格式化 格式化使用 yarn 脚本中的 oxfmt,不要直接运行 prettier。yarn lint:format 在最后一行之前打印结论,因此应检查退出码而非输出末行。
五、变更集 每个 PR 一个 patch 变更集,覆盖该 PR 触及的已发布包(@hashintel/petrinaut、@hashintel/petrinaut-core);纯重构不需要。文本保持一两句平实句子,完整政策见 AGENTS.md。
六、文档同步 用户可见行为变更需在同一 PR 更新用户指南;新页面需要注册和 raw import,二者由测试强制。步骤见 libs/@hashintel/petrinaut/AGENTS.md 的“User-facing docs”章节。文档截图不能由智能体上传:需生成候选截图、列出需重新截取的页面与章节,并在 PR 正文和摘要中标注“screenshots pending”。
七、提交前检查 读取相对基线的 git diff --stat:不得有意外目录、未暂存残留、生成产物或 mise.lock 变动。文本文件的 stat 中出现 Bin 行表示转义序列变成字面控制字节,推送前必须修复,否则 diff 无法审查。过大无法一次审查的 diff 应拆成堆叠 PR,每层一个关注点。
八、草稿、CI 与就绪 以草稿形式打开 PR,正文按组织默认模板 hashintel/.github 中的 docs/pull_request_template.md。监视检查直到运行稳定,并用 jq 判定:gh pr checks 在检查待定、失败或尚未排程时都会返回非零,使用 --json 时在任何检查存在前打印 [],因此待定数为零也可能被误读为“已完成”。示例脚本用 settled 表达式判断:检查列表非空且待定数为零即结束,失败也报告。等待是有界的,最后一次调用保留输出,令牌过期或 API 不可达会以错误呈现而非无限等待。判断失败前需对照 AGENTS.md 约定的 CI 条目(Bench-CI 非阻塞、已知易抖动检查、Vercel 侧文档失败)。仅在检查全绿时转为就绪;此时 AI 审查者运行,应处理其讨论线程而非放任未解决。任何改变了分支的回合结束时,应说明提交并推送了什么,或说明未做任何变更。