TAKT—TAKT 代理协调拓扑 — 是一个开源编排 CLI，用于通过显式的版本化工作流程运行编码代理。 YAML 工作流定义了步骤、角色、权限、转换和最终状态，而不是要求一名代理决定规划、实施和审查何时完成。当前提供程序界面包括 Claude、Codex、OpenCode、Cursor、GitHub Copilot CLI 和 Kiro，配置在 SDK/API-key 和 external-CLI 之间变化集成。
TAKT 的价值是过程的可重复性，而不是额外的模型智能。它可以使审查循环可见，隔离 Git 工作树中的任务并保留运行记录，但它不能保证代理的状态判断是正确的，也不能保证通过的测试证明软件是正确的。团队仍然拥有规范、工具权限、独立验证、秘密、合并控制和多个模型调用的运营成本。
从聊天请求到受管控的变更
用户/问题
|
v
谈话：细化范围
|
QUEUE：不可变的任务记录
|
在隔离的工作树中运行
|
.----+---------+----------。
维维维
计划------>实施-->审查
^ | |
| v +--> 完成
'-----------修复循环+--> ABORT
|
v
独立测试+人工合并
该项目描述了“Talk-Queue-Run”模式。互动聊天完善任务；排队记录；执行在隔离的共享克隆工作树中运行配置的工作流。直接、发布和管道模式缩短了这条路径。仅当输入已经具有机器可检查的验收标准时，跳过细化才是明智的。
没有音乐隐喻的核心概念
| TAKT 概念 | 工程意义 | 控制问题 |
|---|---|---|
| 工作流程（旧材料中以前的“片段”） | YAML 状态机 | 每条路径都能安全终止吗？ |
| 步数/动作 | 代理工作的有界单位 | 它可以使用哪些文件和工具？ |
| 人格面具 | 特定于角色的提示方面 | 它改变了权威还是仅仅改变了观点？ |
| 政策/知识/指导 | 可组合的上下文方面 | 当指令冲突时哪个来源获胜？ |
| 规则 | 状态条件转换 | 该条件是否可以独立观察？ |
| 提供商路由 | 将步骤、标签或角色映射到模型/提供商 | 成本、数据和能力是否可以接受？ |
| 寻找合同 | 结构化审查发现生命周期 | 调查结果可以被悄悄放弃或自我关闭吗？ |
文档和发布已从“片段/动作”术语演变为“工作流程/步骤”术语。固定已安装的 npm 版本并阅读其匹配的文档，而不是复制旧的 YAML 示例。经审查，npm 报告了版本 0.52.0 和 Node 要求 ^20.20.0 或 >=22.22.0;安装前确认live包。
最小的工作流程是一个图表，而不是一个清单
名称：计划-实施-审查
初始步骤：计划
最大步数：10
步骤：
- 名称：计划
角色：策划者
编辑：假
规则：
- 条件：规划完成
下一步：实施
- 名称：实施
角色：编码员
编辑：真实
规则：
- 条件：实施完成
下一页： 回顾
- 名称：评论
角色：审稿人
编辑：假
规则：
- 条件：已批准
下一个： 完成
- 状况：需要修复
下一步：实施这个说明性模式需要故障边缘、迭代限制和确定性检查。 “规划完成”和“已批准”是模型解释，除非有模式、测试或人为决定的支持。为无效状态、提供程序失败、预算耗尽和范围违规添加显式 ABORT 行为。运行您安装的版本支持的官方工作流验证/医生命令。
围绕证据进行设计转变
| 过渡 | 身体状况较弱 | 更有力的证据 |
|---|---|---|
| 计划→实施 | 经纪人说计划很好 | 所需的验收、文件、风险和测试领域验证 |
| 实施→审查 | 代理说编码已完成 | 存在差异，允许更改路径，运行构建/测试命令 |
| 审查 → 修复 | 自由形式的批评 | 发现结果包含 ID、严重性、文件/行、证据和状态 |
| 审核→完成 | 没有提到任何问题 | Ledger 没有发现任何公开的封锁结果，并且大门已通过 |
| 任何 → 中止 | 模特决定放弃 | 预算、安全、无效状态或重复失败的政策火灾 |
| 完成→合并 | 自动 PR 合并 | 受保护的分支检查和负责任的人工批准 |
权限必须遵循步骤，而不是提供商品牌
规划者通常需要读取/搜索访问权限，而不是编辑权限。实施者可以编辑有界工作树并运行存储库检查。审阅者应该是只读的，这样它就无法在批准证据之前“修复”证据。发布步骤需要明确的人为大门和狭窄的存储库令牌。模型的复杂性并不能证明广泛的权威是合理的。
| 能力 | 默认立场 | 控制 |
|---|---|---|
| 文件系统编辑 | 仅实施/修复步骤 | 允许根和步骤后差异检查 |
| 壳牌 | 仅限沙盒/工作树 | 命令策略、超时、CPU/磁盘限制 |
| 网络 | 拒绝或列入白名单 | 阻止元数据/内部主机和日志目的地 |
| Git 推送/公关 | 任务分支和 PR 草案 | 范围内的应用程序令牌和受保护的主程序 |
| 秘密 | 仅在需要时注射 | 每步骤的短期凭证和编辑 |
| 包安装 | 锁文件约束 | 批准的注册表、完整性和依赖性扫描 |
| 部署 | 最初在外部编码工作流程 | 独立的发布系统和人工审批 |
工作树隔离：有用但不完整
TAKT 的独立 Git 工作树/共享克隆可保护开发人员的活动文件并使任务分支更易于检查。它不隔离进程、网络、凭据、用户主文件或外部帐户。具有 shell 访问权限的代理仍然可以读取环境变量、联系任意主机或调用全局身份验证的 CLI。
对于不受信任的问题或存储库，请在具有干净主目录、受限出口和资源配额的一次性容器或虚拟机中运行整个任务。仅挂载任务存储库。使用专用的 GitHub/GitLab 应用令牌。导出差异、日志和所需证据后销毁环境。
提供商路由创建成本和策略路由
将规划者路由到一种模型并将实施/审查交给其他人可以提高专业化并避免单一模型的单一文化。这还意味着源代码和提示可能会根据不同的保留、区域和帐户条款到达多个提供商。按存储库数据类维护允许列表，并记录每个步骤的解析提供者/模型。
| 路由目标 | 合理的实验 | 护栏 |
|---|---|---|
| 降低规划成本 | 结构化低风险计划的小型模型 | 升级模糊性/安全工作 |
| 执行力强 | 带有编辑工具的以代码为中心的模型 | 令牌、文件和命令限制 |
| 独立审查 | 不同的提供商/型号系列 | 只读和查找架构 |
| 数据驻留 | 敏感仓库的批准提供商 | 阻止回退到未经批准的提供商 |
| 可用性 | 短暂中断的后备模型 | 重新验证行为，切勿默默扩大数据共享 |
审查循环需要硬性停止规则
代理审查可能会出现波动：一次通过更改了 API，另一次则恢复它；一种模型添加测试，另一种模型删除测试。设置最大步数、重试、挂机时间、模型花费、更改的文件和差异大小。哈希结果和补丁以检测重复状态。当相同的发现重新出现、测试没有改进或范围扩大时，请上报给人工处理。
- 在没有审查者证据的情况下，切勿让实施者将自己的安全发现标记为已解决。
- 不要仅仅因为线路移动而关闭结果。
- 保持严重性变更和豁免可归因于个人或政策。
- 需要最终干净的签出验证，而不仅仅是修改后的代理会话内的命令。
及时和工作流程供应链风险
TAKT 可以使用内置或弹出的工作流程/方面，并且可以从 GitHub 安装曲目包。这些文件影响代理的行为和工具；将它们视为可执行依赖项。固定提交、审查差异、避免浮动 主要 CI 中的参考并在激活之前扫描包。
存储库文件、问题、编译器输出和获取的网页都是不受信任的提示内容。恶意问题可能会要求代理打印密钥或修改工作流程。系统策略和权限执行必须位于该文本之外。不要让任务编辑在没有单独审查的情况下判断同一任务的质量门。
CI/CD部署
TAKT 记录管道模式和 GitHub Action。从只读分析或草稿 PR 创建开始。当秘密和可写令牌可用时，由分叉触发的 GitHub Actions 可能会很危险；遵循 GitHub 的特定活动安全指南。通过不可变的提交 SHA 固定第三方操作并使用最少的 权限.
| CI元素 | 安全初始设置 | 原因 |
|---|---|---|
| 触发 | 手动调度或可信标签 | 防止任何问题作者花费/采取行动 |
| 存储库令牌 | 阅读内容；仅在需要时才写 PR | 限制妥协 |
| 提供者的秘密 | 环境范围和屏蔽 | 减少叉子/日志暴露 |
| 输出 | PR 草案加证据工件 | 保持合并责任 |
| 并发性 | 每个存储库和每个任务的上限 | 控制冲突的分支和支出 |
| 超时 | 有限的工作和工作流程预算 | 停止循环和挂起的 CLI |
飞行员要测量什么
选择 20 个有代表性的有界任务和一个可比较的人类/单代理对照组。跟踪接受的任务率、首次独立 CI 通过、审阅者分钟数、重新打开的缺陷、安全结果、交付时间、模型成本和工作流程失败。更改的线路和客服人员的步数是活动，而不是价值。
还可以衡量编排开销：YAML 维护、提供程序设置、错误审查结果、冲突清理和时间诊断转换。当结构化工作流程提高可接受的质量或可预测性足以超过该开销时，它就是合理的。
当 TAKT 合适时
| 情况 | 适合 | 为什么 |
|---|---|---|
| 反复维护，测试明确 | 强飞行员 | 可重复使用的工作流程和目标门 |
| 多模型计划/构建/审查 | 好 | 提供商路由和显式角色 |
| 模糊的新建产品设计 | 有条件的 | 人类的决定主导着早期的工作 |
| 一个微小的确定性编辑 | 弱 | 直接脚本或一个受监督的代理更简单 |
| 生产事故响应 | 自主启动不良 | 现场权威和时间压力会放大错误 |
| 具有广泛秘密的不受信任的存储库 | 没有沙箱不安全 | 工作树本身并不是安全边界 |
替代方案
| 选项 | 最适合 | 与 TAKT 的权衡 |
|---|---|---|
| TAKT | YAML 中的本地/CI 多提供商编码工作流程 | 新的编排语言和项目成熟度 |
| 直接Codex/Claude代码 | 一名开发人员监督一项任务 | 可重复性较低的多级布线 |
| GitHub 代理工作流程 | GitHub 原生存储库自动化 | 特定于平台的执行/治理 |
| Open SWE | 内部异步问题/聊天到 PR 平台 | 更重的服务和沙箱集成 |
| LangGraph | 自定义编程状态代理应用程序 | 更多的代码和通用性，更少的编码工作流封装 |
| 普通 CI 脚本 | 已知的确定性变换 | 推理不太灵活，通常更安全、更便宜 |
常见问题
TAKT 是编码模型吗？
不会。它会编排受支持的编码代理提供程序和工作流程。
它是开源的吗？
当前存储库和 npm 包标识 MIT 许可证。验证已安装的版本和捆绑的依赖项。
它是否隔离代理执行？
它使用隔离的 Git 任务工作树/克隆来保护工作树状态。强大的进程、网络和秘密隔离需要容器或虚拟机。
可以在CI中运行吗？
是的，通过管道模式和记录的操作集成。从最小的权限开始并起草 PR。
YAML 保证质量吗？
不，它使流程变得明确。质量需要有证据支持的转变、独立的大门和负责任的审查。
支持哪些提供商？
当前材料列表 Claude、Codex、OpenCode、Cursor、GitHub Copilot CLI 和 Kiro。支持和身份验证随版本而变化。
工作流程何时应停止？
成功需要有必要的关卡、明确的中止或步骤、时间、支出和重复发现的硬预算。
主要来源
- 官方 TAKT 存储库和自述文件
- 官方 npm 包元数据
- 官方 CLI 参考
- 官方配置指南
- 官方工作流程指南
- 官方变更日志
- 官方 GitHub Action 存储库
- GitHub Actions 安全强化
- OWASP 提示注入指导
上次审核日期为 2026 年 7 月 25 日。TAKT 正在快速发布；固定 npm 包、工作流程架构和提供程序版本，然后在升级后重新运行安全和行为测试。
