AGENTS.md@bedrock git:20261103.0de65eaA

Immutable. This exact content never changes and is served at /api/v1/blob/a7a9981f03933f05.

# 基岩版 Add-On — Agent 总纲

与 Java 模组 **零共享**：无 Gradle、无 Mixin、无 `query_api`、无 Yarn。规则编号 **不是** Java 的 DeferredRegister 系列。

打开含 `manifest.json`（`format_version` + `modules`）的包 → 本目录。

| 编号 | 文件 | 主题 |
|------|------|------|
| 00 | 工程目录 RP/BP（脚本在 BP 的 `scripts/` + manifest `script` 模块，不是第三种顶层包）、UUID、min_engine_version |
| 01 | manifest |
| 02 | 资源包 |
| 03 | 行为包 |
| 04 | 实体成对 |
| 05 | 方块/物品 JSON |
| 06 | Molang |
| 07 | Script API（实验开关分层） |
| 08 | 世界生成 JSON |
| 09 | 反模式 |
| 10 | 发布 mcpack |

文档：`search_bedrock_docs`（带 `docsStatus`）。`id` 必须来自搜索结果（如 `stable/custom-block`），不要用网站 URL 当 `get_bedrock_doc_full` 的 id。`diagnose_gradle` / `convert_mapping` / `query_api` / `mixin_analyze` / **`crash_analyze`（Java 向）** 必须拒绝并改口。content-log / `content_log.txt` 分诊用 **`analyze_bedrock_log`**，不要喂 Java 崩溃报告工具。

规则 00–10 在 `.cursor/rules/`（决策流 + 已核实 Learn 约束）。平台 Skill 在 `.cursor/skills/`；库 Skill 另见 `knowledge/libs/bedrock-only/`。禁止 CCA/Trinkets/GeckoLib。不要为本档新写 Java `mc-config`；基岩配置走 pack JSON / Script，不是 Cloth / ForgeConfigSpec。

### 本规则集的 IDE 加载优先级

| AI 助手 | 读取路径 |
|---------|---------|
| Cursor | `.cursor/rules/*.mdc` + `.cursor/skills/` |
| Claude Code | `.claude/rules/` + `.claude/skills/` + `.claude/agents/` + `.claude/commands/` |
| Continue | `.continue/rules/` + `.continue/skills/` |
| Trae | `.trae/rules/` + `.trae/skills/` + `.trae/agents/` |
| OpenCode | `.opencode/rules/` + `.opencode/skills/` |
| ZCode | `.zcode/rules/` + `.zcode/skills/` |
| DSH | `.agents/skills/` |
| Pi | `.pi/rules/*.md`（+ `AGENTS.md`） |

当上述路径不存在时，降级读取本文件和 `.cursor/`。

<!-- MC_SKILL_WORKFLOW_NOTE -->

## 工作流提醒（人在环）

完整流程（从零建工程 / 完整新内容 / 分诊 / 发布）才调 `get_workflow_template`；改已有代码、补方法、查文档走规则 + Skill，不要先调工作流。
- 写盘 / 拷贝文件 / Gradle 均须用户确认（人在环）。

## 工具参数面（W4-6，文档化）

调用基岩工具前先看清参数名 —— 这两个工具**都不吃** `--project` 这种工程路径形：

- `validate_addon_manifest`：吃 `manifestJson`（manifest.json 的**内容**，或配合 `projectPath` 由工具自己找包根），不是「传一个工程路径就自动全包校验」。
- `analyze_bedrock_log`：三选一 `logPath`（content_log.txt 绝对路径）/ `logsDir`（含 `content_log*.txt` 的目录）/ `projectPath`（自动找 `logs/`、`behavior_packs/logs/`、`worlds/logs/`）；可选 `maxLines`（默认 400，封顶 4000）/ `maxBytes`（默认 512KB，封顶 2MB）。
- 行格式：`[时间][级别][标签] 消息`；级别允许方括号或尖括号（`[Error]` / `<Error>`），时间戳允许 `YYYY-MM-DD HH:MM:SS`（毫秒用 `.` / `,` / `:` 分隔）或短 `HH:MM:SS`；时间戳与级别之间允许空格。
- 真机 `content_log.txt` 样例仓内仍缺（`test-fixtures/bedrock-content-log.txt` 是按上述形**合成**的回归样例）⇒ 需要真机样例时请用户提供。
- **BDS 真机取证（官方 BDS 1.21.102.1 / Windows）**：`server.properties` 设 `content-log-file-enabled=true` 后，服务器会打印
  「Content logging to disk is enabled. Writing log to: ContentLog<时间戳>」，但**实际不产出任何文件**
  （4 次起服验证：服务器目录全域、`%TEMP%`、`%APPDATA%`、`%LOCALAPPDATA%` 都没有；预建 `logs/` 也一样）。
  真机可得的内容错误只在**控制台**，行形是 `[YYYY-MM-DD HH:MM:SS:mmm LEVEL] msg`（级别与时间戳同处一方括号、无标签方括号），
  明细以**制表符缩进**跟在下一行 ⇒ 把控制台输出原样存成 `.txt` 交给 `analyze_bedrock_log --logPath` 即可（工具已支持该行形 + 缩进续行归并）。
  样例：`mcp-server/test-fixtures/bedrock-bds-console.txt`（Session ID 已脱敏）。

## 真机自测（BDS）

`bedrock/playtest/` 提供可复跑的基岩无头闭环：`run-bds-qa.mjs` + `qa-pack/`（脚本、方块、命令、动态属性）。
前置 = 自备官方 BDS（EULA 由使用者接受）+ `MC_SKILL_PLAYTEST_ALLOW=1` + `MC_SKILL_PLAYTEST_ROOT` + `MC_SKILL_BDS_DIR`；
用法、证据契约与 fail-closed 边界见 `bedrock/playtest/README.md`。

客户端渲染 / RP 外观 / GUI / 客户端 content log 走真客户端半自动路线：`bedrock/playtest/client/`（URI 直进世界 + 世界脚本摆场景 + PrintWindow 截图 + 退出时落盘的 content log）。实测边界见该页「已知边界」——鼠标注入被忽略、最小化只是起动更慢、命令通道的键盘端需前台焦点。