快捷脚本入口

Seed 把常用检查和项目事实读取做成脚本入口，方便人和 AI 用同一套命令验证项目状态。不同项目可以删减或扩展脚本，但建议保留“先计划、再执行、执行后记录证据”的习惯。

查看可用入口

如果仓库根目录提供 npm 命令面板，先运行：

npm run scripts:help

如果没有这个入口，直接查看：

ls ops/scripts
sed -n '1,160p' ops/scripts/README.md

本地开发入口

npm run dev

推荐让 npm run dev 成为新项目的稳定本地入口。它可以转发到项目自己的后端、前端或脚本启动方式，但对使用者来说只需要记一个命令。

配置读取

目标	命令
合并读取 .maw 配置	python3 ops/scripts/maw-config-merge.py components --format json
读取某个配置值	python3 ops/scripts/maw-config-get.py components components.0.key --format text
按逻辑 key 读取项目事实	python3 ops/scripts/maw-key-get.py module.dossier --module-key <module-key> --format text

这些命令适合给 AI 使用：先读取结构化事实，再决定要改哪些文件。

项目元数据

python3 ops/scripts/extract-project-metadata.py --format json
python3 ops/scripts/extract-project-metadata.py --section ai-preconditions --format markdown

适合场景：

• 开始大任务前，查看项目身份、模块、能力和提示信号。
• 审计项目前，生成可读的项目元数据摘要。
• 任务收口时，确认哪些模块、能力或待办受影响。

测试计划

python3 ops/scripts/run-project-tests.py --format json

默认建议先生成测试计划。确认要执行后，再运行：

python3 ops/scripts/run-project-tests.py --suite test --execute --format json

这样可以避免一上来跑长测试，把日志噪音和真正失败混在一起。

常用检查

检查	命令	什么时候用
diff 格式	git diff --check	提交前每次都跑。
本机边界	bash ops/scripts/check-local-boundary.sh	防止 .local/、本机路径和本机覆盖进入可提交内容。
模块文档	bash ops/scripts/check-template-module-docs.sh	修改模块规则、文档结构或 Seed 协作协议后。
脚本规范	python3 ops/scripts/check-ai-python-script-contract.py --format json	新增或升级 ops/scripts/ 后。
分发就绪	bash ops/scripts/check-seed-distribution-readiness.sh	准备打包、发布 Seed 或公开 Pack 前。
开源就绪	bash ops/scripts/check-seed-open-source-readiness.sh --format json	准备公开仓库、公开示例或公开任务包前。

严格发布前可以使用：

bash ops/scripts/check-seed-open-source-readiness.sh --strict --format json

任务包下载

如果你用 zip 分发任务包，可以先下载到临时目录再导入：

python3 ops/scripts/download-task-pack-url.py "<task-pack-zip-url>" --output "/tmp/task-pack.zip"

公开文档里不要写一次性下载 token、访问密码或非公开分享链接。需要分享任务包时，优先提供公开仓库地址、公开 release 文件或已经脱敏的 zip。

公开发布计划

准备把 Seed、Pack 或公开示例发布到公开仓库前，先看计划：

bash ops/scripts/publish-repository-mirror.sh plan public_seed --version vX.Y.Z

只有确认版本、tag、发布模式、目标仓库和检查 gate 后，才允许执行写入动作：

bash ops/scripts/publish-repository-mirror.sh publish public_seed --version vX.Y.Z --execute

公开发布不应绕过脱敏和 readiness gate。

常见错误

错误	修正方式
只跑 build，不跑公开检查	同时运行 local boundary、open-source readiness 和分发检查。
命令输出太长	优先使用支持 --format json 的脚本。
写远端前不看计划	先运行 plan 或 dry-run，再人工确认。
把一次性 token 写进文档	只写占位或说明，不写真实 token。

下一步

阅读 检查与发布 gate，把这些脚本组合成提交前和公开发布前的检查链路。