agent-ready-kit

Make any repository easier for AI coding agents to understand, edit, and verify.

扫描仓库，生成 Agent 工作材料，让 Codex、Claude Code、Cursor 少猜命令、少改错文件、少漏验证。

Default path: no model signup and no API key required.

默认使用路径不需要注册模型平台，也不需要用户自己申请 API Key。

agent-ready-kit is a CLI and GitHub Action for preparing repositories for AI coding agents. It scans a local folder or GitHub URL, finds the commands and project signals agents usually have to guess, then generates practical outputs: AGENTS.md, readiness reports, task cards, guard rules, before/after notes, action plans, and a CI gate.

agent-ready-kit 是一个帮仓库适配 AI 编码代理的 CLI 和 GitHub Action。它可以扫描本地目录或 GitHub URL，找出 Agent 经常需要靠猜的信息，然后生成可直接使用的产物：AGENTS.md、就绪度报告、任务卡、guard rules、前后对比、行动计划和 CI 门禁。

In plain language, it does three useful things:

• Scans the repo: detects install/test/build scripts, CI, repo structure, agent docs, safety risks, and onboarding gaps.
• Generates agent-ready files: writes AGENTS.md, reports, task cards, guard rules, before/after notes, and action plans.
• Improves AI edits: gives coding agents the commands, boundaries, and validation checklist before they touch code.

简单说，它做三件事：

• 扫描仓库： 识别安装、测试、构建脚本、CI、项目结构、Agent 文档、安全风险和上手缺口。
• 生成材料： 写出 AGENTS.md、报告、任务卡、guard rules、前后对比和行动计划。
• 提升 AI 改代码质量： 在 Agent 动手前给它命令、边界和验证清单。

After using it, an LLM coding agent is less likely to guess the wrong command, edit the wrong layer, touch generated files, or skip verification.

用了之后，大模型更不容易猜错命令、改错层级、碰到生成物，或者忘记验证步骤。

By default, recommendations use a managed LLM path with no model signup or API key required. Local-only mode is still available for privacy, outages, or other fallback cases.

默认建议会走免注册、免 API Key 的托管大模型路径；如果有隐私、网络故障或其他兜底需求，也可以切到纯本地模式。

After You Run It / 用了之后有什么优势

• LLM agents know the correct install, test, build, and validation commands.

• They see the project entrypoints and important directories before editing.

• They get explicit boundaries for generated files, risky paths, and files that should not be touched casually.

• Reviewers spend less time repeating "run this check" or "do not edit that folder".

• CI can use the same rules to block low-context changes before they become team friction.

• 大模型知道正确的安装、测试、构建和验证命令。

• 大模型在改代码前能先看到项目入口和关键目录。

• 生成文件、高风险路径、不要随便改的文件会被明确写出来。

• Reviewer 不用反复提醒“跑这个检查”“别改那个目录”。

• CI 可以复用同一套规则，在低上下文改动进入团队流程前先拦住。

Real Repository Showcase / 真实仓库示例

Want to see what the tool finds on large real repositories?

想看它跑在真实大仓库上是什么效果？

See docs/showcase for scans of React, Next.js, TypeScript, and Node.js.

查看 docs/showcase，里面有 React、Next.js、TypeScript 和 Node.js 的真实扫描结果。

What Problem Does It Solve / 解决什么问题

AI coding agents often fail for boring reasons:

• They cannot find the right install or test command.
• They do not know which folders are generated, risky, or off-limits.
• They miss the project structure and edit the wrong layer.
• Reviewers have to repeat the same safety and verification comments.

AI 编码代理经常不是因为模型不够强才出错，而是因为仓库没有把工作规则讲明白：

• 安装、构建、测试命令在哪里？
• 哪些目录是生成物、高风险区域或不要手改的内容？
• 项目结构是什么，应该优先看哪些文件？
• 改完以后要跑什么检查，PR 里应该怎么守住质量？

agent-ready-kit turns those missing rules into context that LLM agents can actually use.

agent-ready-kit 会把这些“没讲清的规则”变成大模型真正能用的仓库上下文。

What You Get / 跑完会得到什么

Output	What it is for	中文说明
Agent Ready Score	A 0-100 score across docs, tests, scripts, CI, repo map, safety, and onboarding.	从文档、测试、脚本、CI、仓库地图、安全、上手体验给出 0-100 分。
.agent-ready/scan.json	Full machine-readable scan result with LLM status, recommendations, score, and findings.	包含大模型状态、建议、分数和发现的完整机器可读结果。
.agent-ready/before-after.md	Explains what was unclear before the scan and what becomes visible after it.	说明扫描前看不清什么、扫描后多了哪些可见信息。
.agent-ready/action-plan.md	Prioritized fix plan grouped by severity.	按严重程度整理的修复优先级计划。
AGENTS.md	Repo-specific instructions for coding agents.	给 AI 编码代理看的仓库说明书。
.agent-ready/report.md	Bilingual readiness report with findings and fixes.	双语就绪度报告，列出问题和修复建议。
.agent-ready/tasks/*.md	Concrete task cards for improving weak spots.	把薄弱项拆成可以执行的任务卡。
.agent-ready/guards.json	Machine-readable guard rules for automation.	机器可读的守护规则，方便接入自动化。
GitHub Action gate	CI check that can fail PRs below a minimum score.	在 PR 里设置最低就绪度门禁。
LLM recommendations	Smarter suggestions from bounded repo evidence. Uses the managed no-key endpoint by default, with BYOK and local fallback options.	基于有限仓库证据生成更聪明的建议。默认免 key 托管端点，也支持自带 key 和本地兜底。

Quick Start / 快速开始

The default command scans the repo, writes clear findings, and asks the managed LLM for practical recommendations. Common users do not need to create a model account or API key.

默认命令会扫描仓库、输出明确发现，并通过托管大模型生成实用建议。普通用户不需要创建模型账号或申请 API Key。

Scan the current repository:

扫描当前仓库：

cd your-repository
npx @chent6767/agent-ready-kit

Generate a shareable scan bundle:

生成可分享扫描产物：

npx @chent6767/agent-ready-kit . --out .agent-ready

Scan a GitHub repository directly:

直接输入 GitHub 仓库网址扫描：

npx @chent6767/agent-ready-kit https://github.com/chen9965/agent-ready-kit --out .agent-ready

LLM recommendations are attempted automatically through the managed endpoint. No model signup is needed for the common path.

大模型建议会自动优先走托管端点；普通用户不需要先注册模型平台。

npx @chent6767/agent-ready-kit .

Generate agent-facing files:

生成 Agent 可读文件：

npx @chent6767/agent-ready-kit init . --write

Open an HTML report:

打开本地 HTML 报告：

npx @chent6767/agent-ready-kit report . --open

GitHub source install also works:

也可以直接从 GitHub 源码运行：

npx github:chen9965/agent-ready-kit .

Typical Workflow / 典型用法

1. Run agent-ready . to see why a repository is hard for agents to work in.

2. Run init . --write to generate AGENTS.md, task cards, guard rules, and a report.

3. Commit the useful generated files.

4. Add the GitHub Action gate so future PRs do not silently lose agent readiness.

5. 先运行 agent-ready .，看仓库为什么不适合 Agent 接手。

6. 再运行 init . --write，生成 AGENTS.md、任务卡、守护规则和报告。

7. 把有价值的生成文件提交到仓库。

8. 加上 GitHub Action 门禁，避免后续 PR 把 Agent 协作体验改坏。

What It Checks / 它会检查什么

Area	Signal examples	中文说明
Docs	README.md, setup notes, project overview	有没有基础文档、安装说明和项目介绍。
Tests	test files, package.json test script, Python test files	有没有测试文件或测试命令。
Scripts	build, test, check, dev, package manager signals	有没有明确的构建、测试、检查、开发脚本。
CI	.github/workflows/*	PR 或主分支有没有自动验证。
Repo map	repo map, architecture notes, structure sections	有没有仓库地图或架构说明。
Safety	.gitignore, possible secret-like files, large dense files	有没有忽略规则、疑似密钥、高风险大文件。
Onboarding	AGENTS.md and agent-specific rules	有没有给 Agent 的工作说明。

The scanner reads repository shape, docs, scripts, and lightweight file evidence locally, then uses that bounded evidence to generate better recommendations. The CLI tries the maintainer-hosted managed endpoint by default, retries with summary-only context if needed, and can fall back to deterministic local output for outages or privacy-sensitive use. It still does not claim to review every line like a full human reviewer.

扫描器会在本地读取仓库结构、文档、脚本和轻量文件证据，再基于这些有限证据生成更好的建议。CLI 默认请求维护者托管端点，必要时会用摘要模式重试；如果服务不可用，或用户有隐私需求，也可以退回本地确定性输出。它仍然不会假装完整审查了每一行代码。

Managed LLM Mode / 托管大模型模式

By default, agent-ready-kit can use a managed LLM path for better recommendations:

默认情况下，agent-ready-kit 会使用托管大模型生成更好的建议：

• file tree
• entrypoint candidates
• test candidates
• short excerpts from selected config/source files

它发送的内容包括：文件树、入口候选、测试候选，以及少量配置和源码片段。

It sends only bounded context and skips obvious secret-like paths and content. Use --no-llm only when you deliberately need local-only emergency mode.

它只使用有限上下文，并跳过明显像密钥的路径和内容。只有明确需要纯本地应急模式时，才使用 --no-llm。

Default managed endpoint:

默认托管端点：

https://agent-ready-kit-llm.agent-ready-kit.workers.dev/v1/recommend

Use your own managed endpoint:

使用自己的托管端点：

$env:AGENT_READY_LLM_MANAGED_URL="https://your-worker.example/v1/recommend"
npx @chent6767/agent-ready-kit .

Fallback and privacy controls:

兜底和隐私控制：

npx @chent6767/agent-ready-kit . --no-managed-llm
npx @chent6767/agent-ready-kit . --no-llm

Prefer bringing your own key before turning LLM off:

优先自带 key，而不是直接关闭大模型：

$env:AGENT_READY_LLM_PROVIDER="agnes"
$env:AGENT_READY_LLM_API_KEY="your_agnes_key"
npx @chent6767/agent-ready-kit . --markdown

$env:AGENT_READY_LLM_API_KEY="your_openrouter_key"
npx @chent6767/agent-ready-kit . --markdown

Defaults:

默认值：

• AGENT_READY_LLM_MANAGED_URL=https://agent-ready-kit-llm.agent-ready-kit.workers.dev/v1/recommend
• AGENT_READY_LLM_BASE_URL=https://openrouter.ai/api/v1
• AGENT_READY_LLM_MODEL=openrouter/free

Agnes preset:

Agnes 预设：

• AGENT_READY_LLM_PROVIDER=agnes
• AGENT_READY_LLM_BASE_URL=https://apihub.agnes-ai.com/v1
• AGENT_READY_LLM_MODEL=agnes-2.0-flash

Mainland China-friendly preset:

国内更容易访问的预设：

$env:AGENT_READY_LLM_PROVIDER="siliconflow"
$env:AGENT_READY_LLM_API_KEY="your_siliconflow_key"
npx @chent6767/agent-ready-kit .

This sets:

对应默认值：

• AGENT_READY_LLM_BASE_URL=https://api.siliconflow.cn/v1
• AGENT_READY_LLM_MODEL=Qwen/Qwen3-8B

You can override any OpenAI-compatible endpoint:

也可以接入任意 OpenAI 兼容服务：

$env:AGENT_READY_LLM_BASE_URL="https://your-provider.example/v1"
$env:AGENT_READY_LLM_MODEL="provider/model-name"
$env:AGENT_READY_LLM_API_KEY="your_key"
npx @chent6767/agent-ready-kit .

Privacy controls:

隐私控制：

npx @chent6767/agent-ready-kit . --llm-summary
npx @chent6767/agent-ready-kit . --no-managed-llm
npx @chent6767/agent-ready-kit . --no-llm
npx @chent6767/agent-ready-kit . --llm-max-files 12 --llm-max-chars 18000

Maintainers can deploy the proxy template in examples/managed-llm-worker.

维护者可以用 examples/managed-llm-worker 里的模板部署自己的代理。

GitHub Action / GitHub Actions 用法

Add an agent-readiness gate to pull requests:

给 PR 加一个 AI 代理就绪度门禁：

name: Agent Ready

on:
  pull_request:

jobs:
  score:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: chen9965/agent-ready-kit@v0.6.5
        with:
          min-score: 70

The action uses managed LLM recommendations by default, writes a bilingual Markdown report to the GitHub Actions step summary, and fails when the score is below min-score. Set llm: false only when you need local-only fallback mode.

Action 默认使用托管大模型建议，会在 GitHub Actions Step Summary 里写入双语报告；分数低于 min-score 时失败。只有需要纯本地兜底模式时才设置 llm: false。

Commands / 命令

Command	What it does	中文说明
agent-ready [path]	Scans the repo, scores docs, tests, scripts, CI, repo map, safety, and onboarding, then adds LLM recommendations when available.	扫描仓库，为文档、测试、脚本、CI、仓库地图、安全和上手体验评分，并在可用时加入大模型建议。
agent-ready https://github.com/owner/repo	Clones a GitHub repository into a temp directory and scans it.	自动浅克隆 GitHub 仓库到临时目录后扫描。
agent-ready [path] --out .agent-ready	Writes scan.json, report.md, before-after.md, and action-plan.md.	写入 scan.json、report.md、before-after.md 和 action-plan.md。
agent-ready [path] --markdown --fail-under 70	Prints a Markdown report and exits with code 1 below a score.	输出 Markdown 报告，低于指定分数时返回失败。
agent-ready [path] --no-managed-llm	Skips the maintainer-hosted model proxy.	跳过维护者托管模型代理。
agent-ready [path] --llm-summary	Uses only scan summary for LLM recommendations.	只把扫描摘要发给大模型。
agent-ready [path] --no-llm	Forces deterministic local-only emergency mode.	强制进入纯本地应急模式。
agent-ready init [path] --write	Generates AGENTS.md, .agent-ready/tasks/*.md, .agent-ready/guards.json, and .agent-ready/report.md.	生成代理说明、任务卡、守护规则和 Markdown 报告。
agent-ready report [path] --open	Writes and opens a local HTML report.	生成并打开本地 HTML 报告。

Why This Is Useful / 优点在哪里

agent-ready-kit is useful when you want LLM coding agents to start with the right repo context instead of guessing.

当你希望大模型先看懂仓库，再开始改代码，而不是让 Agent 盲猜时，这个工具就有价值。

• Less guessing: agents get commands, entrypoints, boundaries, and validation steps up front.

• Fewer wrong edits: generated, risky, or off-limits areas are called out before the model starts editing.

• Faster review: repeated reviewer comments become agent-facing rules and task cards.

• Smarter recommendations: bounded repo evidence is sent to a managed LLM by default, with no user API key required.

• Zero-config LLM path: the CLI first tries a maintainer-hosted proxy, so users do not need a model account.

• Local fallback: users can still force deterministic scanning with --no-llm, mainly for privacy or outage fallback.

• Agent-specific: output is written for coding agents, not only human readers.

• Actionable: weak spots become task cards and guard rules.

• CI-friendly: the same score can become a pull request gate.

• Provider-agnostic: BYOK mode works with OpenAI-compatible providers.

• 少猜： Agent 一开始就知道命令、入口、边界和验证步骤。

• 少改错： 生成物、高风险目录、不要乱碰的区域会提前写清楚。

• Review 更省事： 反复提醒的规则会变成 Agent 可读说明和任务卡。

• 建议更聪明： 默认把有限仓库证据交给托管大模型生成建议，用户不需要自己准备 API Key。

• 零配置大模型路径： CLI 优先尝试维护者托管代理，用户不需要先注册模型账号。

• 本地兜底： 用户仍然可以用 --no-llm 强制只做确定性扫描，主要用于隐私或故障兜底。

• 面向 Agent： 输出不是普通文档，而是给编码代理看的工作规则。

• 可执行： 薄弱项会变成任务卡和 guard rules。

• 适合 CI： 同一个分数可以变成 PR 门禁。

• 不绑模型： 自带 key 模式兼容 OpenAI 风格接口。

Before and After / 使用前后

Before:

• Agents guess setup commands.
• Agents miss repo boundaries and edit generated or risky files.
• Reviewers repeat the same "please run tests" and "do not touch this folder" comments.

使用前：

• Agent 只能猜安装和验证命令。
• Agent 容易错过仓库边界，改到生成物或高风险目录。
• Review 里反复出现“请跑测试”“别碰这个目录”。

After:

• LLM agents start with model-generated repo context, repo-specific commands, and working rules.
• AGENTS.md tells agents what to inspect, what to avoid, and how to verify.
• .agent-ready/tasks/ turns missing context into concrete follow-up work.
• .agent-ready/guards.json gives automation a stable policy shape.
• --out writes scan.json, report.md, before-after.md, and action-plan.md for sharing or CI.

使用后：

• 大模型一开始就拿到模型整理过的仓库上下文、仓库专属命令和工作规则。
• AGENTS.md 告诉 Agent 先看哪里、避开什么、怎么验证。
• .agent-ready/tasks/ 把缺失上下文变成具体任务。
• .agent-ready/guards.json 给自动化系统稳定策略格式。
• --out 写出 scan.json、report.md、before-after.md 和 action-plan.md，方便分享或接入 CI。

Example Output / 输出示例

Agent readiness / 代理就绪度: good 78/100
Stack / 技术栈: Node.js, React, TypeScript, Vite

Top findings / 主要发现
WARN Add CI / 添加 CI
  Add a workflow that runs install, typecheck/lint, and tests on pull requests.
  添加工作流，在 PR 上运行安装、类型检查或 lint、测试。

Artifacts written / 扫描产物已生成: .agent-ready
- .agent-ready/scan.json
- .agent-ready/report.md
- .agent-ready/before-after.md
- .agent-ready/action-plan.md

Comparison / 对比

Tool type	Focus	agent-ready-kit difference	区别
Linter	Code style and syntax problems	Prepares repo context for LLM agents before they edit.	给大模型补仓库上下文，而不只是检查代码风格。
README generator	Human-facing documentation	Generates agent instructions, task cards, guard rules, reports, and CI-ready artifacts together.	不是写好看的 README，而是生成 Agent 工作材料。
AI wrapper	Calling a model	Helps the model understand the repo before asking it to change code.	不是套一层模型，而是先让模型看懂仓库规则。
Project template	Starting a new repo	Works on existing repositories and makes their rules explicit for agents.	适合已有仓库，把隐含规则整理给 Agent。

Config / 配置

Create agent-ready.config.json:

创建 agent-ready.config.json：

{
  "ignore": ["fixtures/**"],
  "agentTargets": ["Codex", "Claude Code", "Cursor"],
  "riskLevel": "medium",
  "outputDir": ".agent-ready"
}

Development / 开发

npm install
npm run build
npm test
npm run smoke

Roadmap / 路线图

• PR comment mode for richer review feedback.

• More stack detectors: Go, Rust, Java, .NET, Lua.

• JSON schema export for guards.json.

• VS Code task integration.

• PR 评论模式，让审查反馈更直接。

• 更多技术栈检测：Go、Rust、Java、.NET、Lua。

• 导出 guards.json 的 JSON Schema。

• VS Code task 集成。

License / 许可证

MIT