ait-native

本地快速上手

从一个小任务，走到可验收的结果。

先用没有第三方依赖的任务清单示例试跑，再把同一套流程带进自己的仓库。

试跑示例使用自己的仓库

推荐的跨平台方式

从 PyPI 安装

Wheel 支持 macOS、Linux 与 Windows。Python 负责安装软件包；ait 工作流本身是原生程序。

python -m pip install ait-native
改用 Homebrew、npm、apt 或发布归档

Homebrew · macOS 与 Linux

brew tap weita2026/ait-native
brew install ait-native

安装 ait 和默认不启动的 ait-server。

npm · 直接的 Node.js API

npm install --global @wa120/ait-native

安装 JS/TS API、Node-API 插件与在进程内运行的 ait 命令，不含服务器。

apt · Debian 与 Ubuntu

# 先添加已签名的 stable 软件源
sudo apt install ait-native

1.1.1 支持 amd64 与 arm64。设置软件源。

AIT · 1.1.1

第一个 Task，有明确结果可以检查。

先完成上方的 AIT 安装，再用新文件夹试跑。此示例需要 Node.js 22 或更新版本，以及你自己的 coding agent。Node.js 只是示例的要求；agent 可能使用你的模型供应商账户。

下载示例 ZIP核对 SHA-256

  1. 1. 解压缩，确认起点

    用文件管理器解压缩 ZIP，在解出的 ait-first-task 文件夹打开终端。起始的三项测试应全部通过，不需要执行 npm install。

    node --version
node --test tests/baseline.test.mjs

  2. 2. 初始化示例

    在这里执行 ait init，再用 coding agent 打开此文件夹。先请它阅读生成的 AGENTS.md，再开始工作。

    将“你的名称”替换成你要记录在本地 Task 审查中的名称。下方初始 Snapshot 会在任何 Task 启动前记录未修改的示例；这段准备只用于全新示例文件夹。

    ait init
ait config set --user-name "你的名称"
ait snapshot create --message "Start the AIT example"
    查看初始化会修改的内容 →

  3. 3. 把这个需求交给 agent

    阅读 AGENTS.md，按这个仓库的 AIT 工作流完成任务。在 src/tasks.mjs 新增 openTasks(tasks)：返回一个新数组，保留 done 不为 true 的任务、原始顺序与任务对象，不修改输入。保持 taskTitles 的现有行为，补充针对性测试。不要修改 checks/、移除现有测试或新增依赖。完成 Task 前，执行现有测试与 node checks/first-task.mjs。

  4. 4. 回原始文件夹验收

    agent 报告 Task finish 后，回到原始解压缩文件夹执行以下两项检查。功能尚未实现前，验收检查预期会失败。

    node --test tests/*.test.mjs
node checks/first-task.mjs

    功能用例通过时会打印 FIRST_TASK_ACCEPTED。也请检查实际 Task finish 结果：Task 已完成、工作区已清理，且适用的绑定 sprint 项目已关闭。功能验收与工作流完成要分别确认。

遇到问题怎么办

如果找不到 node 或 ait，先完成对应安装。若 agent 没读 AGENTS.md，在已初始化的文件夹开新对话，请它先读取该文件。检查失败时，将结果交回同一个 Task，保留检查并修复功能。冲突需要解决并重新检查，才能完成工作。

下一步：试跑三个兼容的并行 Task

使用全新解压缩的示例并初始化。在这个仓库开三个独立 agent 对话，分别交办一个需求；每个都要遵循 AGENTS.md、绑定自己的 sprint 项目，只在返回的 edit_root 内工作，保留 checks/ 与现有测试，使用不同测试文件。需求 A 就是上方第一个需求。

打开三个对话前，请重复上方完整初始化步骤，包括初始 Snapshot。

需求 B：在 src/labels.mjs 新增 taskCountLabel(count)，输入为非负整数。1 返回 "1 task"，其他返回 "N tasks"。保留 boardTitle。在独立文件新增测试，执行现有测试并完成 Task。
需求 C：在 src/priority.mjs 新增 priorityRank(value)。high、normal、low 分别返回 0、1、2；未知或未提供的值返回 3。保留 priorityOrder。在独立文件新增测试，执行现有测试并完成 Task。

三个 Task 全部完成后，在原始文件夹执行以下命令，应看到 PARALLEL_TASKS_ACCEPTED。此练习涵盖兼容修改，不刻意制造冲突，也没有测量吞吐量；请如实记录实际发生的冲突、检查失败与人工介入。

node --test tests/*.test.mjs
node checks/parallel-tasks.mjs

仓库信任边界

先看清楚 ait init 会改什么。

请在 coding agent 要修改的仓库中运行。

cd <你的仓库>
ait init
  • 创建仓库本地的 .ait/ 状态与 docs/sprints/。
  • 在 AGENTS.md 创建或更新一段带明确标记的工作流区块。
  • 完整保留标记外的 AGENTS.md 内容；再次运行不会重复添加区块。
  • 如果没有 CLAUDE.md，创建一个指向 AGENTS.md 的最小入口；现有文件绝不覆盖。
  • 不启动服务器，也不把仓库数据发送到任何地方。
以后如果要移除仓库集成

AIT 1.1.1 刻意不提供一键移除仓库的命令。如果历史仍有价值，先保留 .ait/；只删除 AGENTS.md 里的标记区块；只有在生成的 CLAUDE.md 仍只包含 AIT 指针时才移除它。Sprint Markdown 可能是用户内容，绝对不要直接删除整个 docs/sprints/。

现有项目请先按入门文档导入现有状态并设置审查名称；已由 AIT 管理的仓库，请沿用当前的 AGENTS.md。

示例成功后，在自己的项目挑选一个范围清楚、方便审查的修改。

照平常的方式跟 coding agent 说

添加一个无障碍的密码显示控制。
登录 API 不要动，并补上测试。

生成的仓库指示会要求 agent 记录需求、启动隔离 Task、运行检查，再完成验证过的结果。你不必把需求翻成 AIT 命令。

检查本地状态

ait --version
ait status --json
{
  "ok": true,
  "line_name": "main",
  "workspace": { "status": "clean" },
  "next_action": null
}

现在交给 agent 一个真实任务。

真正的激活点是成功完成一个 Task，不是只有安装完成。

看完整工作流查看发布状态