HarmanPreet-Singh-XYT/codilay

# 🦅 CodiLay [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](CONTRIBUTING.md) CodiLay 不仅仅是一个静态文档生成器；它是一个**智能体文档研究员**。它阅读你的代码，通过 **The Wire Model** 理解模块连接，并维护一个持久的、可搜索的知识库，你可以通过 Web UI 浏览它，或通过交互式 Chat 与之对话。 ## 🚀 体验 CodiLay ### 1. 安装 **从 PyPI 安装（推荐）** ``` # 基础安装 pip install codilay # 安装所有功能 (Web UI + Watch mode) pip install "codilay[all]" # 全局 CLI 安装（推荐） pipx install codilay ``` **从源码安装** ``` # 克隆仓库 git clone https://github.com/HarmanPreet-Singh-XYT/codilay.git cd codilay # 安装 Web UI 支持 pip install -e ".[serve]" # 安装 Watch mode 支持 pip install -e ".[watch]" # 安装所有内容 (Web UI + Watch mode) pip install -e ".[all]" ``` ### 2. 首次设置 无需每次都导出 API keys。运行设置向导以安全地存储你的密钥。 ``` codilay setup ``` ``` codilay ``` 运行不带参数的 `codilay` 会打开 **交互控制中心**，允许你管理项目、配置 provider 和启动扫描，而无需记忆各种 flags。 ## 🛠 功能特性 ### 🧠 The Wire Model CodiLay 将每一个 import、函数调用和变量引用视为一个 **Wire**。 - **Open Wires**：Agent 正在“追捕”的未解析引用。 - **Closed Wires**：成功追踪到的连接，构成了依赖图的片段。 ### ⚡️ 智能分流 (Smart Triage) 在消耗 tokens 之前，CodiLay 会执行高速的 **Triage Phase**。它将文件分类为： - **Core**：完整的架构分析和文档。 - **Skim**：仅元数据和签名（节省简单工具的 tokens）。 - **Skip**：忽略样板代码、生成代码和平台特定的噪音。 ### 🔄 Git 感知增量更新 CodiLay 具有 repo 感知能力。如果你在一个 500 个文件的项目中只修改了 2 个文件，`codilay .` 将会： 1. 通过 Git 检测变动 (delta)。 2. 仅使受影响的文档部分失效。 3. 重新打开与更改代码相关的 wires。 4. 重新计算局部影响，以保持你的 `CODEBASE.md` 是最新的。 ### 💬 交互式聊天与记忆 使用 `codilay chat .` 询问关于代码库的问题。 - **RAG + Deep Search**：它利用文档快速回答，但可以“升级”到阅读源代码以获取实现细节。 - **Memory**：Agent 会在会话之间记住你的偏好和关于代码库的事实。 - **Promote to Doc**：在聊天中找到了很棒的解释？使用 `/promote` 将 AI 的回答转化为文档的永久部分。 ### 🌐 Web 文档浏览器 Web UI 不仅仅是一个阅读器——它是一个交互式智能层。 - **Layer 1: The Reader**：高保真渲染你的章节和图表。 - **Layer 2: The Chatbot**：基于文档上下文的快速问答。 - **Layer 3: The Deep Agent**：深入源代码以核实事实。 ``` codilay serve . ``` ### 👁 观察模式 在后台运行 CodiLay，并在文件更改时自动更新文档。使用文件系统事件（通过 watchdog）及可配置的去抖动 (debouncing) 来避免冗余重跑。 ``` # 监控当前目录，保存时自动更新 codilay watch . # 自定义 debounce 延迟（5秒） codilay watch . --debounce 5 # 用于调试的 Verbose 输出 codilay watch . -v ``` ### 🧩 IDE 集成 (VSCode Extension) 一个 VSCode 扩展，可以在你编辑的文件旁边内联显示文档。功能包括： - 所有文档部分的**侧边栏树状视图** - 显示当前文件完整文档的 **Webview 面板** - 高亮显示已记录符号的**内联装饰** - 用于提问、查看图表和搜索对话的**快速命令** 从 `vscode-extension/` 目录安装 —— 详见扩展 README。 ### 🤖 AI 上下文导出 以紧凑、token 高效的格式导出文档，专为输入到另一个 LLM 的上下文窗口而设计。支持 markdown、XML 和 JSON 格式，并可设置可选的 token 预算。 ``` # 导出为紧凑 Markdown（默认） codilay export . # 导出为 XML，预算为 4000-token codilay export . --format xml --max-tokens 4000 # 导出为 JSON，排除 dependency graph codilay export . -f json --no-graph -o context.json ``` ### 📊 文档差异对比 查看两次运行之间文档发生变化的逐章节变更日志。与 `codilay diff`（显示 git 级别的文件更改）不同，`diff-doc` 比较实际的文档内容。 ``` # 显示自上次运行以来文档的变更 codilay diff-doc . # 输出为 JSON 以供编程使用 codilay diff-doc . --json-output ``` 快照会在每次 `codilay run` 后自动保存，因此差异对比始终可用。 ### 🎯 分流微调 标记错误的分流决策以改进未来的运行。修正内容按项目存储，并在后续运行的分流阶段自动应用。 ``` # 标记一个已略过但应为核心文件 codilay triage-feedback add . src/auth/handler.py skim core -r "Contains critical auth logic" # 标记一个模式（基于 glob） codilay triage-feedback add . "tests/**" core skip --pattern -r "Tests should be skipped" # 列出所有存储的反馈 codilay triage-feedback list . # 设置项目类型提示 codilay triage-feedback hint . react "Treat all hooks/ files as core" # 移除特定文件的反馈 codilay triage-feedback remove . src/auth/handler.py # 清除所有反馈 codilay triage-feedback clear . --yes ``` ### 🔍 图表过滤器 按 wire 类型、文件层、模块或连接数过滤依赖图。对于减少大型仓库中的噪音至关重要。 ``` # 仅显示 import-type wires codilay graph . --wire-type import # 过滤到特定目录层 codilay graph . --layer src/api # 仅显示具有 3 个以上连接的节点，仅限 outgoing edges codilay graph . --min-connections 3 --direction outgoing # 组合过滤器，排除测试 codilay graph . -w import -l src/core -x "tests/**" # 列出项目可用的过滤器值 codilay graph . --list-filters # 输出为 JSON codilay graph . --json-output ``` ### 🧠 团队记忆 供在同一项目上工作的团队使用的共享知识库。记录事实、架构决策、编码约定和文件注释 —— 所有内容按项目存储，并在文档生成和聊天期间提供给 AI。 ``` # 添加团队成员 codilay team add-user . alice --display-name "Alice Chen" # 记录事实 codilay team add-fact . "We use Celery for async tasks" -c architecture -a alice -t backend -t infra # 对事实投票 codilay team vote . up # 记录架构决策 codilay team add-decision . "Use PostgreSQL over MySQL" "Better JSON support, needed for our schema" -a alice -f src/db/ # 添加编码约定 codilay team add-convention . "Error Handling" "All API endpoints must return structured error responses" -e '{"error": "message", "code": 400}' -a alice # 注释特定文件 codilay team annotate . src/api/routes.py "This file is getting too large, plan to split by domain" -a alice -l 1-50 # 列出所有内容 codilay team facts . # All facts codilay team facts . -c architecture # Facts by category codilay team decisions . # All decisions codilay team decisions . -s active # Active decisions only codilay team conventions . # All conventions codilay team annotations . # All annotations codilay team annotations . -f src/api/routes.py # Per-file codilay team users . # All members ``` ### 🔎 对话搜索 对所有过去聊天对话的全文搜索 —— 不仅仅是当前会话。使用带有 TF-IDF 评分的倒排索引，实现快速、相关的结果。 ``` # 搜索所有对话 codilay search . "authentication flow" # 前 5 个结果，仅限 assistant 消息 codilay search . "error handling" --top 5 --role assistant # 在特定对话中搜索 codilay search . "database migration" -c # 重建索引（在手动编辑 chat 文件后） codilay search . "query" --rebuild ``` ### 📅 定时重新运行 按 cron 计划或当分支上有新提交时自动触发文档更新。作为后台守护进程运行，并带有 PID 文件管理。 ``` # 每天凌晨 2 点更新文档 codilay schedule set . --cron "0 2 * * *" # 在每次提交到 main 时更新 codilay schedule set . --on-commit --branch main # 组合：cron + commit 触发器 codilay schedule set . --cron "0 2 * * *" --on-commit # 检查当前计划 codilay schedule status . # 启动 scheduler（前台） codilay schedule start . # 启动并开启 verbose 日志 codilay schedule start . -v # 停止运行中的 scheduler codilay schedule stop . # 禁用计划 codilay schedule disable . ``` ## ⌨️ CLI 参考 | 命令 | 操作 | |:---|:---| | `codilay` | 启动 **交互菜单** | | `codilay .` | 文档化当前目录（增量） | | `codilay chat .` | 启动关于项目的 **Chat 会话** | | `codilay serve .` | 启动 **Web UI** | | `codilay status .` | 显示文档覆盖率和过期部分 | | `codilay diff .` | 查看自上次运行以来文件的变化 | | `codilay setup` | 配置默认 provider、model 和 API keys | | `codilay keys` | 管理存储的 API keys | | `codilay clean .` | 清除所有生成的产物 | | `codilay watch .` | 监视文件变化，自动更新文档 | | `codilay export .` | 以 AI 友好格式导出文档 | | `codilay diff-doc .` | 显示运行之间的章节级文档差异 | | `codilay triage-feedback` | 管理分流修正 | | `codilay graph .` | 查看和过滤依赖图 | | `codilay team` | 管理共享团队知识 | | `codilay search . "query"` | 对所有过去对话进行全文搜索 | | `codilay schedule` | 配置并运行定时文档更新 | ## ⚙️ 项目配置 在根目录下放置一个 `codilay.config.json` 以定义项目特定行为： ``` { "ignore": ["dist/**", "**/tests/**"], "notes": "This is a React/Next.js frontend using Tailwind.", "instructions": "Focus on data-fetching patterns and state management.", "entryHint": "src/main.py", "llm": { "provider": "anthropic", "model": "claude-3-5-sonnet-latest", "baseUrl": "https://api.anthropic.com", "maxTokensPerCall": 4096 }, "triage": { "mode": "smart", "includeTests": false, "forceInclude": ["critical_logic/*.py"], "forceSkip": ["legacy_v1/*.js"] }, "chunking": { "tokenThreshold": 6000, "maxChunkTokens": 4000, "overlapRatio": 0.10 }, "parallel": { "enabled": true, "maxWorkers": 4 } } ``` ### 📋 配置字段 | 类别 | 键 | 类型 | 描述 | |:---|:---|:---|:---| | **General** | `ignore` | `List[str]` | 用于从扫描中排除文件/文件夹的 Glob 模式。 | | | `notes` | `str` | 提供给 AI 的高层项目上下文。 | | | `instructions` | `str` | 特定的文档风格或领域指令。 | | | `entryHint` | `str` | 指向主入口文件以帮助追踪 wires。 | | | `skipGenerated` | `List[str]` | 可选覆盖，用于默认的生成文件/锁文件忽略规则。 | | **LLM** | `provider` | `str` | AI provider (如 `anthropic`, `openai`, `google`, `ollama`)。 | | | `model` | `str` | 模型标识符 (如 `claude-3-5-sonnet-latest`)。 | | | `baseUrl` | `str` | 自定义 API base URL (适用于本地模型或代理)。 | | | `maxTokensPerCall`| `int` | 每次 agent 调用的最大输出 tokens。 | | **Triage** | `mode` | `str` | 默认分类策略 (`smart`, `core`, `skim`, `skip`)。 | | | `includeTests` | `bool` | 是否处理测试文件 (默认为 `false`)。 | | | `forceInclude` | `List[str]` | 总是视为 **Core** 文档的模式。 | | | `forceSkip` | `List[str]` | 总是忽略的模式。 | | **Chunking** | `tokenThreshold` | `int` | 大于此值（以 tokens 计）的文件将被拆分成块。 | | | `maxChunkTokens` | `int` | 每个细节块的目标 token 数。 | | | `overlapRatio` | `float` | 块之间的上下文重叠 (如 `0.10` 表示 10%)。 | | **Parallel** | `enabled` | `bool` | 启用/禁用同一层级内文件的并发处理。 | | | `maxWorkers` | `int` | 并发 LLM 调用的最大数量。 | ### 🌍 多 Provider 支持 CodiLay 与 provider 无关。支持以下驱动： - **Cloud**: Anthropic (Sonnet/Haiku), OpenAI (GPT-4o), Google Gemini. - **Local**: Ollama, Groq, Llama Cloud. - **Specialty**: DeepSeek, Mistral. - **Custom**: 任何兼容 OpenAI 的 endpoint。 ## 📂 项目结构 ``` src/codilay/ ├── cli.py # Command parsing & Interactive Menu ├── scanner.py # Git-aware file walking ├── triage.py # AI-powered file categorization ├── processor.py # The Agent Loop & Large file chunking ├── wire_manager.py # Linkage & Dependency resolution ├── docstore.py # Living CODEBASE.md management ├── chatstore.py # Persistent memory & Chat history ├── server.py # FastAPI Intelligence Server (Web UI + API) ├── watcher.py # File system watcher (watch mode) ├── exporter.py # AI-friendly doc export (markdown/xml/json) ├── doc_differ.py # Section-level doc diffing & version snapshots ├── triage_feedback.py # Triage correction store & feedback loop ├── graph_filter.py # Dependency graph filtering engine ├── team_memory.py # Shared team knowledge base ├── search.py # Full-text conversation search (inverted index) ├── scheduler.py # Cron & commit-based auto re-runs └── web/ # Premium Glassmorphic Frontend vscode-extension/ # VSCode extension for inline doc surfacing ├── package.json ├── tsconfig.json └── src/extension.ts ``` ## 🤝 贡献 我们热爱贡献者！通过查看 [CONTRIBUTING.md](CONTRIBUTING.md) 来追踪你自己的 wires 进入该项目。 1. **Fork** 该 repo。 2. **安装** 开发依赖：`pip install -e ".[all,dev]"` 3. **测试**：`pytest` 4. **提交** 一个 PR。 ## 📜 许可证 基于 **MIT License** 分发。详见 `LICENSE`。 *由 CodiLay 生成 —— 一次一根 wire，记录未来。*

标签：C2, CLI 工具, DLL 劫持, Markdown, PyPI 包, Python, TCP SYN 扫描, WebSocket, Web UI, 交互式聊天, 代码图谱, 代码文档生成, 代码理解, 依赖分析, 增量构建, 大语言模型, 威胁情报, 开发者工具, 无后门, 知识库管理, 网络安全研究, 自动化文档, 软件架构, 逆向工具, 错误基检测, 静态代码分析