TAKT

🇯🇵 日文文档 | 💬 Discord 社区

TAKT Agent Koordination Topology — 为你的 AI 编码代理提供结构化的评审循环、管理型提示和安全约束——让它们交付高质量代码，而不仅仅是代码。

TAKT 通过 YAML 定义的工作流，并内置评审周期，来运行 AI 代理（Claude Code、Codex、OpenCode、Cursor、GitHub Copilot CLI）。你只需与 AI 沟通以定义需求、排队任务，然后让 TAKT 处理执行过程——包括规划、实现、多阶段评审以及修复循环——所有这些都由声明式的工作流文件来控制。

TAKT 是用 TAKT 自身构建的（自用）。

为什么选择 TAKT

开箱即用 — 架构、安全性和 AI 反模式评审标准已内建。从第一天起就能交付符合质量标准的代码。

实用 — 这是一款用于日常开发的工具，而非演示工具。你可以与 AI 沟通以细化需求、排队任务并执行它们。在任务执行时会隔离工作树，在失败时会创建 PR 并重试。

可复现 — 执行路径在 YAML 中声明，确保结果一致。工作流可以共享——一个团队成员构建的工作流可以被其他任何人使用，以运行相同的高质量流程。每一步都会以 NDJSON 格式记录，从而实现从任务到 PR 的完整可追溯性。

多代理 — 协调多个具有不同角色、权限和评审标准的代理。运行并行评审者，将失败的任务路由回实施者，并通过声明式规则聚合结果。提示被管理为独立的方面（角色、策略、知识、指令），可以在不同的工作流中自由组合（分面提示）。

要求

选择其中之一：

• 提供商 CLI：安装了 Claude Code（默认 claude 提供商）、Codex、OpenCode、Cursor Agent 或 GitHub Copilot CLI
• 直接 API：OpenAI / OpenCode API 密钥（无需 CLI）

可选：

• GitHub CLI (gh) — 用于 takt #N（GitHub Issue 任务）
• GitLab CLI (glab) — 用于 GitLab Issue/MR 集成（根据远程 URL 自动检测）

OAuth 和 API 密钥的使用：是否允许使用 OAuth 或 API 密钥访问因提供商和使用场景而异。在使用 TAKT 之前，请查看各提供商的服务条款。

快速开始

安装

npm install -g takt

与 AI 沟通并排队任务

$ takt

选择工作流：
  ❯ 🎼 default (当前)
    📁 🚀 快速开始/
    📁 🎨 前端/
    📁 ⚙️ 后端/

> 使用 JWT 添加用户认证

[AI 清晰化需求并组织任务]

> /go

提议的任务：
  ...

您想做什么？
    立即执行
    创建 GitHub Issue
  ❯ 排队为任务          # ← 正常流程
    继续对话

选择“排队为任务”会将任务保存到 .takt/tasks/。运行 takt run 来执行——TAKT 会创建一个隔离的工作树，运行工作流（计划 → 实现 → 评审 → 修复循环），并在完成后提供创建 PR 的选项。

# 执行排队的任务
takt run

# 也可以从 GitHub Issues 排队
takt add #6
takt add #12

# 执行所有待处理的任务
takt run

“立即执行” 会直接在当前目录中运行工作流，而不进行工作树隔离。这适用于快速实验，但请注意，更改会直接进入你的工作树。

管理结果

# 列出任务分支 — 合并、重试、强制失败或删除
takt list

工作原理

TAKT 使用音乐隐喻——其名称源自德语中的“节拍”或“指挥棒一挥”，用于指挥乐团保持节奏。TAKT 在面向用户和面向实现的术语中始终如一地使用“工作流”和“步骤”。

工作流由一系列步骤定义。使用 steps、initial_step 和 max_steps。每个步骤指定角色（谁）、权限（允许什么）和规则（接下来发生什么）。以下是一个最小示例：

name: plan-implement-review
initial_step: plan
max_steps: 10

steps:
  - name: plan
    persona: planner
    edit: false
    rules:
      - condition: Planning complete
        next: implement

  - name: implement
    persona: coder
    edit: true
    required_permission_mode: edit
    rules:
      - condition: Implementation complete
        next: review

  - name: review
    persona: reviewer
    edit: false
    rules:
      - condition: Approved
        next: COMPLETE
      - condition: Needs fix
        next: implement    # ← fix loop

规则决定下一步。COMPLETE 成功结束工作流，ABORT 则以失败结束。请参阅 工作流指南 以了解完整的模式、并行步骤和规则条件类型。

工作流文件位于 workflows/ 目录中，这是官方目录名称。

当同一工作流名称存在于多个位置时，TAKT 按照以下顺序解析：.takt/workflows/ → ~/.takt/workflows/ → 内置。

推荐的工作流

工作流	使用场景
default	标准开发。测试优先，包含 AI 反模式评审和并行评审（架构 + 主管）。
frontend-mini	面向前端的迷你配置。
backend-mini	面向后端的迷你配置。
dual-mini	面向前端和后端的迷你配置。

请参阅 内置目录 以获取所有工作流和角色。

关键命令

命令	描述
takt	与 AI 沟通，细化需求，执行或排队任务
takt run	执行所有待处理的任务
takt list	管理任务分支（合并、重试、强制失败、指示、删除）
takt #N	将 GitHub Issue 作为任务执行
takt eject	复制内置工作流/方面以进行定制
takt workflow init	创建新的工作流框架
takt workflow doctor	验证工作流定义
takt repertoire add	从 GitHub 安装曲目包

请参阅 CLI 参考 以获取所有命令和选项。

配置

最小的 ~/.takt/config.yaml：

provider: claude    # claude, claude-sdk, codex, opencode, cursor, or copilot
model: sonnet       # 直接传递给提供商
language: en        # en 或 ja

或者直接使用 API 密钥（无需安装 Claude、Codex、OpenCode 的 CLI）：

export TAKT_ANTHROPIC_API_KEY=sk-ant-...   # Anthropic (Claude)
export TAKT_OPENAI_API_KEY=sk-...          # OpenAI (Codex)
export TAKT_OPENCODE_API_KEY=...           # OpenCode
export TAKT_CURSOR_API_KEY=...             # Cursor Agent (如果已登录则可选)
export TAKT_COPILOT_GITHUB_TOKEN=ghp_...   # GitHub Copilot CLI

请参阅 配置指南 以了解所有选项、提供商配置文件和模型解析。

自定义

自定义工作流

takt workflow init my-flow   # 创建一个新的工作流框架
takt workflow doctor my-flow # 验证工作流定义
takt eject default           # 将内置工作流复制到 ~/.takt/workflows/ 并进行编辑

自定义角色

在 ~/.takt/personas/ 目录下创建一个 Markdown 文件：

# ~/.takt/personas/my-reviewer.md
你是一位专注于安全性的代码评审员。

在你的工作流中引用它：persona: my-reviewer

详情请参阅 工作流指南 和 代理指南。

CI/CD

TAKT 提供了用于 GitHub Actions 的 takt-action：

- uses: nrslib/takt-action@main
  with:
    anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }}
    github_token: ${{ secrets.GITHUB_TOKEN }}

对于其他 CI 系统，可以使用流水线模式：

takt --pipeline --task "修复 bug" --auto-pr

完整的设置说明请参阅 CI/CD 指南。

项目结构

~/.takt/                    # 全局配置
├── config.yaml             # 提供者、模型、语言等
├── workflows/              # 用户自定义的工作流定义
├── facets/                 # 用户自定义的方面（角色、策略、知识等）
└── repertoire/             # 已安装的资源包

.takt/                      # 项目级
├── config.yaml             # 项目配置
├── workflows/              # 项目特定的工作流覆盖
├── facets/                 # 项目特定的方面
├── tasks.yaml              # 待处理的任务
├── tasks/                  # 任务规范
└── runs/                   # 执行报告、日志、上下文

工作流定义存储在 workflows/ 目录下。

API 使用

import { WorkflowEngine, loadWorkflow } from 'takt';

const config = loadWorkflow('default', process.cwd());
if (!config) throw new Error('未找到工作流');

const engine = new WorkflowEngine(config, process.cwd(), '我的任务');
await engine.run();

文档

文档	描述
CLI 参考	所有命令和选项
配置	全局和项目设置
工作流指南	创建和自定义工作流
代理指南	自定义代理配置
内置目录	所有内置工作流和角色
面向方面的提示	提示设计方法论
资源包	安装和共享资源包
任务管理	任务队列、执行、隔离
数据流	内部数据流和架构图
CI/CD 集成	GitHub Actions 和流水线模式
提供商沙盒与权限	Codex / OpenCode / Claude 的沙盒、权限模式和网络访问
变更日志 (日语)	版本历史
安全策略	漏洞报告

社区

加入 TAKT Discord，获取问题解答、讨论和最新动态。

贡献

详情请参阅 CONTRIBUTING.md。

许可证

MIT — 详情请参阅 LICENSE。

TAKT 快速上手指南

TAKT (Agent Koordination Topology) 是一个专为 AI 编程助手设计的编排工具。它通过 YAML 定义的工作流，为 Claude Code、Codex、Cursor 等 AI 代理提供结构化的审查循环、提示词管理和安全护栏，确保输出的代码质量而不仅仅是代码数量。

环境准备

系统要求

• Node.js: 需安装 Node.js 环境（推荐最新 LTS 版本），因为 TAKT 通过 npm 分发。
• Git: 用于工作树隔离和 PR 创建。

前置依赖（任选其一）

TAKT 需要调用底层的 AI 编程工具，请选择以下一种方式配置：

方案 A：安装提供商 CLI（推荐） 确保已安装并登录以下任一工具的命令行版本：

• Claude Code (默认 provider)
• Codex
• OpenCode
• Cursor Agent
• GitHub Copilot CLI

方案 B：直接使用 API Key 若不想安装 CLI，可直接配置环境变量使用 API：

export TAKT_ANTHROPIC_API_KEY=sk-ant-...   # Anthropic (Claude)
export TAKT_OPENAI_API_KEY=sk-...          # OpenAI (Codex)
export TAKT_OPENCODE_API_KEY=...           # OpenCode

可选增强工具

• GitHub CLI (gh): 用于通过 takt #N 直接处理 GitHub Issue。
• GitLab CLI (glab): 用于 GitLab Issue/MR 集成。

注意：使用前请确认各提供商的服务条款是否允许 OAuth 或 API Key 自动化访问。

安装步骤

使用 npm 全局安装 TAKT：

npm install -g takt

国内加速提示：如果 npm 下载缓慢，建议切换至国内镜像源：

npm config set registry https://registry.npmmirror.com
npm install -g takt

安装完成后，可通过 takt --version 验证安装。

基本使用

TAKT 的核心流程是：对话定义需求 -> 排队任务 -> 自动执行工作流（计划->实现->审查->修复）。

1. 启动交互并定义任务

在终端输入 takt 启动交互式会话。你可以用自然语言描述需求，AI 会帮你澄清并生成任务提案。

takt

交互示例：

Select workflow:
  ❯ 🎼 default (current)
    📁 🚀 Quick Start/
    ...

> Add user authentication with JWT

[AI clarifies requirements and organizes the task]

> /go

Proposed task:
  ...

What would you like to do?
    Execute now
    Create GitHub Issue
  ❯ Queue as task          # ← 选择此项将任务加入队列（推荐）
    Continue conversation

• Queue as task: 将任务保存到 .takt/tasks/，稍后统一执行（支持工作树隔离，更安全）。
• Execute now: 直接在当前目录执行（无隔离，适合快速实验）。

2. 执行 queued 任务

当任务排队后，使用 run 命令触发执行。TAKT 会自动创建隔离分支，运行完整的工作流（包括多轮审查和修复），并在完成后提示是否创建 PR。

# 执行所有待处理的任务
takt run

# 也可以直接从 GitHub Issue 创建并执行任务
takt add #6
takt add #12
takt run

3. 管理任务结果

查看、合并、重试或删除任务分支：

takt list

4. 自定义配置（可选）

编辑 ~/.takt/config.yaml 指定默认提供商和模型：

provider: claude    # 可选：claude, codex, opencode, cursor, copilot
model: sonnet       # 具体模型名称
language: en        # 语言设置：en 或 ja

核心工作流原理

TAKT 通过 YAML 文件定义工作流（位于 workflows/ 目录）。一个典型的工作流包含多个步骤（如 plan, implement, review），每个步骤指定了角色（Persona）、权限和流转规则。如果审查未通过，会自动回退到实现步骤进行修复，形成闭环。

# 简化的工作流示例
steps:
  - name: plan
    persona: planner
    rules:
      - condition: Planning complete
        next: implement
  - name: implement
    persona: coder
    edit: true
    rules:
      - condition: Implementation complete
        next: review
  - name: review
    persona: reviewer
    rules:
      - condition: Needs fix
        next: implement    # 自动修复循环
      - condition: Approved
        next: COMPLETE

现在你可以开始使用 TAKT 构建高质量的 AI 驱动开发流程了。更多高级用法（如自定义 Persona、CI/CD 集成）请参考官方文档。