agentloopkit

AgentLoopKit

为软件 Agent 提供即插即用的工程工作流。

一款由 Baseframe Labs 开发的开源工具。

你的软件 Agent 可以生成差异。AgentLoopKit 帮助你判断这些改动是否便于审查、可验证并已准备好合并。

它为 Codex、Claude Code、Cursor、OpenCode、Gemini CLI、GitHub Copilot CLI 及其他工程 Agent 提供本地验收层：任务约定、安全规则、验证证据、审查就绪度评分、PR 描述和审查者交接。

无结构的自动化会产出代码。智能体工程会产出可审计的工作。

ProjScan 发现风险。 AgentLoopKit 管控工作。 AgentFlight 证明结果。

此 README 中的截图和终端演示由 docs/assets/readme/ 中已提交的源文件通过 Playwright 和 VHS 生成。你可以在本地重新生成。

功能介绍

AgentLoopKit 是一套仓库级工具包，供使用 Codex、Claude Code、Cursor、OpenCode、Gemini CLI、GitHub Copilot CLI 及其他工程 Agent 的开发者使用。

保留你的 Agent、IDE 和 CLI。AgentLoopKit 为这些工具提供可重复的本地工作流：

1. 明确任务。
2. 限制风险。
3. 实施最小且有用的改动。
4. 通过实际命令验证。
5. 审查差异。
6. 提供证据并交接。
7. 仅在工作便于审查时交付。

在现有仓库中运行 init，AgentLoopKit 会创建：

• .agentloop/，用于存放任务、报告、交接内容、门禁、策略、模板和 Agent 指令
• AGENTS.md，为 Agent 提供仓库指南
• AGENTLOOP.md，用于说明工作循环
• agentloop.config.json，用于设置本地命令和路径

生成的 AGENTS.md 包含产品、CLI、模板、验证、安全、发布、文档、兼容性、MCP 和仓库维护方面的专家名册。它能帮助后续的 Agent 会话拆分工作，而无需添加后台服务。

CLI 演示展示了常规流程：初始化仓库、创建任务、运行经过审查的验证、评估审查就绪度、起草 PR 文案、检查审查上下文，并追溯文件变更的原因。

安装

在要配置的仓库中使用 npx：

cd /path/to/your/repo
npx agentloopkit init --dry-run
npx agentloopkit init

init 会在当前目录写入文件。--dry-run 会预览相同的计划，但不会写入任何内容。

如果希望获得清晰的差异证据，请在首次功能任务开始前提交生成的 harness 基线。如果 harness 文件尚未提交，explain-diff、Guard 和恢复包会将这些生成的文件视为本地工作纳入其中。这虽然准确，但会让稳定运行阶段的工作流显得更嘈杂。

设置完成后，非 init 命令会向上查找最近的 agentloop.config.json，并将其所在文件夹用作 AgentLoop 根目录。你可以在嵌套的源代码文件夹中运行 agentloop status、agentloop verify、agentloop ship 或 agentloop prepare-pr，任务、报告、运行记录和交接内容仍会写入已初始化的仓库根目录。

除非你打算配置主目录，否则不要从主目录运行 init。AgentLoopKit 默认会拒绝这样做；--force 则允许执行，并会显示主目录目标警告。如果你希望使用本地 Agent 指引，但不想提交生成的文件，请使用仅限本地模式：

npx agentloopkit init --local-only

--local-only 会写入 harness，向 Git 查询此克隆的元数据目录，然后在该克隆的 info/exclude 中添加一个带标记的区块，将 .agentloop/、AGENTS.md、AGENTLOOP.md 和 agentloop.config.json 排除在外。它不会编辑 .gitignore、全局 Git 配置、shell 配置文件或其他项目文件。

以下示例在设置完成后使用 agentloop。如果你没有在本地安装软件包，或没有将其二进制文件加入 PATH，请继续使用一次性形式，例如 npx --yes agentloopkit@latest doctor --redact-paths。

显式检查已发布的软件包：

npx --yes agentloopkit@latest version
npx --yes agentloopkit@latest init

如需可重复的 CI 或团队设置，请将 @latest 替换为经过审核的版本。

初始化前，探索性预检可以采用建议模式：

npx --yes agentloopkit@latest doctor --advisory --redact-paths

建议模式会显示缺少设置的诊断信息，但以 0 退出，以便首次运行脚本继续执行。对于应在设置错误时失败的门禁，请使用普通的 doctor 或 doctor --strict。

团队固定版本用法：

pnpm add -D agentloopkit
pnpm agentloop init

现有仓库

已使用 AgentLoopKit 的仓库可以更新 CLI，而无需重写本地 harness 文件：

cd /path/to/existing/repo
npx --yes agentloopkit@latest version
npx --yes agentloopkit@latest doctor --redact-paths
npx --yes agentloopkit@latest upgrade-harness --details --redact-paths
npx --yes agentloopkit@latest init --dry-run

这些命令会检查已发布的软件包。此仓库可能会在下次发布前记录尚未发布的指引；在预期 agentloopkit@latest 已包含新子命令前，请先查看发布状态。

init 会跳过已存在的生成文件；对于未标记的 AGENTS.md 文件，它会在末尾追加内容，而不是覆盖维护者的修改。使用 upgrade-harness 查找较旧的指引，这些指引可能没有要求 Agent 在广泛读取仓库前运行 agentloop doctor 和 agentloop start，在可用时使用 agentloop context handles 列出句柄，或使用 agentloop context show <handle> 展开源事实。只将有用的内容复制到 AGENTS.md、AGENTLOOP.md 或 .agentloop/harness/*。

你可以在刷新旧指引前使用最新工作流：

npx --yes agentloopkit@latest create-task --type bugfix --title "Fix checkout bug"
npx --yes agentloopkit@latest start --for generic --goal implement --redact-paths
npx --yes agentloopkit@latest verify
npx --yes agentloopkit@latest ship
npx --yes agentloopkit@latest prepare-pr
npx --yes agentloopkit@latest maintainer-check

核心工作流

init 后的首个有效工作流：

agentloop doctor
agentloop create-task --type bugfix --title "Fix checkout bug" --include-config-commands
agentloop status --brief
agentloop start --for codex --goal implement --redact-paths
agentloop loop create --goal "Keep checkout work release-ready" --budget-tokens 50000 --max-iterations 5
agentloop loop tick
agentloop loop scorecard
agentloop ready
agentloop verify --task-commands --progress
agentloop ship
agentloop prepare-pr
agentloop task done

该序列会创建任务约定、检查仓库设置、为下一个软件 Agent 提供简洁的启动简报、记录包含令牌收据的本地工作流约定、评估是否应继续下一轮工作流、检查就绪门禁、仅运行经过审核的验证命令、记录评审就绪证据、起草 PR 文案，并关闭当前活动任务。它不会向 GitHub 发帖、发布软件包、调用大模型、执行编码 Agent，也不会运行隐藏命令。

让你的 Agent 从这里开始

在软件 Agent 对仓库进行广泛扫描之前，先运行：

agentloop doctor --redact-paths
agentloop start --for codex --goal implement --redact-paths
agentloop context handles --redact-paths
agentloop context show <handle-from-start> --redact-paths

doctor 会检查 Agent 就绪矩阵：启动前的 Doctor 指引、Start 指引、上下文句柄指引、避免广泛读取的指引、MCP 指引，以及已安装的 Agent 指令文件。start 会提供当前任务、证明、风险、上下文预算和来源句柄。context handles 会列出当前可用的句柄。只有在 Agent 需要详情时，context show 才会展开精确的本地来源事实。

npx agentloopkit init
agentloop create-task --title "Fix login redirect bug" --type bugfix \
  --acceptance "Password-reset login redirects to the requested page" \
  --include-config-commands \
  --verification "npm test -- auth"

# Run Codex, Claude Code, Cursor, OpenCode, Gemini CLI, or another software agent.

agentloop verify --task-commands --only-task-commands --progress
agentloop ship --github-comment
agentloop prepare-pr

create-task 会将新契约设为当前活动任务。只有在需要切换到另一份契约时，才使用 agentloop task set <path>。 如果希望任务契约从 agentloop.config.json 复制非空的 test、lint、typecheck 和 build 命令，请添加 --include-config-commands。创建任务时会记录这些命令，但不会运行它们。如果当前活动契约已包含完整的检查列表，请使用 verify --task-commands --only-task-commands。 只有对于需要先生成验证报告的已审核任务关卡，才使用 verify --post-verification-gates。 验证并执行 ship 后，使用 agentloop prepare-pr 准备审核者文案，并使用 agentloop task done 关闭当前活动任务，然后再开始无关工作。

当 Agent 需要知道下一步本地操作、又不想读取每个文件时，请使用 agentloop status 或 agentloop next：

npx agentloopkit status
npx agentloopkit status --brief
npx agentloopkit next
npx agentloopkit next --redact-paths

当 status 或 next 在有未提交更改的仓库中建议使用 create-task 时，原因会指出现有的、非证据类的未提交文件，以便 Agent 在实施前确认下一个任务的范围。当 create-task 发现同样的既存未提交工作时，也会在生成的任务契约中添加一条有界的 Risk Notes 要点，让后续审核证据保留基线数量和示例。

当软件 Agent 需要在广泛读取之前了解仓库事实时，请使用 agentloop start --for codex --goal implement --redact-paths。Start 是预检：提供当前任务（如有）、关键状态、下一条安全命令、优先读取的句柄、风险摘要、验证时效性、上下文预算影响和来源句柄。使用 agentloop context handles 列出可用句柄和常见的空状态，然后仅在需要时使用 agentloop context show <handle> 展开来源事实。需要直接查看更底层的回执和省略详情时，请使用 agentloop context pack --for codex --goal continue --redact-paths。需要在审核前实时检查范围偏移、过期验证、证明欠账和上下文预算压力时，请使用 agentloop guard。需要了解当前已更改文件是否受任务范围、近期运行证据、最新验证和风险指引覆盖时，请使用 agentloop explain-diff。需要使用较旧的紧凑续接界面时，请使用 agentloop resume-pack --for codex、--for claude、--for cursor、--for generic 或 --for human。这些命令默认是只读的，且仅使用本地证据。

agentloop start 是 Agent 的起点。它会将任务状态、已更改文件、验证、风险和上下文压力整合为一份紧凑的预检，避免 Agent 凭空猜测。Context Contract 是其底层机制：context pack 会说明每个项目为何存在、指出省略了哪些内容，并提供指向来源事实的本地句柄。大量已更改文件会变成一份简短简报，Agent 只需在需要详情时再展开。

agentloop loop 会在常规任务契约之上添加本地循环契约。agentloop loop create 会记录目标、预算、停止条件、建议命令、原生任务路径和令牌回执。agentloop loop tick 会根据本地证据记录一次迭代决策：继续、停止、请求人工审核，或在关卡通过时将循环标记为就绪。一旦循环请求人工审核，在有人审核循环报告并解决阻塞证据之前，AgentLoopKit 会拒绝再次执行 tick。需要查看当前审核就绪关卡摘要、但不创建循环时，请使用 agentloop ready。 开始工作前，使用 agentloop harden [task] 检查任务契约中尚未解决的模糊点——占位文本、范围无界、未说明的假设、无法测试的验收标准，以及验收标准与非目标之间的矛盾。默认检查当前任务；若仍有阻塞性模糊点，则以非零状态码退出。使用 agentloop harden --resolve <id> --answer "..." 解决模糊点，这会将答案记录到契约的强化日志中。agentloop create-task 默认会在创建契约后立即报告相同的模糊点。

对于范围明确的自主执行轮次，配置一个本地运行器命令，让 AgentLoopKit 记录迭代过程：

agentloop loop create \
  --goal "Keep checkout work release-ready" \
  --runner-command "node scripts/agentloop-runner.mjs" \
  --runner-timeout-ms 600000 \
  --budget-tokens 50000 \
  --max-iterations 5

agentloop loop run
agentloop loop scorecard
agentloop ready --strict
agentloop loop report

loop scorecard 是开始下一轮自主执行前的预检门禁。它会读取循环契约、就绪状态、上下文包、令牌预算、迭代预算、运行器护栏和范围证据，然后返回 continue、ask-human、stop 或 ready。它不会执行运行器或运行验证。

loop run 只会执行循环契约中保存的命令。它使用 shell: false，拒绝 Shell 语法，阻止发布和破坏性命令系列，限制运行器输出，并继续应用最大迭代次数和令牌预算停止条件。AgentLoopKit 负责控制目标、预算、范围、门禁、证据和停止决策。你的 Agent、脚本、CI 任务或 AgentFlight 会话负责实施工作。

JSON 和 MCP 上下文预算／上下文包载荷会保留这条边界：它们包含精简的证据字段和 evidence-map:current 句柄，但不会发送完整的变更文件列表，除非 Agent 展开该本地句柄。

Start 采用严格的当前工作规则。它接受处于活动或开放状态的任务契约。已归档、状态为 done 或 deferred 的任务，以及 AgentFlight 占位任务，都会作为先前证据保留。对于旧工作，Start 和 Context 会省略 task:active 句柄及 agentloop ship 指引。在只有先前证据的干净仓库中，Start 会告知 Agent 当前没有活动任务。

Your software agent / app
  (Codex, Claude Code, Cursor, OpenCode, Gemini CLI, Copilot CLI,
   LangChain, Agno, Strands, your own scripts...)
        |
        | task contracts - diffs - verification - runs - research notes - logs
        v
 +------------------------------------------------------------------------+
 | AgentLoop Start Preflight + Context Contract (source truth stays here) |
 |------------------------------------------------------------------------|
 | State -> Next Safe Command -> Read First -> Risk -> Impact -> Handles   |
 |                                      |                                  |
 |                                      +-- task:active (current work only)|
 |                                      +-- verification:latest            |
 |                                      +-- run:latest                     |
 |                                      +-- evidence-map:current           |
 |                                      +-- context-budget:current         |
 |                                                                        |
 | Goals: implement - continue - review - debug - handoff - research       |
 | MCP tools - generated agent instructions - transparent local heuristics |
 +------------------------------------------------------------------------+
        |
        | compact preflight + retrieval handles
        v
Agent session / review / research handoff

上下文预算示例由本仓库中的本地 AgentLoopKit 输出生成。令牌估算采用 ceil(character_count / 4) 进行规划，并非基于服务提供方的分词器统计或计费声明。百分比会随仓库状态变化；重点在于，Agent 可以从选定的证据开始，并展开源句柄，而不必粘贴大量历史记录。

运行可重复的 Start 有用性演示，创建一个临时的混乱仓库，并查看 agentloop doctor 如何检查 Agent 就绪指引；随后，agentloop start 会报告已避免的上下文、已避免的宽泛文件扫描、过时证明、范围偏移、源句柄以及下一条安全命令。

终端演示由本仓库中已提交的 VHS 源文件生成。它展示了预期的 Agent 工作流：使用 Doctor 检查就绪状态，运行 Start 预检，查看不应进行宽泛扫描的内容，在存在当前任务句柄时展开它，并使用本地证据进行验证。

验证报告会将本地命令转化为评审证据。它们将命令状态、失败摘要、任务链接、变更文件上下文和后续门禁汇总到一个产物中，供评审者检查。

Dogfood Gate

AgentLoopKit 在此代码库中使用自己的循环。贡献者可以运行相同的本地自检：

npm run dogfood

该命令会检查任务文件夹规范、当前循环状态、公开文档规范、依赖项审计结果、harness 升级状态、评审门禁、产物清单、维护者可评审性、Agent 评审上下文、AgentFlight 健康状况和 ProjScan 健康状况。它不会发布软件包、创建标签、发表评论、读取令牌、读取 .env 内容或运行验证命令。

当 Agent 或 CI 作业需要结构化的 dogfood 摘要时，请使用 JSON 输出：

npm run dogfood:json
npm run dogfood:strict:json

JSON 摘要会报告模式、总体状态、步骤结果、退出代码、耗时和安全说明。在打印结构化输出前，它会将当前工作区根目录替换为 [git-root]。

编辑 README、示例或发布渠道文档时，可以单独运行公开文档检查：

npm run check:public-docs

发布或最终交接前，请使用更严格的门禁：

npm run dogfood:strict

当 typecheck、release-proof 或 npm-status 命令的健康状况、公开文档、SchemaStore、策略包、GitHub 元数据、AgentFlight 或 ProjScan 行为发生变化时，请使用维护门禁：

npm run maintenance:check

maintenance:check 涵盖单元测试、typecheck、公开文档、链接、非严格 npm release-proof 冒烟覆盖、只读 npm-status 安全测试、SchemaStore 输出与一致性测试、策略包清单与安全测试、GitHub 元数据安全与 ship-score 中立性测试、AgentFlight、ProjScan，以及非严格 dogfood 自检。新交接或发布证据准备就绪后，请运行 npm run dogfood:strict；当评审门禁警告应阻止交接时，也请运行该命令。维护者检查警告仅供评审者参考，除非命令以非零状态退出。严格的公开发布证明仍属于获批的发布门禁。

命令

该软件包提供两个二进制文件：

agentloop init
agentloopkit init

命令	用途
agentloop init	生成代码库框架和配置
agentloop doctor	检查设置健康状况、Agent 就绪情况、命令、Git 状态和风险文件；首次运行前检查可使用 --advisory
agentloop create-task	创建范围明确的任务约定
agentloop task ...	列出、显示、固定、更新、归档和检查任务状态
agentloop status	显示当前任务、最新报告、最新运行、未提交的文件和下一步
agentloop next	仅打印建议的下一步循环操作
agentloop start	运行代码库原生 Agent 预检查，涵盖任务、证据、风险、证明和影响
agentloop review-context	显示一份只读的可审查性上下文快照
agentloop context	列出句柄、构建上下文预算和包，并展开源事实
agentloop ready	检查任务、范围、验证和上下文预算是否就绪
agentloop harden	在开始工作前检查任务约定中尚未解决的薄弱环节
agentloop loop	记录本地循环目标、受保护的运行器轮次、评分卡、令牌收据、迭代决策和停止原因
agentloop guard	检查本地偏移、证明欠账和上下文预算压力
agentloop explain-diff	使用本地任务、验证、运行和风险证据说明当前差异
agentloop resume-pack	为 Agent 或审查者生成精简的本地续接简报
agentloop verify	运行已配置的检查并写入验证报告
agentloop ship	评估审查就绪情况、写入发布报告，并可选择打印 PR 评论
agentloop prepare-pr	生成 PR 标题、分组正文和可选的 GitHub 评论
agentloop summarize	预览确定性的审查者摘要
agentloop handoff	编写审查者交接摘要
agentloop check-gates	检查审查证据，但不运行测试
agentloop runs --latest	显示最新的本地 ship、verify 或 handoff 运行条目
agentloop show-run <id>	显示一条本地运行记录
agentloop intent <file>	显示某个文件按时间倒序排列的有限运行匹配项及原因
agentloop maintainer-check	检查 Agent 辅助完成的 PR 是否可供审查
agentloop artifacts	汇总本地任务、报告、发布报告、徽章和运行证据
agentloop artifacts --stale	预览数量受限的较旧本地证据候选项，不删除文件
agentloop upgrade-harness	检查较早生成的指南，不覆盖本地编辑内容
agentloop report	写入本地静态 HTML 证据报告
agentloop badge	写入本地 SVG 证据徽章
agentloop ci-summary	汇总 CI 上下文和现有 AgentLoop 证据
agentloop release-notes	根据代码库证据起草本地发行说明
agentloop release-check	检查本地发行就绪情况，不发布
agentloop release-proof	检查公开发行渠道中的发布后证明
agentloop npm-status	检查 npm 注册表状态，不发布
agentloop mcp-server	启动只读 MCP stdio 服务
agentloop policy ...	读取并比较本地安全策略
agentloop schemastore	打印配置架构目录条目
agentloop github import	导入明确指定的本地 GitHub issue 或 PR JSON
agentloop install-agent <name>	添加特定 Agent 的说明
agentloop list-templates	列出随附的模板
agentloop completion <shell>	打印 Shell 补全脚本
agentloop version	打印 CLI 版本
清理已完成任务的契约，确保验证和评审就绪证据齐备：

agentloop task archive --status done --dry-run
agentloop task archive --status done

有关命令示例、JSON 模式和安全说明，请参阅 docs/cli-reference.md。

有关本地循环契约、就绪门槛、令牌收据和 dogfood 循环，请参阅 docs/loop-contracts.md。

有关 ProjScan、AgentLoopKit 和 AgentFlight 之间的本地 JSON 交接，请参阅 Baseframe Suite Integration v1。

维护者在迭代时可以运行更快速、范围更集中的健全性检查：

npm run test:quick
npm run test:integration

发布前运行完整测试套件：

npm run test:release
npm run release-flow

test:quick 运行面向单元测试的快速测试集。test:integration 运行较慢的 CLI 工作流测试。test:release 运行完整的 Vitest 测试套件。release-flow 运行本地发布门禁，不会发布软件包、创建标签或创建 GitHub 发布。

Agent 设置

为你使用的 Agent 安装说明：

agentloop install-agent codex
agentloop install-agent claude-code
agentloop install-agent cursor
agentloop install-agent opencode
agentloop install-agent gemini-cli
agentloop install-agent github-copilot-cli
agentloop install-agent all
agentloop install-agent all --json --redact-paths

AgentLoopKit 会在仓库本地写入 Markdown 说明。可以安全地重新运行 install-agent：现有的 .agentloop/agents/<agent>.md 文件会被跳过，以保留本地修改；同时，AGENTS.md 会更新，补充任何缺失的 AgentLoopKit 引用。在分享设置输出前使用 --redact-paths；它会在普通文本和 JSON 输出中隐藏本地根目录，但不会改变文件的写入位置。如果无法确定第三方工具的确切配置约定，它会生成通用输出，而不会假装能管理其他工具的设置。

安全模型

AgentLoopKit 刻意保持简单：

• 无 postinstall 脚本
• 无遥测
• 无云后端
• 无数据库
• 无 API 密钥
• 无隐藏网络调用
• 不读取 .env 内容
• 安装期间不执行破坏性操作

环境文件仅按路径报告。只有在你明确运行 agentloop verify 时，才会运行验证命令。

默认情况下，agentloop ship 会复用当前的验证证据。如果希望它在就绪流程中运行验证，请传入 --run-verify。如果 CI 需要用于拉取请求评论的精简 Markdown，请传入 --github-comment。AgentLoopKit 不会自行发布评论。

agentloop prepare-pr 会按评审范围对已更改的文件分组，包括风险敏感路径、源代码、测试、AgentLoop 证据、文档、CI、配置和其他文件。

agentloop start 会为软件 Agent 提供简报，其中包含当前任务、关键的预检状态、下一条安全命令、优先阅读的源文件句柄、风险摘要、验证新鲜度、上下文预算影响和源文件句柄。agentloop context 会将本地任务、差异、验证和运行证据整理成精简的上下文预算，或整理成带源文件句柄的资料包，供软件 Agent 使用。它是只读的，并会说明纳入了什么、遗漏了什么、原因是什么，以及如何扩展本地源信息。agentloop guard 会在证据映射的基础上增加漂移、证明债务、基线和上下文预算检查。除非你明确传入 --write-report 或 --write-baseline，否则它是只读的。agentloop explain-diff 会直接显示证据映射。agentloop resume-pack 会将相同的本地证据打包成较旧格式的精简续接简报，并附带上下文预算估算。这些命令不会运行测试、调用外部 API、读取 .env 内容、发布评论、发布软件包、创建标签、拦截提示词、代理提供商流量或更改任务状态。

如需更精简的证据历史记录，agentloop verify --write-run 和 agentloop handoff --write-run 可以分别添加自己的本地运行记录，而不改变默认命令行为。 如果 .agentloop/runs/ 存在，agentloop status 会包含最新的本地运行账本条目，这样 Agent 无需打开每份报告，就能查看最新的评审就绪情况或验证证据。 运行账本输出使用安全的显示路径：AgentLoopKit 工件使用 .agentloop/...，仓库文件使用相对于仓库的路径，较早的仓库外绝对路径则只显示文件名。 在将输出粘贴到公开议题、PR 或 CI 日志前，请对 doctor、task list、task show、task set、task status、task done、task archive、task clear、status、next、start、review-context、context、guard、explain-diff、resume-pack、check-gates、artifacts、report、badge、runs、show-run、intent、verify、summarize、handoff、ship、prepare-pr、maintainer-check、upgrade-harness、ci-summary、release-notes、schemastore、github import、install-agent、release-check 或 release-proof 使用 --redact-paths。此模式会将本地根路径替换为占位符。除非传入路径脱敏标记，否则默认的 JSON 输出会为脚本保留原始路径。task show 会对显示的任务约定内容进行路径脱敏。task list、artifacts、runs、show-run、intent、schemastore 和 github import 已使用相对于仓库的路径或目录元数据；为保持命令一致性，这些命令也接受该标记。 agentloop review-context --json 为非 MCP Agent 提供一份只读的本地快照，其中包含状态、活动任务风险备注数量、精简证据映射、上下文预算估算、门禁、策略、工件、近期运行记录、最新发布证据和下一步操作。默认情况下，它会省略完整的变更文件列表；如需文件级详情，可让 Agent 使用 agentloop context show evidence-map:current。 agentloop upgrade-harness 为只读命令。CLI 升级后，它会告知现有用户哪些生成的指导文件需要人工审查。它不会合并模板，也不会覆盖本地修改。 agentloop schemastore --json 会输出 agentloop.config.json 的目录条目。准备向 SchemaStore 提交贡献时可使用此命令；CLI 不会代你提交该贡献。为保持一致性，schemastore --redact-paths 也可使用；目录值不是本地文件系统路径，因此输出值不会改变。 agentloop github import --issue-json issue.json --pr-json pr.json 会将明确提供的本地 GitHub 元数据导入 .agentloop/github/context.json。只要该本地上下文存在，review-context、prepare-pr 和 maintainer-check 就会使用它。缺少元数据不会阻止工作流继续运行。为保持一致性，github import --redact-paths 也可使用；元数据路径已相对于仓库，因此输出值不会改变。CLI 不会调用 GitHub API、读取令牌或运行 gh。 agentloop release-proof 会检查 npm、GitHub Releases、GitHub Marketplace、GHCR 和 MCP Registry 的发布后证据。使用 --only <channel> 可重新检查单个渠道。它可以查询公开元数据，也可以读取你明确传入的已捕获 JSON 文件。它不会发布、打标签、上传、发表评论或读取令牌。 Shell 补全包含以下固定值：任务类型、任务列表状态筛选器、状态转换、done 归档状态、Agent 名称、策略子命令、补全 Shell、工件类型、徽章来源、summarize 和 handoff 格式，以及 release-proof --only 渠道。

更多文档

• 快速入门
• CLI 参考
• 升级现有仓库
• 配置
• 任务契约
• 研究任务
• AgentLoop 上下文契约
• 证据映射和恢复包
• 验证报告
• 状态和下一步操作
• 关卡检查
• HTML 报告
• PR 摘要和交接
• 策略
• SchemaStore 支持
• GitHub 元数据导入
• 真实仓库试用
• 发布证明
• MCP 服务
• 模板和工具链升级
• GitHub Actions 和 Marketplace Action
• 分发渠道
• 比较

示例

请参阅 examples/，了解生成的工具链和 CI 配方示例：

• 端到端工作流
• Bug 修复 PR
• Next.js 应用
• Node API
• Python 服务
• 仅包含文档的仓库
• 空仓库
• GitHub Actions
• GitLab CI
• Buildkite
• 安全审查
• 依赖升级

请参阅 docs/stack-recipes.md，了解 Next.js、React/Vite、Remix、SvelteKit、Node API、Django、FastAPI、Python、仅包含文档的仓库、空仓库和单体仓库的验证配方。

与纯 AGENTS.md 相比

AGENTS.md 提供说明。AgentLoopKit 则增加了流程产物：任务契约、关卡、策略、验证报告、PR 摘要和回滚说明。

这样更容易审查，因为工作会产出证据，而不仅仅是代码。

与提示词集合相比

提示词集合有助于 Agent 更好地响应。AgentLoopKit 为仓库提供一套常设工作流，兼容的 Agent 可以读取并遵循。

与 Superpowers 相比

Superpowers 是一个涵盖面更广的 Agent 方法论和技能系统。AgentLoopKit 专注于仓库级工程循环、任务契约、验证证据和交接产物。

两者可以互补。你可以将 AgentLoopKit 与 Superpowers 一起使用。AgentLoopKit 与 Superpowers 没有关联。

稳定性

从 1.0 版本开始，AgentLoopKit 发布的功能——CLI 命令和标志、 agentloop.config.json、MCP 工具界面、--json 输出格式、退出 代码以及生成的工具链格式——均属于依据 SemVer 承诺的 公开契约。你可以基于它构建 CI、Agent 工作流或 集成：1.x 版本不会破坏你的使用。

完整契约和命令参考请参阅 docs/stability.md， SemVer 承诺、弃用政策和实验级别规则请参阅 docs/versioning.md。

从 1.0 之前的版本升级？运行 agentloop upgrade-harness，检查 生成的文件是否符合当前格式。

贡献

贡献者环境配置：

git clone https://github.com/abhiyoheswaran1/agentloopkit
cd agentloopkit
pnpm install
pnpm test
pnpm build

本地环境配置和 PR 预期请参阅 CONTRIBUTING.md。

许可证

MIT。