muse-agent-example/docs/系统架构/新版设计/文件设计/工程配置与部署.md

工程配置与部署：文件合同

本页从目标文件清单投影，共 49 个目标条目。测试身份与行为合同在现行用例清单；文件和目标合同不代表实现或验收已完成。

返回目录 · 完整项目树 · 现行用例清单

本部分文件树

agent-example/
├── .editorconfig  # 编辑格式
├── .gitattributes  # 文本换行与差异属性
├── .github/
│   └── workflows/
│       ├── 构建.yml  # 资源、前后端打包与安装产物验证
│       └── 检查.yml  # 静态、契约、隔离测试和索引检查
├── .gitignore  # 私人数据、缓存及构建产物排除
├── .python-version  # Python 运行版本
├── AGENTS.md  # 项目入口与设计、规则、验证导航
├── CLAUDE.md  # 兼容入口，只引用 AGENTS.md
├── Makefile  # 安装、生成、检查、测试和构建入口
├── README.md  # 安装、启动与日常使用入口
├── pyproject.toml  # 应用包、命令、依赖与检查配置
├── uv.lock  # Python 依赖锁
├── 工具/
│   ├── 构建发布.py  # 生成带哈希轮子、依赖和部署配置的独立发布目录
│   ├── 构建资源包.py  # 生成运行资源与发布清单
│   ├── 环境预检.py  # 安装包、连接和宿主能力核查
│   ├── 生成接口.py  # 生成 Schema、OpenAPI 和 TypeScript
│   ├── 生成输入.json  # 接口生成的唯一登记输入
│   ├── 维护索引.py  # 索引生成、查重及检查
│   └── 资源登记.json  # 运行资源包的唯一登记输入
├── 部署/
│   ├── Dockerfile  # 前端构建和后端发布镜像
│   ├── Pi/
│   │   ├── package-lock.json  # Pi运行依赖完整性锁
│   │   └── package.json  # 固定Pi宿主和Node版本
│   ├── compose.test.yaml  # 隔离 PostgreSQL 和测试环境
│   ├── compose.yaml  # HTTP、任务与隔离评测执行配置
│   ├── 停止.sh  # 优雅停止并保护正在执行的任务
│   ├── 启动.sh  # 启动已配置进程
│   ├── 应用.example.toml  # 无凭据值的生产用途配置示例
│   └── 部署.example.env  # 明确实例、镜像摘要和受控存储引用
└── 配置/
    ├── 工具策略.yaml  # 允许工具和用途
    ├── 应用.example.toml  # 服务地址和资源、连接引用模板
    ├── 提供方.example.toml  # 提供方能力与凭据引用模板
    ├── 检索策略.yaml  # 切块、召回与预算
    ├── 流程模板/
    │   ├── 作品准备.yaml  # 作品准备 的具名步骤与开放槽位模板
    │   ├── 完整审校.yaml  # 完整审校保护节点与judge步骤模板
    │   ├── 定稿交付.yaml  # 定稿交付 的具名步骤与开放槽位模板
    │   ├── 审校修订.yaml  # 审校修订 的具名步骤与开放槽位模板
    │   ├── 执行评测-检测.yaml  # 独立detector准备、发送与交付流程
    │   ├── 执行评测-比较.yaml  # 独立成对比较的固定保护节点与judge槽位
    │   ├── 执行评测-生成.yaml  # 逐例生成的固定保护节点与writer槽位
    │   ├── 数据维护.yaml  # 数据维护 的具名步骤与开放槽位模板
    │   ├── 生成正文.yaml  # 生成正文 的具名步骤与开放槽位模板
    │   ├── 生成规划.yaml  # 受控规划的冻结、生成和候选保存保护流程
    │   ├── 研究拆书.yaml  # 研究拆书 的具名步骤与开放槽位模板
    │   ├── 章后处理.yaml  # 章后处理 的具名步骤与开放槽位模板
    │   ├── 经验改进.yaml  # 经验改进 的具名步骤与开放槽位模板
    │   └── 规划章节.yaml  # 规划章节 的具名步骤与开放槽位模板
    ├── 测试.example.toml  # 隔离测试与真实调用显式配置
    ├── 角色策略.yaml  # 角色模型能力与工具模式
    └── 预算策略.yaml  # 五小时额度窗口、并发和停止条件

逐文件合同

AGENTS.md

• 归属与种类：工程；文档。
• 意图：明确“项目入口与设计、规则、验证导航”的设计或生成合同。
• 职责：项目入口与设计、规则、验证导航。
• 边界：只在其主题内维护定义，其他文档引用；不把目标写成已实现状态。
• 目标：读者可定位接口、失败、验收和关联主题，引用有效且没有第二份当前定义。
• 合同依据：设计文档。

CLAUDE.md

• 归属与种类：工程；文档。
• 意图：明确“兼容入口，只引用 AGENTS.md”的设计或生成合同。
• 职责：兼容入口，只引用 AGENTS.md。
• 边界：只在其主题内维护定义，其他文档引用；不把目标写成已实现状态。
• 目标：读者可定位接口、失败、验收和关联主题，引用有效且没有第二份当前定义。
• 合同依据：设计文档。

README.md

• 归属与种类：工程；文档。
• 意图：明确“安装、启动与日常使用入口”的设计或生成合同。
• 职责：安装、启动与日常使用入口。
• 边界：只在其主题内维护定义，其他文档引用；不把目标写成已实现状态。
• 目标：读者可定位接口、失败、验收和关联主题，引用有效且没有第二份当前定义。
• 合同依据：设计文档。

pyproject.toml

• 归属与种类：工程；工程配置。
• 意图：固定工程的“应用包、命令、依赖与检查配置”约定。
• 职责：应用包、命令、依赖与检查配置。
• 边界：只约束安装、构建或编辑配置；不规范化作者正文、不替代业务权限与验收。
• 目标：工具使用相同依赖和格式规则，相关变更可明确检查。
• 合同依据：工程约定。

uv.lock

• 归属与种类：工程；工程配置。
• 意图：固定工程的“Python 依赖锁”约定。
• 职责：Python 依赖锁。
• 边界：只约束安装、构建或编辑配置；不规范化作者正文、不替代业务权限与验收。
• 目标：工具使用相同依赖和格式规则，相关变更可明确检查。
• 合同依据：工程约定。

.python-version

• 归属与种类：工程；工程配置。
• 意图：固定工程的“Python 运行版本”约定。
• 职责：Python 运行版本。
• 边界：只约束安装、构建或编辑配置；不规范化作者正文、不替代业务权限与验收。
• 目标：工具使用相同依赖和格式规则，相关变更可明确检查。
• 合同依据：工程约定。

.gitignore

• 归属与种类：工程；工程配置。
• 意图：固定工程的“私人数据、缓存及构建产物排除”约定。
• 职责：私人数据、缓存及构建产物排除。
• 边界：只约束安装、构建或编辑配置；不规范化作者正文、不替代业务权限与验收。
• 目标：工具使用相同依赖和格式规则，相关变更可明确检查。
• 合同依据：工程约定。

.gitattributes

• 归属与种类：工程；工程配置。
• 意图：固定工程的“文本换行与差异属性”约定。
• 职责：文本换行与差异属性。
• 边界：只约束安装、构建或编辑配置；不规范化作者正文、不替代业务权限与验收。
• 目标：工具使用相同依赖和格式规则，相关变更可明确检查。
• 合同依据：工程约定。

.editorconfig

• 归属与种类：工程；工程配置。
• 意图：固定工程的“编辑格式”约定。
• 职责：编辑格式。
• 边界：只约束安装、构建或编辑配置；不规范化作者正文、不替代业务权限与验收。
• 目标：工具使用相同依赖和格式规则，相关变更可明确检查。
• 合同依据：工程约定。

Makefile

• 归属与种类：工程；工程配置。
• 意图：固定工程的“安装、生成、检查、测试和构建入口”约定。
• 职责：安装、生成、检查、测试和构建入口。
• 边界：只约束安装、构建或编辑配置；不规范化作者正文、不替代业务权限与验收。
• 目标：工具使用相同依赖和格式规则，相关变更可明确检查。
• 合同依据：工程约定。

配置/应用.example.toml

• 归属与种类：配置；配置。
• 意图：为 服务地址和资源、连接引用模板 提供无凭据的可审声明。
• 职责：服务地址和资源、连接引用模板。
• 边界：仅模板与策略，不包含真实密钥、不读评测答案、不越过角色能力上限。
• 目标：配置可以校验和版本化，实际任务保存明确生效版本。
• 合同依据：配置模板。

配置/提供方.example.toml

• 归属与种类：配置；配置。
• 意图：为 提供方能力与凭据引用模板 提供无凭据的可审声明。
• 职责：提供方能力与凭据引用模板。
• 边界：仅模板与策略，不包含真实密钥、不读评测答案、不越过角色能力上限。
• 目标：配置可以校验和版本化，实际任务保存明确生效版本。
• 合同依据：配置模板。

配置/角色策略.yaml

• 归属与种类：配置；配置。
• 意图：为 角色模型能力与工具模式 提供无凭据的可审声明。
• 职责：角色模型能力与工具模式。
• 边界：仅模板与策略，不包含真实密钥、不读评测答案、不越过角色能力上限。
• 目标：配置可以校验和版本化，实际任务保存明确生效版本。
• 合同依据：配置模板。

配置/预算策略.yaml

• 归属与种类：配置；配置。
• 意图：为 五小时额度窗口、并发和停止条件 提供无凭据的可审声明。
• 职责：五小时额度窗口、并发和停止条件。
• 边界：仅模板与策略，不包含真实密钥、不读评测答案、不越过角色能力上限。
• 目标：配置可以校验和版本化，实际任务保存明确生效版本。
• 合同依据：配置模板。

配置/工具策略.yaml

• 归属与种类：配置；配置。
• 意图：为 允许工具和用途 提供无凭据的可审声明。
• 职责：允许工具和用途。
• 边界：仅模板与策略，不包含真实密钥、不读评测答案、不越过角色能力上限。
• 目标：配置可以校验和版本化，实际任务保存明确生效版本。
• 合同依据：配置模板。

配置/检索策略.yaml

• 归属与种类：配置；配置。
• 意图：为 切块、召回与预算 提供无凭据的可审声明。
• 职责：切块、召回与预算。
• 边界：仅模板与策略，不包含真实密钥、不读评测答案、不越过角色能力上限。
• 目标：配置可以校验和版本化，实际任务保存明确生效版本。
• 合同依据：配置模板。

配置/测试.example.toml

• 归属与种类：配置；配置。
• 意图：为 隔离测试与真实调用显式配置 提供无凭据的可审声明。
• 职责：隔离测试与真实调用显式配置。
• 边界：仅模板与策略，不包含真实密钥、不读评测答案、不越过角色能力上限。
• 目标：配置可以校验和版本化，实际任务保存明确生效版本。
• 合同依据：配置模板。

配置/流程模板/作品准备.yaml

• 归属与种类：编排；运行资源。
• 意图：将 作品准备 的允许步骤组织为可审配置。
• 职责：作品准备 的具名步骤与开放槽位模板。
• 边界：仅引用已登记处理器和槽位；不能删除保护节点或运行任意脚本。
• 目标：发布版本可固定，所有合法路径保留适用前置与确认。
• 合同依据：流程模板。

配置/流程模板/规划章节.yaml

• 归属与种类：编排；运行资源。
• 意图：将 规划章节 的允许步骤组织为可审配置。
• 职责：规划章节 的具名步骤与开放槽位模板。
• 边界：仅引用已登记处理器和槽位；不能删除保护节点或运行任意脚本。
• 目标：发布版本可固定，所有合法路径保留适用前置与确认。
• 合同依据：流程模板。

配置/流程模板/生成正文.yaml

• 归属与种类：编排；运行资源。
• 意图：将 生成正文 的允许步骤组织为可审配置。
• 职责：生成正文 的具名步骤与开放槽位模板。
• 边界：仅引用已登记处理器和槽位；不能删除保护节点或运行任意脚本。
• 目标：发布版本可固定，所有合法路径保留适用前置与确认。
• 合同依据：流程模板。

配置/流程模板/研究拆书.yaml

• 归属与种类：编排；运行资源。
• 意图：将 研究拆书 的允许步骤组织为可审配置。
• 职责：研究拆书 的具名步骤与开放槽位模板。
• 边界：仅引用已登记处理器和槽位；不能删除保护节点或运行任意脚本。
• 目标：发布版本可固定，所有合法路径保留适用前置与确认。
• 合同依据：流程模板。

配置/流程模板/审校修订.yaml

• 归属与种类：编排；运行资源。
• 意图：将 审校修订 的允许步骤组织为可审配置。
• 职责：审校修订 的具名步骤与开放槽位模板。
• 边界：仅引用已登记处理器和槽位；不能删除保护节点或运行任意脚本。
• 目标：发布版本可固定，所有合法路径保留适用前置与确认。
• 合同依据：流程模板。

配置/流程模板/章后处理.yaml

• 归属与种类：编排；运行资源。
• 意图：将 章后处理 的允许步骤组织为可审配置。
• 职责：章后处理 的具名步骤与开放槽位模板。
• 边界：仅引用已登记处理器和槽位；不能删除保护节点或运行任意脚本。
• 目标：发布版本可固定，所有合法路径保留适用前置与确认。
• 合同依据：流程模板。

配置/流程模板/经验改进.yaml

• 归属与种类：编排；运行资源。
• 意图：将 经验改进 的允许步骤组织为可审配置。
• 职责：经验改进 的具名步骤与开放槽位模板。
• 边界：仅引用已登记处理器和槽位；不能删除保护节点或运行任意脚本。
• 目标：发布版本可固定，所有合法路径保留适用前置与确认。
• 合同依据：流程模板。

配置/流程模板/定稿交付.yaml

• 归属与种类：编排；运行资源。
• 意图：将 定稿交付 的允许步骤组织为可审配置。
• 职责：定稿交付 的具名步骤与开放槽位模板。
• 边界：仅引用已登记处理器和槽位；不能删除保护节点或运行任意脚本。
• 目标：发布版本可固定，所有合法路径保留适用前置与确认。
• 合同依据：流程模板。

配置/流程模板/数据维护.yaml

• 归属与种类：编排；运行资源。
• 意图：将 数据维护 的允许步骤组织为可审配置。
• 职责：数据维护 的具名步骤与开放槽位模板。
• 边界：仅引用已登记处理器和槽位；不能删除保护节点或运行任意脚本。
• 目标：发布版本可固定，所有合法路径保留适用前置与确认。
• 合同依据：流程模板。

工具/构建资源包.py

• 归属与种类：工程；源码。
• 意图：在工程阶段执行 生成运行资源与发布清单。
• 职责：生成运行资源与发布清单。
• 边界：只处理声明的生成、索引或预检；不改变业务数据或自行批准发布。
• 目标：命令可报告差异与失败，生成物与唯一输入一致。
• 合同依据：工程工具。
• 唯一登记输入：工具/资源登记.json。

工具/生成接口.py

• 归属与种类：工程；源码。
• 意图：在工程阶段执行 生成 Schema、OpenAPI 和 TypeScript。
• 职责：生成 Schema、OpenAPI 和 TypeScript。
• 边界：只处理声明的生成、索引或预检；不改变业务数据或自行批准发布。
• 目标：命令可报告差异与失败，生成物与唯一输入一致。
• 合同依据：工程工具。
• 唯一登记输入：工具/生成输入.json。

工具/维护索引.py

• 归属与种类：工程；源码。
• 意图：在工程阶段执行 索引生成、查重及检查。
• 职责：索引生成、查重及检查。
• 边界：只处理声明的生成、索引或预检；不改变业务数据或自行批准发布。
• 目标：命令可报告差异与失败，生成物与唯一输入一致。
• 合同依据：工程工具。

工具/环境预检.py

• 归属与种类：工程；源码。
• 意图：在工程阶段执行 安装包、连接和宿主能力核查。
• 职责：安装包、连接和宿主能力核查。
• 边界：只处理声明的生成、索引或预检；不改变业务数据或自行批准发布。
• 目标：命令可报告差异与失败，生成物与唯一输入一致。
• 合同依据：工程工具。

部署/Dockerfile

• 归属与种类：部署；配置。
• 意图：将 从已核对发布目录安装固定后端、工作台与Pi镜像 固定为可检查入口。
• 职责：从已核对发布目录安装固定后端、工作台与Pi镜像。
• 边界：只构建、启动、停止或执行验证；不默认迁移作者数据或回显凭据。
• 目标：使用明确版本和连接配置，停机与验证结果可解释。
• 合同依据：交付配置。

部署/compose.yaml

• 归属与种类：部署；配置。
• 意图：将 HTTP、任务与隔离评测执行配置 固定为可检查入口。
• 职责：HTTP、任务与隔离评测执行配置。
• 边界：只构建、启动、停止或执行验证；不默认迁移作者数据或回显凭据。
• 目标：使用明确版本和连接配置，停机与验证结果可解释。
• 合同依据：交付配置。

部署/compose.test.yaml

• 归属与种类：部署；配置。
• 意图：将 隔离 PostgreSQL 和测试环境 固定为可检查入口。
• 职责：隔离 PostgreSQL 和测试环境。
• 边界：只构建、启动、停止或执行验证；不默认迁移作者数据或回显凭据。
• 目标：使用明确版本和连接配置，停机与验证结果可解释。
• 合同依据：交付配置。

部署/启动.sh

• 归属与种类：部署；配置。
• 意图：将 启动已配置进程 固定为可检查入口。
• 职责：启动已配置进程。
• 边界：只构建、启动、停止或执行验证；不默认迁移作者数据或回显凭据。
• 目标：使用明确版本和连接配置，停机与验证结果可解释。
• 合同依据：交付配置。

部署/停止.sh

• 归属与种类：部署；配置。
• 意图：将 优雅停止并保护正在执行的任务 固定为可检查入口。
• 职责：优雅停止并保护正在执行的任务。
• 边界：只构建、启动、停止或执行验证；不默认迁移作者数据或回显凭据。
• 目标：使用明确版本和连接配置，停机与验证结果可解释。
• 合同依据：交付配置。

.github/workflows/检查.yml

• 归属与种类：工程；配置。
• 意图：将 静态、契约、隔离测试和索引检查 固定为可检查入口。
• 职责：静态、契约、隔离测试和索引检查。
• 边界：只构建、启动、停止或执行验证；不默认迁移作者数据或回显凭据。
• 目标：使用明确版本和连接配置，停机与验证结果可解释。
• 合同依据：交付配置。

.github/workflows/构建.yml

• 归属与种类：工程；配置。
• 意图：将 资源、前后端打包与安装产物验证 固定为可检查入口。
• 职责：资源、前后端打包与安装产物验证。
• 边界：只构建、启动、停止或执行验证；不默认迁移作者数据或回显凭据。
• 目标：使用明确版本和连接配置，停机与验证结果可解释。
• 合同依据：交付配置。

配置/流程模板/生成规划.yaml

职责：受控规划的冻结、生成和候选保存保护流程。

合同依据：流程模板。机械范围与用例绑定见目标文件清单中同路径条目。

配置/流程模板/完整审校.yaml

职责：完整审校保护节点与judge步骤模板。

合同依据：流程模板。机械范围与用例绑定见目标文件清单中同路径条目。

配置/流程模板/执行评测-生成.yaml

• 归属与种类：编排；运行资源。
• 意图：逐例生成的固定保护节点与writer槽位。
• 职责：逐例生成的固定保护节点与writer槽位。
• 边界：仅引用已登记处理器和槽位；不能删除保护节点或运行任意脚本。
• 目标：发布版本可固定，所有合法路径保留适用前置与确认。
• 合同依据：流程模板。

配置/流程模板/执行评测-比较.yaml

• 归属与种类：编排；运行资源。
• 意图：独立成对比较的固定保护节点与judge槽位。
• 职责：独立成对比较的固定保护节点与judge槽位。
• 边界：仅引用已登记处理器和槽位；不能删除保护节点或运行任意脚本。
• 目标：发布版本可固定，所有合法路径保留适用前置与确认。
• 合同依据：流程模板。

配置/流程模板/执行评测-检测.yaml

• 意图：独立detector准备、发送与交付流程。
• 职责：独立detector准备、发送与交付流程。
• 边界：不写正式事实，不把检测回合当文学效果或生产启用证明。
• 目标：独立检测产物可从原调用和原文重新核验。
• 合同依据：模块设计/B10-效果评测.md；模块设计/B06-审校修订.md。

工具/构建发布.py

• 归属：工程。
• 职责：生成带哈希轮子、依赖和部署配置的独立发布目录。
• 边界：不默认迁移、启用或读取私人原文；失败返回可核对原因。
• 验证：真实安装、隔离PG和浏览器证据。

部署/应用.example.toml

• 归属：部署。
• 职责：无凭据值的生产用途配置示例。
• 边界：不默认迁移、启用或读取私人原文；失败返回可核对原因。
• 验证：真实安装、隔离PG和浏览器证据。

部署/部署.example.env

• 归属：部署。
• 职责：明确实例、镜像摘要和受控存储引用。
• 边界：不默认迁移、启用或读取私人原文；失败返回可核对原因。
• 验证：真实安装、隔离PG和浏览器证据。

部署/Pi/package.json

• 归属：部署。
• 职责：固定Pi宿主和Node版本。
• 边界：不默认迁移、启用或读取私人原文；失败返回可核对原因。
• 验证：真实安装、隔离PG和浏览器证据。

部署/Pi/package-lock.json

• 归属：部署。
• 职责：Pi运行依赖完整性锁。
• 边界：不默认迁移、启用或读取私人原文；失败返回可核对原因。
• 验证：真实安装、隔离PG和浏览器证据。