[WIP] feat: restructure project template layout

[Craun718]

Pull Request

关联 Issue

Related #47

变更摘要

• 将 interface.json、任务配置、资源目录和 Schema 文件迁移到与 create-maa-project 一致的布局
• 调整 Agent 自定义逻辑为 agent/custom/ 包结构，并更新安装、校验脚本、工作流与文档
• 新增 TypeScript 配置和 typecheck 脚本，修复 import.meta.dirname 的类型检查问题

验证

• 执行 npm run typecheck，通过
• 执行 git diff --check，通过
• 我已阅读并遵守 PR 规范

截图 / 日志 / 说明

本 PR 主要调整模板目录结构，不涉及界面变化。

Sourcery 总结

围绕标准布局重构项目模板，并相应更新其工具链、自动化流程、智能体组织方式和文档。

增强功能：

• 通过将接口定义、任务、基础资源、架构以及自定义智能体代码移动到规范位置，使项目模板与标准布局保持一致。
• 更新安装、架构验证、配置、工作流和文档，以适配新的项目结构。
• 将自定义智能体操作和识别器组织到一个包中，并集中进行注册。

构建：

• 添加 TypeScript 配置和类型检查脚本，用于验证 Maa 工具配置。

持续集成：

• 针对重构后的目录更新工作流触发条件、架构同步、验证和发布打包流程。

文档：

• 记录新的项目目录布局，并更新开发和贡献指南，以引用移动后的文件。

Original summary in English

Sourcery 摘要

围绕标准 Maa 项目布局重构项目模板，并相应更新 Agent 工具、验证、自动化、打包和文档。

新功能：

• 添加标准化项目模板布局，包括根目录级接口定义、任务配置、资源包、模式以及打包后的 Agent 代码。
• 提供自动化 OCR 设置、模式同步与验证、图像优化、格式化和开发检查。
• 引入结构化的自定义 Agent 动作、识别、实用工具、日志记录和运行时环境支持。

增强：

• 使安装、验证、发布打包、格式化和运行时工作流与新的项目结构保持一致。
• 将问题报告和贡献指南整合为双语模板，并更新开发文档。

构建：

• 采用基于 pnpm 和 uv 的 Node.js/Python 工具链，并固定运行时版本，配置依赖管理、格式化、代码检查和严格的 Python 类型检查。

CI：

• 更新检查、安装、模式、格式化、图像优化和发布工作流，以适配标准化布局和自动化维护任务。

部署：

• 更新资源安装和发布打包流程，以包含重新定位后的任务和资源目录。

文档：

• 记录标准化目录布局、新的开发命令、资源设置、验证要求和贡献流程。

测试：

• 在项目验证命令和 CI 中添加模式验证与 MaaFramework 配置检查。

杂项：

• 用新的资源、模式、pnpm lockfile 和 uv lockfile 组织结构，替换之前基于 assets/deps 和 package-lock 的结构。

Original summary in English

Summary by Sourcery

Restructure the project template around the standard Maa project layout and update its Agent tooling, validation, automation, packaging, and documentation accordingly.

New Features:

• Add a standardized project template layout with root-level interface definitions, task configurations, resource packs, schemas, and packaged Agent code.
• Provide automated OCR setup, schema synchronization and validation, image optimization, formatting, and development checks.
• Introduce structured custom Agent action, recognition, utility, logging, and runtime environment support.

Enhancements:

• Align installation, validation, release packaging, formatting, and runtime workflows with the new project structure.
• Consolidate issue reporting and contribution guidance into bilingual templates and updated development documentation.

Build:

• Adopt pnpm and uv-based Node.js/Python tooling with pinned runtime versions, dependency configuration, formatting, linting, and strict Python type checking.

CI:

• Update check, installation, schema, formatting, image optimization, and release workflows for the standardized layout and automated maintenance tasks.

Deployment:

• Update resource installation and release packaging to include the relocated tasks and resource directories.

Documentation:

• Document the standardized directory layout, new development commands, resource setup, validation requirements, and contribution process.

Tests:

• Add schema validation and MaaFramework configuration checks to the project verification commands and CI.

Chores:

• Replace the previous assets/deps and package-lock-based structure with the new resource, schema, pnpm lockfile, and uv lockfile organization.

[sourcery-ai]

你好——我已经审阅了你的更改，看起来很棒！

---

Sourcery 对开源项目免费——如果你喜欢我们的审查结果，请考虑分享它们 ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{帮助我变得更有用！请在每条评论上点击 👍 或 👎，我会利用这些反馈来改进审查结果。}

Original comment in English

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[MistEO]

我感觉应该反过来对齐，因为用模板的人更多

[Craun718]

我感觉还是新的好，旧的在install过程中动态修改interface有点反直觉了（

[Craun718]

我感觉应该反过来对齐，因为用模板的人更多

目前模板没有agent打包示例，每次新人打包后agent起不来都要解释interface位置变更，感觉好麻烦。

[Windsland52]

create-maa-project是基于长期开发和解答问题的经验调整的结构，另外create-maa-project实现了组件化，尽可能的将实际开发通用的部分搞好了，会更通用便捷

[Windsland52]

目前跟create-maa-project生成的项目差别有点大

[Windsland52]

光从生成的项目的结构来说大概有以下差别：

cmp 生成项目 vs 官方模板：结构层面的优势

一句话框架：官方模板的结构是“给人看的快照”，cmp 的结构是“给人和工具一起用的骨架”。具体拆开是九处：

1. 根布局：业务置根，消灭路径换算层

cmp:  interface.json / resource/ / tasks/ / agent/ 都在根
官方: assets/interface.json + assets/resource/，agent/ 却在根

官方布局下，同一个 agent 项目的 child_exec 路径在仓库里（interface 在 assets/ 内）和发布包里（摊平后同级）必然不一致，开发和发布必有一边要手改路径。cmp 源码路径 = 发布路径，这个隐式坑从结构上不存在。

2. interface v2 import 拆分

cmp 的 task 清单独立成 tasks/tutorial.json（受 interface_import.schema.json 校验），interface.json 只留骨架；官方把 task/option 全部内联在 interface.json 里，任务一多就膨胀。拆分还让 UI 定义和 pipeline 业务各归各的 schema 管辖。

3. resource 按资源包 profile 组织

resource/base/{default_pipeline.json, pipeline/, image/, model/}——资源包是一等结构单元，加官服/B服就是加一个 profile 目录 + maa-project.json 一行；官方是 assets/resource/ 扁平单资源，注释里暗示你加 B 服得自己造 resource_bilibili 并手改 interface。另外 cmp 有 default_pipeline.json 落点，官方没有。

4. agent 是工程包，不是三个示例文件

cmp：bootstrap.py（依赖自举）+ agent_runtime + custom/{action,reco,sink}/ 分层 + 6 个 utils + __init__ 包结构，配套 pyproject.toml/uv.lock/requirements.in+txt/.python-version。开发用 uv，发布自动切内嵌 Python。官方：main.py/my_action.py/my_reco.py 平铺三个文件，依赖无清单、无版本管理，写大了必乱。

5. schema 的位置和覆盖面

cmp 放 tools/schema/，6 份 schema 外加 schema-manifest.json（schema-sync CI 的锚点），而且多出官方没有的 custom.action / custom.recognition 两份自定义逻辑 schema；.vscode 的 fileMatch 把 interface、tasks/*.json、resource/*/pipeline/** 三层全部挂上校验。官方放在 deps/tools/——和二进制依赖目录混在一起，且无 manifest、无自定义 schema。

6. 工具栈不越界

cmp 纯 pipeline 项目的工具全是 Node（tools/*.mjs + package.json + pnpm-workspace），Python 只在 agent 项目出现；官方纯 pipeline 项目也拖着 tools/*.py + requirements.txt。且 cmp 的工具本地可跑（ajv 校验、build-release dry-run），官方 install.py 是为 CI 设计的。

7. maa-project.json：机器可读的项目意图（独有文件）

资源包顺序、runtime 启用状态、add-on 装配记录都结构化落盘。官方模板没有任何对应物——它是“快照”和“可维护骨架”的结构分水岭：有它，--add/--sync/--update/--doctor 才有锚点。

8. .vscode 七份配置 vs 两份

cmp 含 tasks/launch/settings/extensions 各自的 pipeline 版 + .agent 变体版：打开目录自动 pnpm install/uv sync、debugpy 直调 agent。官方只有 extensions + settings 两份、仅 schema 关联。

9. 生成文件已按项目实例化

workflow、cliff.toml、dependabot（agent 项目自动加 uv ecosystem）、双语 issue 模板（单套中英合排，官方是中英各一套共 6 个文件）生成时就是这个项目的配置，不占用户定制成本。小细节：官方 package-lock.json 和 pnpm-lock.yaml 双锁并存，是模板自身的结构瑕疵。

收尾：这九处归结起来是三个结构性决策——业务置根让开发即发布、profile 化让结构可生长、元数据落盘让工具可持续读写。官方模板在这三点上要么没做，要么做了但把成本转嫁给了用户。

[Craun718]

cmp目前尚未稳定，工作流也接近完全重置。考虑到cmp工作流的部分流程实现较为复杂，社区对相关流程并不熟悉，加上对应的文档缺失内容也较多，我们很难对新人的疑惑进行解答。

故考虑先暂时回退部分修改，等到cmp相关内容完善之后再议。

[MistEO]

我知道新的好，但会带来很多“兼容性问题”。

比如新人开发者听说 MaaEnd 中某个脚本很方便开发，结果抄了一份发现自己项目完全用不了。新人想学习一下某个项目的经验，结果发现和自己的模板完全不一样，根本没法学习。这些都是要考虑的点，不能只单纯看“新的好还是旧的好”