{"_id":"@codemapai/codemap-ai","_rev":"2-af750df1997622a3fbbff4b2f70280cc","name":"@codemapai/codemap-ai","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@codemapai/codemap-ai","version":"0.1.0","keywords":["ai","code-atlas","codebase","code-graph","onboarding","project-understanding","rag","react","mermaid","monaco-editor"],"author":"","license":"MIT","_id":"@codemapai/codemap-ai@0.1.0","maintainers":[{"name":"codemapai","email":"735313582qq@gmail.com"}],"homepage":"https://github.com/weimin96/codemap-ai#readme","bugs":{"url":"https://github.com/weimin96/codemap-ai/issues"},"bin":{"pfo":"bin/pfo.js","codeatlas":"bin/pfo.js","project-fast-onboarding":"bin/pfo.js"},"dist":{"shasum":"eb7943f89c75cb0e0a80ddabb1575023b4d309ea","tarball":"https://registry.npmjs.org/@codemapai/codemap-ai/-/codemap-ai-0.1.0.tgz","fileCount":76,"integrity":"sha512-d088XNyOd6AbCYSe2MS39OjUObSIDaOjk64SlohO3A8uQw31uWxhgOYM/2JCzddqS7EcdFGja3qy3l/3lTeudA==","signatures":[{"sig":"MEQCIESw5t9Jy9ZxfZqiF0KVgWFMEswhVDlUIosXwaxI0LI2AiAlTWcGZXntw+UXceFdH1Uyyd9HpVzb9LyaffPyJH8efA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":377545},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"9a431c0572a658ef83fd70e6bbe906212238e231","scripts":{"dev":"node bin/pfo.js . --port 3000","lint":"eslint .","test":"node --test server/*.test.js","build":"vite build web --config web/vite.config.ts","start":"node bin/pfo.js .","test:e2e":"playwright test","typecheck":"tsc -p web/tsconfig.json --noEmit","pack:local":"npm pack","prepublishOnly":"npm run typecheck && npm run test && npm run build","release:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"codemapai","email":"735313582qq@gmail.com"},"repository":{"url":"git+https://github.com/weimin96/codemap-ai.git","type":"git"},"_npmVersion":"11.18.0","description":"CodeAtlas local AI project onboarding workbench with code preview, code graph, flow maps, risk radar, and context-bound Q&A.","directories":{},"_nodeVersion":"24.11.1","dependencies":{"ai":"^6.0.0","zod":"^3.24.0","clsx":"^2.1.1","open":"^10.0.0","vite":"^7.0.0","jszip":"^3.10.1","react":"^19.0.0","express":"^5.0.0","mermaid":"^11.0.0","commander":"^14.0.0","cytoscape":"^3.34.0","react-dom":"^19.0.0","typescript":"^5.6.0","tailwindcss":"^4.0.0","lucide-react":"^0.468.0","@ai-sdk/openai":"^2.0.0","tailwind-merge":"^2.5.0","@tailwindcss/vite":"^4.0.0","@monaco-editor/react":"^4.7.0","@vitejs/plugin-react":"^5.0.0","ollama-ai-provider-v2":"^3.6.0","class-variance-authority":"^0.7.1","@ai-sdk/openai-compatible":"^1.0.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"packageManager":"pnpm@10.24.0","devDependencies":{"eslint":"^10.6.0","globals":"^17.7.0","@eslint/js":"^10.0.1","@types/react":"^19.0.0","@playwright/test":"^1.61.1","@types/react-dom":"^19.0.0","typescript-eslint":"^8.62.1"},"_npmOperationalInternal":{"tmp":"tmp/codemap-ai_0.1.0_1783165247046_0.2996262264427516","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@codemapai/codemap-ai","version":"0.2.0","description":"CodeAtlas local AI project onboarding workbench with code preview, code graph, flow maps, risk radar, and context-bound Q&A.","type":"module","packageManager":"pnpm@10.24.0","bin":{"codeatlas":"bin/pfo.js","pfo":"bin/pfo.js","project-fast-onboarding":"bin/pfo.js"},"scripts":{"dev":"node bin/pfo.js . --port 3000","start":"node bin/pfo.js .","build":"vite build web --config web/vite.config.ts","typecheck":"tsc -p web/tsconfig.json --noEmit","test":"node --test server/*.test.js","test:e2e":"playwright test","lint":"eslint .","pack:local":"npm pack","release:dry-run":"npm pack --dry-run","prepublishOnly":"npm run typecheck && npm run test && npm run build"},"engines":{"node":">=20.0.0"},"devDependencies":{"@eslint/js":"^10.0.1","@playwright/test":"^1.61.1","@types/react":"^19.0.0","@types/react-dom":"^19.0.0","eslint":"^10.6.0","globals":"^17.7.0","typescript-eslint":"^8.62.1"},"dependencies":{"@ai-sdk/openai":"^2.0.0","@ai-sdk/openai-compatible":"^1.0.0","@monaco-editor/react":"^4.7.0","@tailwindcss/vite":"^4.0.0","@vitejs/plugin-react":"^5.0.0","ai":"^6.0.0","class-variance-authority":"^0.7.1","clsx":"^2.1.1","commander":"^14.0.0","cytoscape":"^3.34.0","express":"^5.0.0","jszip":"^3.10.1","lucide-react":"^0.468.0","mermaid":"^11.0.0","ollama-ai-provider-v2":"^3.6.0","open":"^10.0.0","react":"^19.0.0","react-dom":"^19.0.0","tailwind-merge":"^2.5.0","tailwindcss":"^4.0.0","typescript":"^5.6.0","vite":"^7.0.0","zod":"^3.24.0"},"keywords":["ai","code-atlas","codebase","code-graph","onboarding","project-understanding","rag","react","mermaid","monaco-editor"],"repository":{"type":"git","url":"git+https://github.com/weimin96/codemap-ai.git"},"bugs":{"url":"https://github.com/weimin96/codemap-ai/issues"},"homepage":"https://github.com/weimin96/codemap-ai#readme","publishConfig":{"provenance":true,"access":"public"},"author":"","license":"MIT","gitHead":"858b128e431aef7b7235f25c29afe3266879fcf3","_id":"@codemapai/codemap-ai@0.2.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-Dh31eICZbkjhqx5tBPnJpUchOwwiBigsI6PeFqDk5oz2+Up3hhjyODMLARtL37g1Tr0LhIYL/kvZKLDSFAwmMA==","shasum":"43b17808b30161264bdff37b8ef4256b6bdf01db","tarball":"https://registry.npmjs.org/@codemapai/codemap-ai/-/codemap-ai-0.2.0.tgz","fileCount":76,"unpackedSize":376694,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@codemapai%2fcodemap-ai@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCRFI4VQzprK1ImcMVhZD4nnT5aY7zPrsnuoBHsxjLqrAIgNogH/oSKFZPiydpS32v6jDFquwpnVtgHPZmMcizPxv0="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:4ab53fe3-4073-44f5-af80-24626399fd8b"}},"directories":{},"maintainers":[{"name":"codemapai","email":"735313582qq@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/codemap-ai_0.2.0_1783165612584_0.9602678104207154"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-04T11:40:46.881Z","modified":"2026-07-04T11:46:52.999Z","0.1.0":"2026-07-04T11:40:47.196Z","0.2.0":"2026-07-04T11:46:52.711Z"},"bugs":{"url":"https://github.com/weimin96/codemap-ai/issues"},"license":"MIT","homepage":"https://github.com/weimin96/codemap-ai#readme","keywords":["ai","code-atlas","codebase","code-graph","onboarding","project-understanding","rag","react","mermaid","monaco-editor"],"repository":{"type":"git","url":"git+https://github.com/weimin96/codemap-ai.git"},"description":"CodeAtlas local AI project onboarding workbench with code preview, code graph, flow maps, risk radar, and context-bound Q&A.","maintainers":[{"name":"codemapai","email":"735313582qq@gmail.com"}],"readme":"

\n \"CODEATLAS\"\n

\n\n

\n \"CodeAtlas\n

\n\n# CodeAtlas\n\n

\n \"npm\n \"npm\n \"CI\"\n \"License\"\n \"Node.js\"\n

\n\n本地项目快速接管工作台。通过 npm 安装后，用命令指定一个本地项目目录，在浏览器里查看项目总览、模块地图、模块详情、核心链路、链路详情、数据模型、风险雷达、代码图谱、代码证据，并基于当前文件、选中代码、符号、链路或风险追问 AI。\n\n> npm 包名为 `@codemapai/codemap-ai`；CLI 已新增 `codeatlas`，并保留 `pfo` / `project-fast-onboarding` 兼容入口。\n\n## 当前版本\n\n当前代码版本：`0.2.0`。\n\n已完成项目理解工作台核心能力：顶部导航、CodeAtlas 品牌字标和 logo、报告质量信息、证据索引、模块详情、链路剧本、风险详情、Graph-aware Context Pack、结构化追问答案、明确失败策略、JS/TS Code Graph、Cytoscape 图谱、通用 ObjectInspector、AI Explain cache、AI JSON repair、人工确认状态字段、测试脚本、CI 和 zip 接管文档导出。\n\n## 品牌资源\n\n- 字标：`web/public/brand/codeatlas-wordmark.svg`\n- Logo：`web/public/brand/codeatlas-logo.svg`\n- 系统复用组件：`web/src/components/BrandMark.tsx`\n- 品牌使用说明：`docs/brand.md`\n- 浏览器 favicon 和系统顶部品牌区已使用该 logo。\n- 字标为纯 SVG 几何笔画，不依赖外部字体。\n\n## 技术栈\n\n- CLI / Server: Node.js + Express\n- Frontend: Vite + React + TypeScript\n- UI: Tailwind CSS + shadcn/ui 风格组件\n- Icons: lucide-react\n- Diagram: Mermaid\n- Code graph visualization: Cytoscape\n- Code Preview: Monaco Editor via `@monaco-editor/react`\n- AI: Vercel AI SDK (`ai`)\n - OpenAI: `@ai-sdk/openai`\n - OpenAI-compatible: `@ai-sdk/openai-compatible`\n - Ollama: `ollama-ai-provider-v2`\n- Schema validation: Zod\n- Test: Node.js built-in test runner\n\n## 安装\n\n```bash\nnpm install -g @codemapai/codemap-ai\n```\n\n本地打包验证：\n\n```bash\nnpm run pack:local\nnpm install -g ./codemapai-codemap-ai-0.2.0.tgz\n```\n\n## 使用\n\n```bash\ncodeatlas /path/to/your/project\n```\n\n指定端口：\n\n```bash\ncodeatlas /path/to/your/project --port 8088\n```\n\n不自动打开浏览器：\n\n```bash\ncodeatlas /path/to/your/project --no-open\n```\n\n默认地址：\n\n```text\nhttp://127.0.0.1:7890\n```\n\n## 开发与验证\n\n```bash\nnpm run dev # 启动本地工作台\nnpm run typecheck # 前端 TypeScript 类型检查\nnpm run test # 服务端单元测试\nnpm run build # Vite 前端生产构建\nnpm run lint # ESLint 静态检查\nnpm run pack:local # 本地 npm pack\n```\n\n发布前会执行：\n\n```bash\nnpm run typecheck && npm run test && npm run build\n```\n\n仓库已提供 GitHub Actions：PR 和 main 分支 push 会执行依赖安装、类型检查、测试和构建；main 分支还会执行 `npm pack --dry-run`。Release workflow 通过 npm Trusted Publishing 发布，不需要在仓库配置 npm token。\n\n## AI 配置\n\n打开页面右上角的 AI 设置，填写 Provider、Base URL、Model 和 API Key。\n\n配置优先级：CLI 参数 / 项目配置 > `pfo.config.json` > 环境变量 > Web UI 保存配置。\n\n### OpenAI-compatible\n\n```text\nProvider: OpenAI Compatible\nBase URL: https://api.openai.com/v1\nModel: gpt-4.1-mini 或其他模型\nAPI Key: sk-...\n```\n\n也支持环境变量：\n\n```bash\nOPENAI_API_KEY=xxx OPENAI_MODEL=gpt-4.1-mini codeatlas /path/to/project\n```\n\n### Ollama\n\n```bash\nollama serve\nollama pull qwen2.5-coder:7b\n```\n\n页面填写：\n\n```text\nProvider: Ollama\nBase URL: http://127.0.0.1:11434/api\nModel: qwen2.5-coder:7b\nAPI Key: 留空\n```\n\n## 工作台页面\n\n- 项目总览：项目定位、技术栈、启动方式、模块数、链路数、风险数和分析质量；分析质量会直接显示未解析 import、未解析 call、parse error 和跳过大文件。\n- 模块地图：按业务模块组织项目结构，进入模块详情查看职责、能力、入口、依赖、数据实体、相关链路、风险和代码证据。\n- 核心链路：查看链路图和步骤，进入链路详情查看时序图、代码剧本、数据读写、外部调用、异常路径、推荐断点、风险和证据。\n- 数据模型：查看实体、关系、状态机、关键字段和数据风险。\n- 风险雷达：查看风险分布，选择风险后查看影响范围、验证步骤、建议测试和代码证据。\n- 代码图谱：查看 JS/TS 文件、目录、符号、导入和近似调用关系，支持范围切换、边过滤、按文件/函数/模块/warning 搜索、warnings-only、邻居高亮、2-hop 影响范围、画布显示范围/排序、业务回链和 Why Connected 最短路径。\n- 代码浏览器：打开证据文件、定位符号和行号，结合右侧追问面板分析代码。\n- 追问历史 / 阅读路线：查看报告生成的阅读计划。\n\n## 当前能力\n\n- 扫描本地项目目录，并识别关键文件、入口候选、模块候选。\n- 基于正则提取 JavaScript / TypeScript / Python / Go / Java 的函数、类、接口、方法和常量。\n- 构建 Repo Map，并按优先级、路径角色、符号数量和文件大小排序。\n- 构建 JS/TS Code Graph，输出 nodes、edges、warnings，边类型包含 `contains`、`defines`、`imports`、`calls`。\n- Code Graph 使用 TypeScript AST 提取 JS/TS imports、exports、require、动态 import 和 CallExpression，再进行本地符号匹配。\n- 图谱页支持 Cytoscape 交互画布和通用 ObjectInspector：概览、解释、为什么有关、告警、代码。\n- Inspector 解释 tab 使用 600ms 延迟触发、切换取消和前端 session cache；服务端会先查 SQLite explain_cache，未命中才请求 AI，成功后写入缓存。\n- Explain 不提供 Explain All；当前支持 Explain selected、Explain neighbors、Explain current flow impact、Explain risk path。\n- Why Connected 通过最短路径解释两个节点为什么有关。\n- 构建 Context Pack，按字符预算选择 AI 分析上下文，并支持导出 `project-context.md`。\n- Context Pack 支持 `overview`、`module`、`flow`、`risk`、`question` mode，并按目标模块、链路、风险、路径、符号和 Code Graph 邻居加权选择上下文。\n- AI 生成项目概览、分析质量、入口、模块、模块能力、核心链路、数据模型、风险、阅读路线、证据索引和 Mermaid 图。\n- AI 分析 prompt 按项目总览、模块分析、链路分析、风险与待验证问题四阶段组织。\n- AI 返回非法 JSON 时会用 repair prompt 重试一次；重试后仍失败才显示错误。\n- 启发式生成 2-5 条核心链路候选，包括 CLI、API、页面和后台任务等常见入口。\n- 链路步骤可绑定文件、符号和行号，并支持点击打开代码位置。\n- 模块详情和链路详情会把判断连接到代码证据。\n- 风险详情包含风险说明、影响范围、验证步骤、建议测试和相关文件。\n- 模块、链路、风险和数据实体已有人工确认状态字段：`ai_guess`、`verified`、`rejected`、`pending`、`stale`。\n- 模块详情、链路详情和风险详情支持更新确认状态，并通过 `/api/verification` 写回本地报告文件。\n- 追问会绑定当前文件、选中行、当前符号、当前链路和当前风险。\n- 追问返回结构化答案：结论、证据、风险、下一步验证动作、相关文件和可信度。\n- 追问历史会按 scope 归档到浏览器 localStorage，包括项目、链路、风险、文件、符号和选区。\n- 在支持 `node:sqlite` 的 Node 运行时，会镜像写入本地 SQLite：scan runs、reports、chat threads、verified conclusions、code graph、explain cache 表。\n- 支持导出 `repo-map.json`、`project-context.md` 和 `/api/onboarding-docs` 接管文档集。\n- 系统顶部“接管文档”按钮会下载 `codeatlas-onboarding-docs.zip` 多文件文档集。\n- `/api/onboarding-docs` 返回 `PROJECT_MAP.md`、`MODULES.md`、`CORE_FLOWS.md`、`DATA_MODEL.md`、`RISK_REGISTER.md`、`READING_PLAN.md`、`QUESTIONS.md`、`CODE_GRAPH_SUMMARY.md`、`ANALYSIS_QUALITY.md`。\n- 支持 OpenAI-compatible、OpenAI、OpenRouter、DeepSeek、Kimi、智谱、SiliconFlow、Ollama 和 Auto fallback。\n- Auto fallback 会按 `ollama,openai-compatible,openrouter,openai` 顺序尝试；可通过 `PFO_AI_PROVIDER_PRIORITY` 覆盖。\n\n## 明确失败策略\n\n系统不把关键错误降级成可继续结果：\n\n- AI 分析和追问必须返回合法 JSON；非法 JSON 只 repair 一次。\n- AI repair 后仍不是合法 JSON，或追问结果字段结构不符合要求时，请求会失败并显示错误。\n- Context Pack、追问上下文和扫描器读取文件失败时会明确报错。\n- `.gitignore` / `pfo.ignore` 只在文件不存在时忽略；其他 IO 错误会中止扫描。\n- 配置文件不存在时使用环境变量；配置文件存在但读取失败、JSON 不合法或解密失败时会明确报错。\n- 前端 API 请求统一校验 HTTP 状态和响应中的 `error` 字段，配置加载失败不会被静默忽略。\n\n## 导出\n\n```bash\n# Repo Map\ncurl http://127.0.0.1:7890/api/repo-map\n\n# Context Pack\ncurl http://127.0.0.1:7890/api/context-pack?format=markdown\n\n# 接管文档集 API\ncurl http://127.0.0.1:7890/api/onboarding-docs\n\n# 或在系统顶部点击“接管文档”，下载 codeatlas-onboarding-docs.zip\n```\n\n接管文档集 API 以 JSON 返回多个 Markdown 文件名和内容；前端会打包为 zip，适合放入项目仓库或团队交接目录。\n\n## 设计取向\n\n这个工具不是普通 AI coding assistant，而是“项目接管工作台”：\n\n1. 先生成第一版地图。\n2. 再进入模块或链路详情，查看职责、剧本和证据。\n3. 然后通过代码图谱检查真实导入、近似调用关系、范围过滤、邻居高亮、业务回链和解析告警。\n4. 接着围绕当前文件、函数、链路或风险追问。\n5. 最后由人基于代码、断点、日志和测试验证。\n\n## 安全说明\n\nAPI Key 优先可通过环境变量提供。通过页面保存时，配置写入本机用户目录 `~/.project-fast-onboarding/config.json`。\n\n本地保存的 API Key 会使用 Node.js `crypto` 进行 AES-256-GCM 加密，密钥保存在同一配置目录下的本地密钥文件中。该方案用于避免配置文件直接出现明文 API Key；如果攻击者已经获得同一系统用户的文件读取权限，仍可能同时读取密文和密钥文件。\n\n## 当前限制\n\n- 产品展示名、README 标题、系统顶部品牌和主 CLI 已统一为 CodeAtlas；npm 包名已迁移为 `@codemapai/codemap-ai`。\n- 符号索引当前使用正则实现，不是 Tree-sitter AST 级索引。\n- Code Graph 目前只支持 JS/TS 图谱层；Python / Go / Java 仍只有符号索引。\n- `calls` 已改为 TypeScript AST CallExpression 提取，但目标解析仍基于名称匹配，无法覆盖动态调用、别名、重导出和复杂类型推断。\n- 核心链路仍是候选链路，不是完整精确调用图。\n- Context Pack 使用字符预算近似 token 预算。\n- Graph-aware Context Pack 会使用 Code Graph 邻居和 warning 加权，但仍不是完整本地 RAG 或类型系统级调用图。\n- 模块、链路、风险和数据实体的人工确认状态已支持 UI 更新并写回本地报告。\n- SQLite 镜像持久化依赖运行时支持 `node:sqlite`；Node 20 环境会自动跳过，不阻断主流程。\n- `/api/onboarding-docs` 已提供前端合并 Markdown 下载；暂未提供 zip 批量下载。\n- `test:e2e` 已接入 Playwright，包含工作台 smoke 用例；CI 会安装 Chromium 后执行。\n- `lint` 已接入 ESLint；当前关闭了 `preserve-caught-error` 和 `no-useless-escape`，避免把既有错误包装和正则写法变成大范围重构。\n- release workflow 已提供 npm Trusted Publishing 发布入口，真实发布依赖 npm 包侧配置匹配的 Trusted Publisher。\n- 多模型 fallback 已支持 `provider=auto`，但每个 provider 的独立 API Key / model UI 尚未展开。\n- 暂未支持多人协作或远程仓库托管。\n\n下一版建议：TypeScript 类型系统级调用解析、更完整 Playwright 关键路径测试、SQLite 查询 UI、多人协作。\n","readmeFilename":"README.md"}