[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-84129":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":16,"stars90d":14,"forks30d":14,"starsTrendScore":17,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":23,"readmeContent":24,"aiSummary":9,"trendingCount":14,"starSnapshotCount":14,"syncStatus":25,"lastSyncTime":26,"discoverSource":27},84129,"Repo-to-Agent-Context","whut09\u002FRepo-to-Agent-Context","whut09","一键把仓库变成 AI 可读、可更新、可验证的上下文包，解决 token 浪费和上下文丢失",null,"TypeScript",101,10,9,0,25,39,89,83.52,false,"main",true,[],"2026-06-12 04:01:42","# Repo-to-Agent-Context\n\n中文 | [English](README.en.md)\n\n把任意仓库压缩成结构化、紧凑、适合 Claude、Codex、Cursor 等 AI 编程 Agent 使用的上下文包。\n\n第一版采用离线优先设计：扫描仓库、提取轻量代码结构、排序关键文件、构建依赖图，并输出 Markdown\u002FJSON 上下文文件，不强依赖大模型。\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fcontext-pack-demo.svg\" width=\"900\" alt=\"Repo-to-Agent-Context 最终输出动画\">\n\u003C\u002Fp>\n\n## 通过 AI Agent 使用\n\n你也可以直接让 Codex、Claude Code、Cursor 或其他编程 Agent 代你运行这个项目。例如在 Codex 里可以直接说：\n\n```txt\n使用 https:\u002F\u002Fgithub.com\u002Fwhut09\u002FRepo-to-Agent-Context 对 xxx 项目生成 AGENTS.md 和 .agent-context 上下文包。请先检查目标仓库结构，再按需安装或克隆该工具。请强制启用 LLM 摘要：在目标仓库创建或更新 repo-context.local.yml，不要提交该文件，优先使用当前 AI 工具环境里可用的模型 API 配置或我提供的 key\u002FbaseUrl\u002Fmodel；如果缺少配置，请先问我。然后运行 repo-context build \u003C目标仓库> --target codex --llm，再运行 repo-context validate \u003C目标仓库>，最后说明生成了哪些文件和 LLM 摘要模式是否成功。\n```\n\n把 `xxx 项目` 替换成本地路径、GitHub 仓库或当前工作区名称即可。如果只需要根目录说明，就说“生成 AGENTS.md”；如果需要完整上下文包，就说“生成 AGENTS.md 和 .agent-context”。\n\n注意：当前 AI 工具必须能提供可调用的模型 API key、base URL 和 model，Repo-to-Agent-Context 才能真正执行 LLM 摘要。如果 Codex\u002FClaude\u002FCursor 没有把自身模型暴露成 API，就让 Agent 先向你索取配置；真实 key 只写入 `repo-context.local.yml`。\n\n## 快速开始\n\n发布到 npm 后可直接运行：\n\n```bash\nnpx repo-to-agent-context build .\u002Fpath\u002Fto\u002Frepo\n```\n\n从源码运行：\n\n```bash\nnpm install\nnpm run build\nnode dist\u002Fcli\u002Findex.js build .\u002Fpath\u002Fto\u002Frepo\n```\n\n开发时可以直接运行：\n\n```bash\nnpm run dev -- build .\u002Fpath\u002Fto\u002Frepo\n```\n\n## 大模型会自动读取 AGENTS.md 吗？\n\n要看你使用的编程工具，而不是大模型本身。`AGENTS.md` 是 Agent 客户端用于把仓库说明注入模型上下文的一种约定。\n\n- 默认生成的 `AGENTS.md` 使用 `agents.mode: minimal`，只保留必须遵守的操作规则、入口文件、必要命令和 `.agent-context\u002F` 索引。\n- 更长的仓库摘要、模块图、依赖图、readiness 和任务包都放在 `.agent-context\u002F`，避免根上下文文件过长。\n- Codex：会。Codex 会在开始工作前读取 `AGENTS.md`，并可以把全局说明和项目级说明合并进上下文。\n- Claude Code：不会直接读取 `AGENTS.md`。Claude Code 的项目说明文件是 `CLAUDE.md`。如果想复用本工具生成的说明，可以在仓库根目录创建 `CLAUDE.md`，内容写 `@AGENTS.md`，再追加 Claude 专用说明。\n- Cursor：支持。把 `AGENTS.md` 放在项目根目录即可作为简单项目规则使用。如果需要按路径作用域、条件触发、多文件规则，建议使用 `.cursor\u002Frules`。\n- 其他工具：支持情况不同。如果工具不会自动加载 `AGENTS.md`，可以在提示词里手动引用或附上该文件。\n\n详细用法见 [docs\u002Fagents-md.zh-CN.md](docs\u002Fagents-md.zh-CN.md)。\n\n## 输出内容\n\n```txt\nAGENTS.md\n.agent-context\u002F\n  repo-summary.md\n  key-files.md\n  module-map.md\n  dependency-graph.md\n  architecture.md\n  onboarding.md\n  readiness.md\n  readiness.json\n  token-savings.md\n  token-savings.json\n  tasks\u002F\n    bugfix-context.md\n    feature-context.md\n    refactor-context.md\n    bugfix.json\n    feature.json\n    refactor.json\n  rag\u002F\n    README.md\n    manifest.json\n    documents.jsonl\n  evidence\u002F\n    file-evidence.json\n  index\u002F\n    files.json\n    symbols.json\n    modules.json\n    chunks.json\n  graphs\u002F\n    dependencies.json\n    dependencies.mmd\n```\n\n## 命令\n\n```bash\nrepo-context init [repo]\nrepo-context build [repo]\nrepo-context graph [repo]\nrepo-context explain \u003Cpath> [repo]\nrepo-context savings [repo]\nrepo-context readiness [repo]\nrepo-context validate [repo]\nrepo-context task \"\u003Ctask>\" [repo]\nrepo-context diff [repo] --base main\nrepo-context update [repo] --since main\nrepo-context rag export [repo]\n```\n\n示例：\n\n```bash\nrepo-context build . --target codex\nrepo-context build . --target codex --tokenizer chars-approx\nrepo-context build . --target codex --model gpt-4.1\nrepo-context build . --llm\nrepo-context build ..\u002Fmy-app --target all --token-budget 80000\nrepo-context explain src\u002Fserver.ts .\nrepo-context explain auth .\nrepo-context readiness .\nrepo-context validate .\nrepo-context savings . --token-budget 60000\nrepo-context savings . --actual --model gpt-4.1\nrepo-context task \"fix login timeout bug\" . --type bugfix --token-budget 12000\nrepo-context diff . --base main\nrepo-context rag export . --token-budget 60000\n```\n\n## Token Savings Report\n\n每次构建都会生成 token 节省报告：\n\n```txt\nOriginal repo (estimated, chars_approx): 2,400,000 tokens\nEstimated context pack (chars_approx): 42,000 tokens\nActual context pack (o200k_base, gpt-4.1): 41,832 tokens\nCompression: 57x\nToken budget: 60,000 (within budget)\n```\n\n报告会区分原始仓库估算、理论紧凑上下文估算，以及实际写出的 Markdown、Mermaid、RAG JSONL token 数。机器可读索引不会计入实际输出 token，具体范围会写在报告里。配置真实 tokenizer 时会用 `js-tiktoken` 计数，无法识别时回退到 `chars_approx`。\n\n生成文件：\n\n- `.agent-context\u002Ftoken-savings.md`\n- `.agent-context\u002Ftoken-savings.json`\n\n## Agent Readiness Score\n\nreadiness 报告是工程诊断分，不是 agent 成功率保证。它会把六类底层信号汇总成三层，并应用硬上限，避免轻易给满分：\n\n```txt\nAgent Readiness: B \u002F 82\n\nDimensions:\n- Operational: 90\u002F100\n- Context Quality: 75\u002F100\n- Agent Safety: 70\u002F100\n\nHard caps:\n- max 90 when no CI workflow is detected\n- max 90 when token counting uses chars_approx instead of a model tokenizer\n- max 85 when no high-confidence AST\u002Fcompiler analyzer evidence exists\n```\n\n生成文件：\n\n- `.agent-context\u002Freadiness.md`\n- `.agent-context\u002Freadiness.json`\n\n## 可选的大模型摘要\n\n大模型是可选能力。CLI 默认离线可用。\n\n提交到仓库的配置只应该保留占位符：\n\n```yaml\nllm:\n  enabled: false\n  provider: openai-compatible\n  baseUrl: xx\n  apiKey: xx\n  model: xx\n```\n\n本地使用时，把 `repo-context.local.example.yml` 复制成 `repo-context.local.yml`，把真实 key 和 URL 写进去。`repo-context.local.yml` 已加入 `.gitignore`，不会被提交。\n\n```yaml\nllm:\n  enabled: true\n  provider: openai-compatible\n  baseUrl: xx\n  apiKey: xx\n  model: xx\n```\n\n然后运行：\n\n```bash\nrepo-context build . --llm\n```\n\n未启用 LLM 时，Repo-to-Agent-Context 使用离线摘要。启用后，如果 key、URL、model 缺失或仍然是 `xx`，会直接给出可操作的配置错误；运行时请求失败则退回离线摘要并记录原因。\n\n运行 `repo-context validate .` 可以检查配置、生成 JSON、依赖边、分析置信度和 token 预算。\n\n## 分析置信度与证据\n\n- TypeScript\u002FJavaScript 使用 TypeScript Compiler API 解析 `import type`、动态 `import()`、re-export、symbol、barrel export、`tsconfig` path alias、workspace package alias，以及常见 Next.js\u002FExpress\u002FFastify\u002FHono\u002FNestJS route 模式。\n- Python 在本机有 Python runtime 时优先使用 stdlib `ast`，失败时回退到轻量解析；支持解析 `from .models import User`、`from app.services.auth import login` 等本地绝对与相对 import。\n- 不支持或 fallback 的分析会标记为低置信度。\n\n每个索引文件包含 `analyzer`、`confidence`、`analysisStats`（parser、resolved\u002Funresolved imports、symbols、routes）和带行号的 `evidence`。汇总证据输出到 `.agent-context\u002Fevidence\u002Ffile-evidence.json`。\n\n## 任务上下文包\n\ntask 模式不是简单关键词文件列表，而是三阶段上下文打包器：\n\n1. 直接检索：匹配 path、module、summary、exports、symbols、tests 和 docs。\n2. 图扩展：加入 direct imports、direct importers、sibling tests、entrypoints、config files 和 owning module docs。\n3. 预算装包：按 direct source、tests、dependency neighbors、config\u002Fdocs、entrypoints 分桶放入 token budget。\n\n```bash\nrepo-context task \"fix login timeout bug\" . --type bugfix --token-budget 12000\nrepo-context task \"add SSO login\" . --type feature\nrepo-context task \"split auth module\" . --type refactor\n```\n\nMarkdown 输出会给 agent `Read First`、`Then Inspect If Needed`、`Why These Files`、`Budget Packing` 和 `Suggested Commands`。机器可读 task pack 会生成在 `.agent-context\u002Ftasks\u002F*.json`。\n\n## 可选 RAG：LightRAG\n\n建议引入 RAG，但不要让 RAG 取代静态上下文包。推荐架构是：\n\n```txt\n先生成静态上下文包\n  -> AGENTS.md、摘要、依赖图、关键文件\n再接可选 RAG 适配层\n  -> 导出 LightRAG 友好的 JSONL，后续再导入 LightRAG Server\n```\n\nRepo-to-Agent-Context 会生成：\n\n- `.agent-context\u002Frag\u002Fdocuments.jsonl`\n- `.agent-context\u002Frag\u002Fmanifest.json`\n- `.agent-context\u002Frag\u002FREADME.md`\n\nLightRAG 保持可选，因为它通常需要单独的 Python\u002FServer 环境，并且索引和查询阶段需要保持 embedding 配置一致。\n\n当前版本会导出适合 LightRAG 摄入的文档，但尚未直接同步到 LightRAG Server。\n\n## 架构\n\n实现设计见 [docs\u002Farchitecture.md](docs\u002Farchitecture.md)，`AGENTS.md` 使用说明见 [docs\u002Fagents-md.zh-CN.md](docs\u002Fagents-md.zh-CN.md)，后续规划见 [docs\u002Froadmap.md](docs\u002Froadmap.md)。\n\n## 配置\n\n创建 `repo-context.config.yml`：\n\n```yaml\ntarget: codex\ntokenBudget: 60000\n\ntokenizer:\n  mode: chars_approx\n  # mode: cl100k_base\n  # model: gpt-4.1\n\nagents:\n  mode: minimal # minimal | balanced | full\n  maxTokens: 1200\n  include:\n    - commands\n    - safety\n    - entrypoints\n    - contextLinks\n\ninclude:\n  - src\u002F**\n  - docs\u002F**\n  - package.json\n\nexclude:\n  - node_modules\u002F**\n  - dist\u002F**\n  - coverage\u002F**\n\noutputs:\n  agents: true\n  modules: true\n  graph: true\n  tasks: true\n  readiness: true\n  rag: true\n```\n\n`agents` 控制根目录 `AGENTS.md` 的信息密度。默认 `minimal` 会把根文件限制成最小操作约束，`balanced`\u002F`full` 才会写入更多概览内容。`outputs` 开关控制可选生成物。关闭开关时，也会清理该分组中之前生成的文件。仓库摘要、关键文件、onboarding、token 节省报告和机器可读索引会始终生成。\n\n## 开发\n\n```bash\nnpm run build\nnpm run check\nnpm test\nnpm pack --dry-run\n```\n",2,"2026-06-11 04:12:20","CREATED_QUERY"]