规范约定

术语

content/ 是学术内容的 canonical source。
packages/ 放所有可安装或可发布的包源。
tooling/ 放维护自动化和运营资产。
根目录 scripts/ 是稳定 wrapper 层；真正实现编辑 tooling/scripts/。
根目录 qiongli-workflow/、plugins/qiongli/、plugins/qiongli-next/ 和 .agent/ 是生成后的 distribution 形状；源文件在 content/ 和 content/distribution/plugins.yaml。

跨多层修改时，优先按这个顺序：

content/standards/：contract 或 routing 真源。
content/roles/ 与 content/skills/：责任归属或执行行为。
content/templates/：稳定结构化输出。
tooling/pipelines/、content/workflow/workflows/、content/distribution/plugins.yaml：编排、入口 UX 或 plugin metadata。
packages/python-qiongli/src/qiongli/：只有运行时执行逻辑需要变化时才改。
generated payloads：只能通过 staged materialization 生成。

变化类型	放这里
artifact paths、task outputs、quality gates	`content/standards/research-workflow-contract.yaml`
runtime routing、MCP requirements、skill requirements	`content/standards/mcp-agent-capability-map.yaml`
functional ownership、thresholds、tone	`content/roles/`
可复用 task 行为	`content/skills/`
可复用 markdown/table 结构	`content/templates/`
subject catalog 或 overlays	`content/subjects/`
domain/venue profile 数据	`content/skills/domain-profiles/`、`content/venue-profiles/`
pipeline 编排	`tooling/pipelines/`
维护自动化	`tooling/scripts/`
public script 入口兼容	根目录 `scripts/` wrapper，仅在兼容层变化时
Python runtime、CLI、installer、bridges	`packages/python-qiongli/src/qiongli/`
plugin manifest、prompt、keywords 或平台开关	`content/distribution/plugins.yaml`
plugin command wrapper、MCP bundle manifest 或平台入口文件结构	`tooling/scripts/build_plugin_artifacts.py`
npm package wrapper	`packages/npm-qiongli/`
eval cases、rubrics、runners	`evals/`

只有同时满足以下条件，才新增 internal top-level skill：

否则优先扩展现有 skill、template、provider adapter、role 或 pipeline step。

不要直接编辑生成 payload。使用：

bash

python3 scripts/materialize_distribution_payloads.py --target all --out /tmp/qiongli-dist --force

受 ignore 和 guard 保护的生成路径包括：

research_skills 是位于 packages/python-qiongli/src/research_skills/ 的 deprecated compatibility shim。迁移窗口内保持兼容，但新 import 和新文档应使用 qiongli。