Skip to content
BranchesTags

Latest commit

 

History

70 Commits

Folders and files

NameName
Last commit message
Last commit date
.github/workflows
.github/workflows
 
 
docker
docker
 
 
docs
docs
 
 
file_cortex_core
file_cortex_core
 
 
routers
routers
 
 
scripts
scripts
 
 
static
static
 
 
templates
templates
 
 
tests
tests
 
 
.dockerignore
.dockerignore
 
 
.gitattributes
.gitattributes
 
 
.gitignore
.gitignore
 
 
CURRENT_ENGINEERING_PLAN.md
CURRENT_ENGINEERING_PLAN.md
 
 
DEVELOPER_GUIDE.md
DEVELOPER_GUIDE.md
 
 
README.md
README.md
 
 
ROADMAP.md
ROADMAP.md
 
 
TECHNICAL_GUIDE.md
TECHNICAL_GUIDE.md
 
 
build_exe.py
build_exe.py
 
 
fctx.py
fctx.py
 
 
file_search.py
file_search.py
 
 
mcp_server.py
mcp_server.py
 
 
pyproject.toml
pyproject.toml
 
 
pytest.ini
pytest.ini
 
 
requirements.txt
requirements.txt
 
 
start_web_server.bat
start_web_server.bat
 
 
web_app.py
web_app.py
 
 

Repository files navigation

FileCortex v7.0.0 (工作区编排助手)

版本: 7.0.0 | 日期: 2026-09-17 | 测试: 882 passed | 代码质量: Ruff 0 errors

核心理念

  • Orchestration over Collection: 从简单的"收集"进化为对工作区的"编排"。
  • Engineering Excellence: 基于 Pydantic V2 与 Google Python Style Guide 构建的健壮内核。

主要功能

微内核架构

  • 强类型配置: Pydantic 模型驱动的 DataManager，实现配置的自愈与严谨校验。
  • 策略化搜索: 多维度匹配策略 (smart/exact/regex/content)，易于扩展。
  • 安全沙盒: PathValidator 路径权限注册制，UNC 拦截，敏感目录保护。

现代化交互

  • 控制中心: Web 端顶部全局过滤器工具栏，统一配置排除规则与搜索模式。
  • 智能查重: DuplicateFinder 支持"保留最早/最晚"一键筛选冗余文件。
  • XML 导出引擎: 支持 CDATA 封装，提升 LLM 对复杂代码片段的解析精度。
  • 项目蓝图: 一键生成项目架构 ASCII 快照。

性能与安全

  • 二级探测缓存: (path, mtime, size) 编码探测缓存，大幅提升大规模文件读取速度。
  • 安全沙盒增强: 符号链接遍历防护 (Path.resolve())、统一入口验证 (PathValidator.validate_project())
  • 内存防溢出: 并发内容搜索 max_bytes 物理隔离 + 导出 OOM 保护 (500文件/50MB上限)。
  • Token 预算预警: UI 超阈值颜色警示。
  • API Token 认证: HTTP Header + WebSocket 双通道验证。

多端访问

  • 桌面版 (Tkinter): 原生桌面体验，目录树导航与实时预览。
  • 网页版 (FastAPI): ES6 模块化前端，WebSocket 实时搜索流，自定义右键菜单。
  • CLI 工具 (fctx.py): Headless 环境命令行编排 (search/export 子命令)。
  • MCP Server: Model Context Protocol 服务器，AI Agent 原生调用。

文件管理

  • 多模式搜索: smart/exact/regex/content 四种模式，positive/negative 标签。
  • 批量操作: 批量重命名、批量删除、批量归档 (ZIP)。
  • 查重工具: 大小预筛 + SHA256 策略。
  • 快速分类: 自定义类别目录移动。

v7.0.0 发行工程与修复轮

  • 可部署发行: Dockerfile + docker-compose（非 root、healthz 探活、单 worker 固化）、systemd 单元、Windows NSSM 脚本、clean-install 冒烟脚本（scripts/）。
  • 配置目录可重定位: FCTX_CONFIG_DIR 环境变量（配置与日志同步跟随），容器/多实例部署不再共享 ~/.filecortex。
  • 免鉴权健康端点: GET /healthz 供编排系统探活；/api/* 门禁不变。
  • 嵌套 .gitignore: 逐目录 .gitignore 按 git "后者覆盖前者" 语义生效（父 *.log + 子 !error.log 正确组合），搜索/树/导出/flatten 全线一致。
  • Web 导出异步化: /api/generate、/api/project/stats 改走 asyncio.to_thread，大导出不再占用事件循环。
  • 桌面响应性: 预览读取、上下文导出、全选添加、暂存过滤、批重命名预览全部后台化/去抖，主线程不再做重 IO。
  • 前端一致性: openProject 取消在途搜索并 flush 暂存；fetch 超时熔断；Modal 实例去重；全选可见性修正；虚拟列表 ResizeObserver；stats 竞态守卫；预览清空卫生。
  • CLI 沙盒收口: fctx export 相对输出路径越界（../）被拒绝（显式绝对路径仍允许）。
  • MCP/队列契约: DuplicateWorker 与 SearchWorker 的 ERROR→DONE 哨兵对齐；progress 端点补 Pydantic schema。

v6.6.1 审查修复轮

  • WS Origin 门禁: WebSocket 握手应用与 HTTP 中间件一致的同源策略，封堵跨站 WebSocket 劫持 (CSWSH)。
  • 解析根配置查询: 工具执行端点 (HTTP/WS) 以 resolve 后的项目根查询配置，子目录输入不再产生幽灵项目条目。
  • WS 成功路径 PID 卫生: 工具正常结束后不再对已退出 PID 执行 taskkill（消除 PID 复用误杀风险）；背压取消竞态消除重复结果帧。
  • 前端健壮性: 工具流处理 {"status":"ERROR"} 帧并在服务器关闭时兜底解锁；搜索 WS 异常关闭不再卡死 UI；全选/SELECT 控件改为 change 驱动；_fetch 单次读取响应体；openProject 竞态守卫。
  • 桌面版: 暂存树专用右键菜单恢复可达；搜索轮询单链管理 + DONE 哨兵 TOCTOU 防护；工具执行并发防护；统计估算 1MB 采样外推（不再全量读入大文件）。
  • CLI: 相对路径锚定项目根；搜索结果相对路径显示（Windows 修复）；GBK 管道编码守卫；工具执行失败反映到退出码。
  • MCP: 阻塞磁盘 I/O 全部下放 asyncio.to_thread；search_files 描述补全 content 模式。
  • 测试隔离: CLI/MCP 入口测试默认隔离到临时配置文件，不再污染开发者真实 ~/.filecortex/config.json。

前端增强

  • 标签管理 (Tag Management): 前端 UI 支持添加/移除标签。
  • 文件创建 (File Creation): 文件创建模态框，支持从 UI 直接创建新文件。
  • 可折叠面板 (Collapsible Left Panel): 左面板从 Bootstrap 标签页重构为可折叠区域，提升操作效率。
  • SRI 哈希 (Subresource Integrity): 所有 CDN 资源添加 SRI 哈希；marked@12.0.0 和 mermaid@10.9.0 版本锁定。

详细文档

快速开始

环境要求

  • Python 3.10+
  • Windows/macOS/Linux

安装

pip install -r requirements.txt
# 或作为库/命令安装（推荐）:
pipx install file-cortex

部署拓扑（v7.0 起）

拓扑 命令 说明
本机单用户 fctx-web → http://127.0.0.1:8000 零配置，仅回环可访问
LAN 团队服务器 (Docker) docker compose -f docker/docker-compose.yml up -d 必填 FCTX_API_TOKEN；单 worker 硬约束
Windows 服务 scripts\install_service_windows.bat <token> NSSM 注册为系统服务
Linux 服务 scripts/filecortex.service → /etc/systemd/system/ Restart=on-failure，单进程
CI/headless fctx open/search/export + MCP stdio 无 GUI 依赖

配置目录: 默认 ~/.filecortex；容器/多实例部署用 FCTX_CONFIG_DIR 重定位（日志同步跟随）。 健康检查: GET /healthz（免鉴权）供容器编排探活；/api/* 仍受 token 门禁。 发布门禁: bash scripts/smoke_install.sh（clean-venv 安装 → CLI → Web 冒烟）。

桌面版

python file_search.py

网页版

python web_app.py
# 浏览器访问 http://127.0.0.1:8000

部署约束: 进度追踪（copy/extract 任务）为进程内实现，Web 服务必须以单进程运行（默认即是），请勿使用 uvicorn --workers N 多进程部署，否则轮询任务的进度端点可能返回 404。

CLI 工具

python fctx.py open .
python fctx.py projects
python fctx.py stage <project> <file>
python fctx.py search <project> <query> --mode smart
python fctx.py export <project> --format markdown --output context.md

MCP Server（需额外安装 MCP SDK）

# 1. 安装 MCP 可选依赖
pip install -e ".[mcp]"
# 或: pip install mcp>=1.0.0

# 2. 启动（默认 stdio 传输，供 Claude Desktop / Cline 等 MCP 客户端调用）
python mcp_server.py --transport stdio

# 3. 网络传输（v6.6.0 起真正可用）：sse 或 streamable-http
python mcp_server.py --transport streamable-http --host 127.0.0.1 --port 3000

# 4. 在 Claude Desktop 配置中注册（示例）
# ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
# 或 %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
  "mcpServers": {
    "file-cortex": {
      "command": "python",
      "args": ["<path-to>/mcp_server.py"]
    }
  }
}

注：未安装 mcp 包时，mcp_server.py 进入 mock 回退模式（仅打印工具列表，不提供真实 MCP 传输）。

测试

运行所有测试

python -m pytest

测试覆盖

  • 882 项核心测试: 涵盖内核逻辑、安全沙盒、API 契约、搜索矩阵、WebSocket 实时流、前端模块化契约、CLI、MCP、Windows 兼容性、进程管理、OOM 保护、批量 copy/事务 extract 文件操作、v6.6.0 审查加固回归（UNC 长前缀、注册旁路、CancelledError、背压取消等）、v6.6.1 审查修复回归（WS Origin 门禁、解析根查询、PID 卫生、CLI 相对路径、源码契约等）、v7.0 发行工程回归（FCTX_CONFIG_DIR、healthz、嵌套 gitignore、CLI 导出沙盒、哨兵契约）。
  • 测试结果: 882 passed, 0 failed
  • 代码质量: Ruff 0 errors, Google Style 全审计项通过

代码质量检查

python -m ruff check .
python -m ruff check . --fix
python -m pytest

项目结构

file_cortex_core/          # 微内核逻辑包
├── __init__.py           # 统一接口 + 版本声明
├── config.py            # DataManager (SSOT 配置中心)
├── security.py         # PathValidator (安全沙盒与归一化)
├── file_io.py          # FileUtils (物理 I/O 与 Gitignore)
├── format_utils.py     # FormatUtils (格式化与 Token 估算)
├── context.py          # ContextFormatter (AI 上下文导出, OOM 保护)
├── search.py           # SearchWorker (搜索引擎, ThreadPoolExecutor)
├── actions.py          # FileOps, ActionBridge (执行桥接, DI 支持)
├── duplicate.py        # DuplicateWorker (SHA256 查重)
├── process_utils.py    # 跨平台进程终止工具
└── gui/                # GUI 组件 (BatchRename, DuplicateFinder)

routers/                  # FastAPI 路由层
├── http_routes.py      # 合并层 (向后兼容)
├── project_routes.py   # 工作区/项目管理
├── fs_routes.py        # 文件系统 CRUD
├── action_routes.py    # 暂存/工具/上下文/设置
├── ws_routes.py        # WebSocket 搜索/工具流
├── services.py         # 业务逻辑服务层
├── schemas.py          # Pydantic 参数校验模型
└── common.py           # ProcessManager (线程安全进程管理)

static/js/                # ES6 模块化前端
├── main.js             # 流程控制 + App 初始化
├── state.js            # 状态中心 + config.endpoints 集中管理
├── api.js              # API 封装 (_post / _postJson 集中化)
├── ui.js               # UI 渲染驱动 (树/暂存/收藏/工具)
├── events.js           # data-action 事件委托 (v6.5.1+)
├── layout.js           # 三栏拖拽调整 (v6.5.1+)
└── virtual-list.js     # 虚拟滚动列表 (v6.5.1+)
static/css/style.css     # CSS 变量 + 双主题 + 骨架屏 + 减动效 (v6.5.1+)

file_search.py           # Tkinter 桌面版 (入口 main())
web_app.py              # FastAPI Web 入口 (含 CSP Header)
fctx.py                # CLI 工具入口
mcp_server.py          # MCP 协议服务
build_exe.py            # PyInstaller 打包脚本 (入口 main())

参数动态对齐

前后端关键参数已统一校验，确保一致性：

参数 前端 后端 默认
token_threshold state.js GlobalSettings 128000 (dynamic via GlobalSettings())
token_ratio state.js GlobalSettings 4 (dynamic via GlobalSettings())
preview_limit_mb settings modal GlobalSettings 1.0
allowed_extensions settings modal GlobalSettings ""
api_token <meta name="fctx-api-token"> env FCTX_API_TOKEN -
wsSearch state.js:config.endpoints ws_routes.py /ws/search -
wsExecute state.js:config.endpoints ws_routes.py /ws/actions/execute -
__version__ index.html {{ version }} __init__.py 7.0.0

环境变量

变量 说明 默认值
FCTX_API_TOKEN API 认证 Token；绑定非 localhost 时必填 (仅 localhost 可省略)
FCTX_CONFIG_DIR 配置/日志目录重定位（容器挂载卷） ~/.filecortex
FCTX_ALLOWED_ORIGINS 允许的跨域来源，逗号分隔 localhost/127.0.0.1/::1 的 8000 端口
FCTX_PROD 生产模式 (隐藏错误详情) (无)
FCTX_EXEC_TIMEOUT 工具执行超时(秒) 300

许可证

MIT License

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages