Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -343,7 +343,7 @@ Maker 本地开发的默认路径是 CLI-first + PAT-first:
- Maker 鉴权文件必须沿用线上已发布版本的原始本地保存路径,不要为 production 或 rnd 新建环境子目录;不要在用户文档或普通用户说明里暴露具体凭证缓存路径。
- 用户可运行 `taptap-maker login` 主动刷新当前环境鉴权;`taptap-maker init` 和无参数 `taptap-maker pat set` 缺 PAT 时也走 CLI 登录。兼容写法 `taptap-maker pat set <PAT>`、`--pat PAT` 或 `--pat-stdin` 仅用于 CI / 应急联调,其中 argv 形式会让 PAT 进入 `ps`/shell history。
- 本地研发环境配置只作为内部开发能力处理:CLI/MCP 按当前环境使用对应配置,显式 `--env` 或 `TAPTAP_MCP_ENV` 优先;项目目录级配置只读取 `.maker/taptap-maker.local.json`,不读取项目根目录散落的本地配置文件;不要把内部研发配置写入面向用户的 README/使用文档。
- `taptap-maker init` 会检查 Git、Python 环境、maker-lua-lsp 本地 Lua 诊断环境、PAT、TapTap token、当前目录绑定状态、app 列表、AI dev kit,并在用户选择 app 后先记录 `.maker-mcp/config.json`,再 checkout 到当前目录;Python 未就绪时会自动尝试准备,最多 3 次,仍失败则暂停 init 且不继续 PAT、app、clone 或 MCP 配置;Python ready 后会 best-effort 创建 Maker 私有 LSP venv,在其中安装/升级 `maker-lua-lsp` 并执行 `maker-lua-lsp install --ide codex,cursor,claude`,LSP 失败只提示错误且不阻塞远端构建。clone/fetch 失败后重复执行 init 会复用已记录 app,显式选择不同 app 会拒绝覆盖已有绑定。app 文本预览默认展示前 40 个;账号 app 很多时在 init 交互中输入 `all` 一次性展开全部,或单独跑 `taptap-maker apps --all`;`taptap-maker apps --json` 仅给 AI / 脚本解析使用。AI 转述时宽屏可用两列紧凑布局,窄屏保持单列;每个 app 保留 app_id,并在用户确认后选择 app。
- `taptap-maker init` 会检查 Git、Python 环境、maker-lua-lsp 本地 Lua 诊断环境、PAT、TapTap token、当前目录绑定状态、app 列表、AI dev kit,并在用户选择 app 或创建新 Maker 项目后先记录 `.maker-mcp/config.json`,再 checkout 到当前目录;Python 未就绪时会自动尝试准备,最多 3 次,仍失败则暂停 init 且不继续 PAT、app、clone 或 MCP 配置;Python ready 后会 best-effort 创建 Maker 私有 LSP venv,在其中安装/升级 `maker-lua-lsp` 并执行 `maker-lua-lsp install --ide codex,cursor,claude`,LSP 失败只提示错误且不阻塞远端构建。clone/fetch 失败后重复执行 init 会复用已记录 app,显式选择不同 app 会拒绝覆盖已有绑定。app 文本预览默认展示前 40 个;创建新项目入口 `0. Create a new Maker project` 不参与裁剪,始终在列表底部显示;账号 app 很多时在 init 交互中输入 `all` 一次性展开全部,或单独跑 `taptap-maker apps --all`;`taptap-maker apps --json` 仅给 AI / 脚本解析使用。AI 转述时宽屏可用两列紧凑布局,窄屏保持单列;每个 app 保留 app_id,并在用户确认后选择 app;如需新建项目,可让用户在 init 中选择 `0`/`new` 并输入项目名称,或使用 `taptap-maker init --create --name "my-local-game"`;当前目录已绑定 Maker 项目时,必须切换到新的独立目录后再创建新项目
- AI dev kit 安装/更新按当前环境查询最新版本信息,按返回的 `current.version` 生成版本化下载 URL;版本检查失败时降级使用内置默认下载地址。安装成功后记录本地已安装版本,`taptap-maker doctor`、`maker://status` 和 `maker_status_lite` 输出当前版本、最新版本和是否可更新。
- `taptap-maker init` 首次拉取默认使用 `git init` + `git fetch --depth=1 origin` + checkout;Git clone/fetch 会按错误内容判断是否自动重试:503、HTTP 5xx、超时、连接重置、RPC/HTTP2 中断等远端临时错误会重试;认证、权限、仓库不存在、远端拒绝和本地目录冲突不重试。
- 首次 clone/fetch 前必须提示用户:Maker server 可能正在准备仓库,首次拉代码 20 秒以上是正常现象,请保持当前命令运行。
Expand Down
26 changes: 20 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ npx -y @taptap/maker init
```

CLI 负责一次性流程:Git 检查、Python 和 maker-lua-lsp 本地 Lua 诊断环境检查、CLI 登录、
TapTap token 换取、app 列表选择、Maker Git clone、AI dev kit 准备、MCP 配置写入与基础验证。Python 环境准备连续 3 次失败时,
TapTap token 换取、app 列表选择或新建 Maker 项目、Maker Git clone、AI dev kit 准备、MCP 配置写入与基础验证。Python 环境准备连续 3 次失败时,
初始化会暂停在登录、项目拉取和 MCP 配置之前;修复后重新运行 `taptap-maker init`。安装或修改 MCP 配置后,Claude Code /
Codex / Cursor 通常需要重启会话、刷新 MCP 或新开窗口才会出现新的 MCP tools;但当前终端
里的 CLI 初始化流程可以继续完成到 PAT 鉴权和项目绑定。
Expand All @@ -65,14 +65,25 @@ taptap-maker login
taptap-maker doctor
taptap-maker apps --json
taptap-maker install --ide codex,cursor,claude
taptap-maker agents update
taptap-maker upgrade
taptap-maker mcp verify
taptap-maker dev-kit update
```

如果需要创建新 Maker 项目,仍从 `taptap-maker init` 进入。app 列表底部会固定显示
`0. Create a new Maker project`,输入 `0` 或 `new` 后填写项目名称;自动化场景可用
`taptap-maker init --create --name "my-local-game"`。当前目录已绑定 Maker 项目时,不允许在同一目录
创建并覆盖绑定;请先切到一个新的独立目录再运行 `taptap-maker init`。

`taptap-maker login` 是 CLI 登录入口;它会按需打开 Maker 授权页,CLI 轮询授权结果并完成本地鉴权配置。
`taptap-maker init` 缺 PAT 时会自动进入该流程。`taptap-maker pat set` 保留为兼容入口;
自动化场景可用 `--pat-stdin` 从标准输入读取。`taptap-maker install` 是
`taptap-maker mcp install` 的快捷别名,二者都会写入 AI 客户端 MCP 配置。
`taptap-maker upgrade` 会刷新当前机器的 Maker MCP 配置,并在当前目录已绑定 Maker 项目时
同步项目 `AGENTS.md` 的 TapTap Maker 受管策略块。`maker://status`、`maker_status_lite`
和 `taptap-maker doctor` 会检查老项目 `AGENTS.md` 是否缺失或过期,并提示运行
`taptap-maker agents update` 或 `taptap-maker upgrade`。
`taptap-maker dev-kit update` 会检查当前环境可用的最新 AI dev kit 并更新当前目录。

Maker MCP 精简为开发循环里的高频能力:
Expand All @@ -97,9 +108,10 @@ Maker 远端但构建失败。只有用户明确说“不提交,只构建云
`runtime_logs.local_file`;如需判断 watcher 是否正常,读取 `runtime_logs.state_file`。

Maker MCP 也提供部分生成类能力,当前包括 `generate_image`、`batch_generate_images`、
`edit_image`、`create_video_task`、`query_video_task` 和 `text_to_music`;具体参数以 MCP
客户端展示的 tool schema 为准。已绑定 Maker 项目中建议优先使用这些 proxy tools;代理转发、
错误透出和白名单细节见 [TapTap Maker 本地开发](docs/MAKER.md)。
`edit_image`、`create_video_task`、`query_video_task`、`text_to_music`、
`create_3d_model_task` 和 `query_3d_model_task`;具体参数以 MCP 客户端展示的 tool schema 为准。
已绑定 Maker 项目中建议优先使用这些 proxy tools;代理转发、错误透出和白名单细节见
[TapTap Maker 本地开发](docs/MAKER.md)。

Windows 是默认优先级:CLI 写 MCP 配置时会在 Windows 通过 `cmd.exe` 包装 `npx.cmd`,
避免无 shell 的 MCP 启动器直接 spawn `.cmd` 失败;Git 引导优先提示 Git for Windows,
Expand Down Expand Up @@ -341,7 +353,7 @@ npm test

### Maker 本地开发预览

Maker 本地开发现在以 CLI-first 为准。初始化、PAT、app 选择、dev-kit 和 clone 都走 CLI;MCP 只保留状态和同步构建:
Maker 本地开发现在以 CLI-first 为准。初始化、PAT、app 选择/创建、dev-kit 和 clone 都走 CLI;MCP 只保留状态和同步构建:

```text
taptap-maker init
Expand All @@ -357,7 +369,9 @@ maker_build_current_directory
`taptap-maker mcp verify` 默认跑一次实际 MCP 配置使用的 npx 包命令;本地 dist 自测可用 `--mode self`。如果失败结果显示 `failure_type` 或 `status: null`,优先按本地 Node/npm/npx 启动问题处理,Maker MCP server 此时尚未启动,不要误判为 PAT 或 Maker 服务报错。

测试时优先运行 `taptap-maker login`;CLI 会按需打开 Maker 授权页,授权完成后自动完成本地鉴权配置。
当前目录未绑定时,APP_ID 应通过 `taptap-maker init` 或 `taptap-maker apps` 返回的 app 列表让用户选择;当前目录已绑定时不要再次引导 clone。
当前目录未绑定时,APP_ID 应通过 `taptap-maker init` 或 `taptap-maker apps` 返回的 app 列表让用户选择;
创建新项目时使用 `taptap-maker init` 列表底部的 `0. Create a new Maker project`,或运行
`taptap-maker init --create --name "my-local-game"`;当前目录已绑定时不要再次引导 clone 或创建新项目。

```bash
npm run build
Expand Down
Loading
Loading