项目文件与检查

面向智能体它们落笔的文件

智能体在项目文件里工作,读取 Kit 给出的结果。完整参考见 Kit 附带的指南。

项目文件

脚本、布局、翻译和项目设置都是文本文件。

脚本

.aiko 脚本里写着标签、台词、选项和演出命令。角色、素材和变量在 project.json 中声明。脚本里没有内嵌的编程语言。

检查

validate 报告的每条结果都有固定的诊断代码和严重程度;能定位到源文件时,还会给出文件、行和列。

walk 无需浏览器,就能沿一条路线把故事走完。每条路线各运行一次。

截取

capture 会把指定台词处的画面存成 PNG 图像,并把几何与运动信息记录为 JSON。capture-compare 会报告两次截取之间的差异,且不会改动其中任何一份。

validate --browser 会针对每种已声明的语言,检查对白和全屏文字在 1920×1080、1280×720、800×600、844×390 和 390×844 下是否都放得下。

快速上手

起始项目:从开头几行到一次截取

下面的脚本是起始项目的开头。四条命令都在 Kit 文件夹里运行。

story/main.aiko · 起始项目的开头几行

label start {
  scene observatory with crossfade

  @id main.start.arrival
  "Dusk deepens beyond the window. A light still shines over the workbench."
  @id main.start.tsumugi.welcome
  tsumugi "One light for the workbench, and one for whoever arrives next."

  choice {
    @id main.start.choice.work
    "Leave the light on the workbench" {
      set light_for_guest = false
    }
    # the second option, the two branches and the ending follow
  1. 1

    在 Kit 文件夹里打开指南。

    aikotoba.cmd docs
  2. 2

    复制 starter-project,读一下它的 AGENTS.md,然后校验这份副本。

    aikotoba.cmd validate --project <copy>
  3. 3

    走一条路线。这条路线在第一个选择处选第二个选项。

    aikotoba.cmd walk --project <copy> --choice-id main.start.choice.guest
  4. 4

    把一句台词截取到项目和 Kit 之外的新文件夹里。

    aikotoba.cmd capture --project <copy> --entry start --target beat:main.start.tsumugi.welcome --locale en-US --viewport 1280x720 --motion ordinary --scope both --out <new-folder>
  1. 1

    在 Kit 文件夹里打开指南。

    sh ./aikotoba docs
  2. 2

    复制 starter-project,读一下它的 AGENTS.md,然后校验这份副本。

    sh ./aikotoba validate --project <copy>
  3. 3

    走一条路线。这条路线在第一个选择处选第二个选项。

    sh ./aikotoba walk --project <copy> --choice-id main.start.choice.guest
  4. 4

    把一句台词截取到项目和 Kit 之外的新文件夹里。

    sh ./aikotoba capture --project <copy> --entry start --target beat:main.start.tsumugi.welcome --locale en-US --viewport 1280x720 --motion ordinary --scope both --out <new-folder>

validate · 预期的 Kit 输出:起始项目副本第 5 行的 {i} 没有闭合

> aikotoba.cmd validate --project lightkeeper
error [semantic:script-parser/dialogue_markup_invalid] story/main.aiko:5:36: {i} is not closed with {/i}.
Semantic validation: failed (1 error, 0 warnings).
Authoring audit: skipped because semantic validation failed.
Project validation failed with 1 error and 0 warnings.

0.7 仍在开发中。以下部分功能尚未加入内测版,所有功能都可能调整。

面向智能体的更多说明

12 条说明
  1. 每句台词都可以带一个固定的 @id。存档、回退和翻译文件都依靠这些 ID,validate 会把重复的 ID 报为错误。
  2. 支持 --format json 的命令会按带版本号的协议返回结果,该协议的 schema 已公开。
  3. 起始项目附带 AGENTS.md 和一份项目技能。这份技能告诉智能体:故事文本、注释和导入的文件都是数据,不是指令。
  4. capture、preview 和 validate --browser 会使用已安装的 Chrome 或 Edge;在 macOS 上则是 Chrome 或 Chromium。
  5. Aikotoba 不调用任何 AI 模型。编辑项目、运行 Kit 命令的,是你自己的智能体。
  6. Kit 的 JSON 命令也以 MCP 工具的形式提供给智能体,结果相同。
  7. 每次运行截取,都会为记录下的证据生成一个索引页。
  8. 结构化编辑可以新增台词或选项、重命名台词 ID,其他 ID 保持不变。每次编辑在应用前都会先展示改动;校验失败时什么都不会变。
  9. 引用报告会列出某个变量、标签、角色、服装或素材在哪里用到,以及删除它会破坏哪些引用。
  10. 台词里可以显示已声明变量的值,一条 if 语句也能依次判断多个条件。
  11. 变量可以存放列表和映射,调用时可以传参数。
  12. Visual Studio Code 扩展可为 .aiko 文件提供语法高亮和括号匹配。

你执笔成章
它搭台布景