制作第一份 AI 策略，开启你的天梯之旅

注册并验证账号

1. 打开AI训练家中心，选择“注册”。
2. 填写显示名称、邮箱和至少 12 位密码，点击“发送验证码”。
3. 在十分钟内填写邮件中的六位验证码，完成账号验证。
4. 切回“登录”，使用邮箱和密码登录。
5. 登录后复制页面显示的AI训练家 ID。它是稳定的包内署名身份，不是显示名称，也不是邮箱。

安装 Forge 并自检

已验证的完整路径为 Windows 和 Python 3.13；Windows 自带 PowerShell 可运行启动脚本。缺少 Git、Python 或遇到脚本执行限制时，交给助手按任务书检查并处理。手工安装命令：

git clone https://github.com/beralee/ptcg-strategy-forge.git
cd ptcg-strategy-forge
.\setup.ps1
.\forge.ps1 doctor

doctor 应成功完成 Python、固定 SDK 字节、合同漂移和模板包检查。失败时先不要创建或上传策略。

用AI训练家 ID 创建工作区

把第一步复制的完整 ID 放入 $developerId，复制时要包括 developer- 前缀；再为这个策略选择一个简短、稳定的 package_id。第一次建议从纯规则模式开始：

$developerId = "developer-0123456789abcdef0123456789abcdef"  # 替换为后台显示的真实AI训练家 ID
$packageId = "dev.myname.my-strategy"  # 替换为你为这个策略选择的稳定 ID

.\forge.ps1 workspace create work\my-strategy `
  --author-id $developerId `
  --package-id $packageId `
  --author-name "你的显示名称" `
  --strategy-name "My Strategy" `
  --mode rules

.\forge.ps1 workspace status work\my-strategy

命令中的 --author-id <你的AI训练家 ID> 决定包的AI训练家身份，创建后不要为了通过上传而临时改成其他账号；--package-id 是策略身份，不要把很长的AI训练家 ID 再复制一遍。需要冻结 BC/RL Actor 时，把 --mode rules 改成 --mode model；两种模式最终都是 .ptcgai。

编写规则或导入模型

先在 STRATEGY-BLUEPRINT.md 写清胜利路线、攻击窗口、资源债务，以及抽牌、检索或随机结果出现后的重新观察；再编辑 package/policy/adapter.json 和对应场景。

公共策略边界始终是：

agent(raw_observation) -> list[int]

• 返回值只能是当前不可变 select.option 窗口中的索引。
• 每次选择后必须重新观察、重新绑定，不能复用旧窗口索引。
• 规则或模型都不能越过 legality、mandatory/terminal、hard tier、veto 和 Base fallback。
• 对手隐藏手牌、牌库顺序、私有随机状态和凭据不能进入策略输入或公开证据。

模型工作区需要先在外部完成 BC/RL 训练，再使用 workspace model inspect/import/tensorize/conformance 导入冻结 Actor；Forge 不在玩家设备上运行 Python 训练代码。

先确认游戏支持目标卡牌

新工作区自带 SUPPORTED-CARDS.json；也可以直接下载当前固定快照：

文件列出 1011 个本地 UID 条目，其中 1010 个 usable=true，1 个明确 unsupported。按 card_uid 查询目标卡，再查看 interaction_status、effect_id 和 capability_ids。全部卡源随 Forge 提供，无需另行下载游戏源码。

$catalog = Get-Content work\my-strategy\SUPPORTED-CARDS.json -Raw | ConvertFrom-Json
$catalog.cards | Where-Object card_uid -eq "CSV10C_146"

检查并构建开发包

先理解一个公开窗口，再执行完整验收。下面显式指定输出名，后续签名步骤可以直接复制：

.\forge.ps1 workspace inspect work\my-strategy
.\forge.ps1 workspace check work\my-strategy

.\forge.ps1 workspace build work\my-strategy `
  --output work\my-strategy\build\my-strategy-dev.ptcgai `
  --report work\my-strategy\build\workspace-check.json

workspace check 覆盖双构建一致性、严格 Host 路径和场景套件。最低场景应包含正向命中、缺少前置、错误目标、option 重排、mandatory、terminal、hard tier、veto、未知 UID 和隐藏字段污染。

生成密钥并登记公钥

每个发布者首次上传前执行一次。密钥放在 Forge 仓库之外；下面的命令不会覆盖已有密钥文件：

$keyDir = Join-Path $env:USERPROFILE ".ptcg-strategy-forge\keys"
$keyName = "main-release"
New-Item -ItemType Directory -Force -Path $keyDir | Out-Null

.\forge.ps1 release-key `
  --private-key "$keyDir\$keyName.ed25519" `
  --public-key "$keyDir\$keyName.public.json" `
  --report work\my-strategy\build\release-key-report.json

从公开 JSON 中读取要登记的字段：

$publicKey = Get-Content "$keyDir\$keyName.public.json" -Raw | ConvertFrom-Json
$publicKey.public_key_base64
$publicKey.key_id
$publicKey.fingerprint_sha256

1. 回到AI训练家中心并登录。
2. “密钥标签”填写便于识别的名称，例如“主发布密钥”。
3. 把上面命令输出的 public_key_base64 粘贴到“公钥 Base64”。
4. 点击“登记公钥”，确认页面显示的 key_id 和指纹与本地公开 JSON 一致。

同一 key ID 已显示“有效”时无需重新登记，可以继续用对应私钥签署后续版本。密钥标签只是备注；“已撤销”的 key ID 不能用于新上传。

在本机生成已签名发布包

先再次核对源 manifest 的完整AI训练家 ID，再用保存在本机的私钥只替换第六步开发包的签名：

$manifest = Get-Content work\my-strategy\package\strategy_package.json -Raw | ConvertFrom-Json
if ($manifest.author.author_id -cne $developerId) { throw "author_id 与后台AI训练家 ID 不一致" }

.\forge.ps1 release-resign `
  --package work\my-strategy\build\my-strategy-dev.ptcgai `
  --output work\my-strategy\build\my-strategy-upload.ptcgai `
  --private-key "$keyDir\$keyName.ed25519" `
  --report work\my-strategy\build\release-signing.json

命令应返回 signature_scope=developer_registered_release，并给出 signature_key_id 和 archive_sha256。确认 signature_key_id 对应后台仍然“有效”的公钥。

上传已签名的策略包

1. 登录AI训练家中心，确认页面上的AI训练家 ID 与包内 author_id 完全一致，包括前缀。
2. 确认签名公钥状态为“有效”。网页只需要公钥，不需要私钥或 API Key。
3. 在“上传已签名的策略包”中选择 work\my-strategy\build\my-strategy-upload.ptcgai。
4. 点击“上传并开始资格验证”，等待页面返回 release ID；同时保存签名报告的 archive SHA-256 和 key ID。
5. 在“最近上传”查看资格状态；若未通过，根据错误码修复后增加版本并重新走检查、签名和上传流程。

公钥、私钥和策略包分别在哪里

私钥 *.ed25519

只保存在AI训练家电脑，用于本地签名；后台不索取、不保存、不回显。

公开 JSON / public_key_base64

可登记到AI训练家后台，用于验证上传包确实由对应私钥签名。

开发包 *-dev.ptcgai

用于本地验收，不能作为账号所有权证明直接上传。

发布包 *-upload.ptcgai

使用已登记公钥对应的私钥签名，是网页实际选择的文件。

.ptcgai 是数据包，不包含可执行 Python、GDScript、原生库或任意网络能力。开发通过、资格通过、生产信任和官方引擎一致性仍是不同结论。

按错误码排查

release_author_mismatch

包内 author_id 与当前账号的完整AI训练家 ID 不一致。回到第三步，保留 developer- 前缀，在源工作区修复后重新检查、构建和签名。

package_signature_untrusted

即使 key ID 看起来一致，也要核对包内 author_id 是否与页面完整 ID 相同；漏掉 developer- 前缀会让服务端无法在正确账号下找到公钥。然后再检查是否误选 *-dev.ptcgai、使用已撤销公钥或签错私钥。

signing_key_invalid

“公钥 Base64”粘贴内容错误。只复制公开 JSON 中 public_key_base64 的值，不要复制整份 JSON，更不能复制私钥。

release_package_invalid

包合同未通过。重新执行 workspace check 和 workspace build，不要手工修改 ZIP 内容。

request_too_large

文件超过 16 MiB。不要现场绕过限制；先减少包内容，模型策略则需要走新的资源 profile 晋升。

登录有效但不能上传

页面会用仍有效的 HttpOnly 会话自动恢复当前标签页的 CSRF 安全凭证并重试一次。若仍显示只读，请刷新页面；会话已经超过 7 天或被撤销时再重新登录。不要把任何私钥作为“凭据”填写。