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