内容
# 上下文锻造
[](https://github.com/drag1web/contextforge/actions/workflows/ci.yml)
**上下文锻造** 是一个本地优先的桌面工作空间，用于为 AI 编程代理准备软件项目。
它扫描仓库，解释项目准备情况，构建可重用的项目上下文，生成可编辑的 `AGENTS.md` 文件，并为 **Codex**、**Cursor**、**Claude Code**、**Gemini** 和通用编程代理创建受保护的任务包。上下文锻造还包括一个用于安全项目和任务包访问的本地stdio **MCP 服务器**，适用于兼容的客户端。
> 当前版本：**v0.7.0-alpha — 桌面工作空间和本地 MCP**<br>
> 这是一个源码预发布版本，暂无打包安装程序。
<p align="center">
<img src="docs/assets/screenshots/dashboard-v0.7.png" alt="ContextForge dashboard" width="100%" />
</p>
## 为什么选择上下文锻造
- **默认本地优先。** 项目扫描、SQLite存储、上下文选择、任务包和MCP都在本地机器上运行。
- **可解释的上下文。** 选定的文件具有角色、原因、置信度、质量信号和审查状态，而不是不透明的文件转储。
- **受保护的AI工作流。** 缺失的值、主观范围、不安全的目标和弱所有权证据停留在澄清、审查或调查流程中。
- **可重用的输出。** 项目内存、模板、规则配置文件、验收标准、`AGENTS.md`和任务包在重启后存活，并可跨工具重用。
## 当前功能
### 项目工作空间
- 添加和重新扫描本地仓库。
- 检测堆栈、包管理器、脚本、测试、文档、CI、配置和库存信号。
- 显示AI就绪情况、项目详情、扫描器证据、本地Git状态和轻量级差异审查。
- 在不上传源代码的情况下维护项目特定的内存和决策。
### 任务包
- 在文件选择之前理解非正式的RU/EN/混合语言任务。
- 在缺少所需信息时提出聚焦的澄清问题。
- 从实际仓库证据中选择有根据的实现和支持上下文。
- 应用模板、规则配置文件、自定义规则和验收标准。
- 生成、编辑、保存、复制和导出任务包为Markdown或文本。
- 显示隐私安全的选择器、生成和性能诊断。
### 集成
- 可选的Ollama和支持的AI提供商精炼，具有验证的回退。
- 可选的GitHub设备身份验证、仓库链接、问题→任务包和任务包→问题工作流。
- 可选的网站账户和通过桌面链接的显式任务包交接。
- 用于Codex和其他MCP兼容客户端的本地上下文锻造MCP服务器。
## 本地MCP
上下文锻造MCP使用stdio和与桌面后端相同的本地存储和受保护的任务包管道。
服务器启用读取操作。任务包创建默认情况下被禁用，需要两个条件：
1. 显式本地权限；
2. 在个别工具调用上设置`confirmCreate: true`。
MCP服务器**不**编辑仓库文件、运行shell命令、修改Git或启动编码代理任务。
主要命令：
```bash
npm run build
npm run mcp:start
npm run test:mcp
```
设置、权限、工具、资源、提示、Codex注册和故障排除在[`docs/mcp.md`](docs/mcp.md)中有详细记录。
<table>
<tr>
<td width="50%"><img src="docs/assets/screenshots/navigation-v0.7.png" alt="ContextForge navigation modal" /></td>
<td width="50%"><img src="docs/assets/screenshots/global-search-v0.7.png" alt="ContextForge global search" /></td>
</tr>
</table>
## 隐私和安全边界
上下文锻造旨在在用户启动显式外部工作流之前保留源代码。
- SQLite是默认的桌面存储。
- 导出的任务包元数据中省略了绝对本地项目根目录。
- 诊断信息不存储原始提示、模型响应、源代码片段、机密或绝对路径。
- GitHub工作流仅在显式请求时发送仓库和问题元数据。
- 网站发布仅传输选定的任务包，并拒绝检测到的机密和绝对本地路径。
- MCP列表操作省略完整的任务包提示，并编辑类似机密的值。
## 从源码运行
### 要求
- Node.js 20+
- npm
- 可选：用于本地AI精炼的Ollama
- 可选：仅用于PostgreSQL适配器实验的Docker
### 安装和启动
```bash
npm install
npm run dev
```
开发模式启动：
- Express API 在 `http://localhost:4000`;
- Vite渲染器 在 `http://localhost:5173`;
- Electron桌面外壳。
正常的桌面开发使用本地SQLite，不需要Docker。
### 构建
```bash
npm run build
```
### 焦点验证
```bash
npm run test:mcp
npm run test:desktop-sync
npm run test:understanding
npm run test:clarification
npm run test:generation:taskpack
npm run test:selector:rollout
npm run test:ownership
npm run test:canonical-core
npm run test:context-quality
```
其他选择器、安全、接地、基准和验证实验室命令在`package.json`中可用。
## 环境
复制`.env.example`到`.env`并仅调整您需要的集成。
```env
STORAGE_DRIVER=sqlite
SQLITE_DB_PATH=./data/contextforge.sqlite
SERVER_PORT=4000
OLLAMA_URL=http://localhost:11434
APP_VERSION=0.7.0-alpha
CONTEXTFORGE_MCP_ENABLED=true
CONTEXTFORGE_MCP_ALLOW_CREATE_TASK_PACKS=false
```
GitHub、网站账户、PostgreSQL和外部AI提供商是可选的。
## 架构
```text
Electron桌面外壳
├─ React + TypeScript + Vite渲染器
├─ 本地Express API
│ ├─ 扫描器和就绪情况
│ ├─ 任务理解和澄清
│ ├─ 选择器/所有权/授权管道
│ ├─ 上下文编译器和任务包生成
│ ├─ Git和GitHub工作流服务
│ └─ SQLite优先存储适配器
└─ 本地MCP_stdio服务器
├─ 只读项目、内存和任务包访问
└─ 显式授权任务包创建
```
## 文档
- [`docs/mcp.md`](docs/mcp.md) — 本地MCP服务器和Codex设置。
- [`docs/MVP.md`](docs/MVP.md) — 当前alpha产品边界和发布检查清单。
- [`docs/ROADMAP.md`](docs/ROADMAP.md) — 已完成的里程碑和下一个产品阶段。
- [`docs/VALIDATION_LAB.md`](docs/VALIDATION_LAB.md) — 便携式顺序验证工作流。
- [`docs/SELECTOR_BENCHMARK.md`](docs/SELECTOR_BENCHMARK.md) — 选择器基准模型和私有清单边界。
- [`CHANGELOG.md`](CHANGELOG.md) — 详细的发布历史。
## 发布状态
`v0.7.0-alpha` 是一个GitHub源码预发布版本。它标志着大型桌面UI刷新、当前通用接地基线、桌面链接改进和上下文锻造MCP服务器v1的完成。
已知发布边界：
- 暂无安装程序或便携式二进制文件；
- 深度选择器支持仍然最适用于TypeScript/JavaScript项目；
- MCP v1仅限本地stdio；
- 远程MCP、自动代码更改、自动PR和代理任务编排不属于此发布。
参见 [`docs/releases/v0.7.0-alpha.md`](docs/releases/v0.7.0-alpha.md) 了解发布摘要。
