semcod/nexu
GitHub: semcod/nexu
Nexu 是一个可视化意图契约编排器，通过冻结项目状态、创建独立 capsule 沙盒、验证意图契约并安全提升变更，实现大型项目的可控代码和 UI 演进。
Stars: 0 | Forks: 0
# Nexu
项目
范围演进：函数
## AI 成本追踪
   
  
- 🤖 **LLM 使用量：** $10.1205 (62 次提交)
- 👤 **人工开发：** ~$3015 (30.2 小时 @ $100/小时，30 分钟去重)
生成于 2026-07-05，使用 [openrouter/deep/deep-v4-pro](https://openrouter.ai/deep/deep-v4-pro)
**Nexu** 是一个**可视化意图契约编排器**，用于受控的代码和 UI 演进。
它帮助您接管一个大型项目，冻结其当前状态，提取一个称为 capsule 的独立小切片，通过人工或 LLM 辅助的迭代来演进该 capsule，根据意图契约验证结果，只有在此之后才将变更提升回源项目。
```
init -> freeze -> capsule create -> plan/blueprint -> iterate -> verify -> review -> promote
```
当一项任务在主工作区直接编辑过于冒险或范围过大时，Nexu 非常有用。Nexu 不会让 LLM 在整个代码库上操作，而是为其提供一个更小的、带版本控制的沙盒，其中包含明确的文件、契约、证据、报告和提升检查。
## 当前状态
当前版本：**0.5.17**。
该项目目前提供：
- 基于 Typer 的 CLI：`nexu init`、`nexu freeze`、`nexu capsule ...`、`nexu mcp ...`，
- 带有轻量级文件哈希基准的项目快照，
- 位于 `.nexu/capsules//` 下的独立 capsule，
- 确定性的 capsule 规划和迭代文件夹，
- 从 capsule 元数据和 Intract 契约生成的 UI/API/测试蓝图，
- capsule 的静态运行时预览，
- 具有严格 capsule 边界的、适配 LLM 的 prompt 导出，
- 包含契约、漂移和证据检查的验证报告，
- 人工/LLM 审查包和可移植的审查捆绑包，
- 模拟运行和应用提升模式，
- 适用于 IDE/agent 客户端的兼容 MCP 的 stdio 工具，
- Cinema：用于可视化 UI 演进的交互式浏览器工作区，
- 使用 pytest、Markdown 链接检查、Intract、redup 和 ruff 的本地质量配置。
默认情况下禁用网络 LLM 调用。仅当在 `nexu.yaml` 中启用且存在所需的 API key 环境变量时才会使用它们。
## 安装
从 PyPI 安装：
```
python -m venv .venv
. .venv/bin/activate
pip install nexu
nexu --help
```
对于本地开发：
```
git clone https://github.com/semcod/nexu.git
cd nexu
python -m venv .venv
. .venv/bin/activate
pip install -e .[dev]
python -m nexu --help
```
Nexu 需要 Python **3.10+**。
## Nexu 创建的内容
执行 `nexu init .` 后，项目将包含：
```
nexu.yaml project configuration
intract.yaml project-level intent contracts
.nexu/ local Nexu state
```
capsule 存储其自己的元数据、复制的源切片、基准哈希、契约、计划、报告和生成的工件：
```
.nexu/capsules//
capsule.yaml
intract.yaml
src/
iterations/
baseline/
plan/
blueprints/
runtime/
evidence/
reviews/
reports/
bundles/
cinema/
```
## 快速开始
```
nexu init .
nexu freeze . --name baseline
nexu capsule create . \
--name users-api \
--domain backend \
--include "src/users/**" \
--endpoint "POST:/api/users"
nexu capsule plan users-api --steps 5 --goal "Improve create-user flow" --print
nexu capsule blueprint users-api --print
nexu capsule iterate users-api --steps 3 --goal "Improve create-user flow"
nexu capsule export-prompt users-api
nexu capsule verify users-api
nexu capsule review users-api
nexu capsule report users-api
nexu capsule promote users-api --dry-run
```
当提升计划可接受且验证无误时：
```
nexu capsule promote users-api --apply
```
## 主要命令
项目设置：
```
nexu init .
nexu freeze . --name baseline
```
capsule 生命周期：
```
nexu capsule create . --name my-slice --include "src/my_module/**"
nexu capsule list
nexu capsule status my-slice
nexu capsule plan my-slice --steps 10 --goal "Evolve the selected workflow"
nexu capsule blueprint my-slice --print
nexu capsule iterate my-slice --steps 3 --goal "Evolve the selected workflow"
nexu capsule runtime my-slice
nexu capsule export-prompt my-slice
nexu capsule diff my-slice
nexu capsule drift my-slice
nexu capsule verify my-slice
nexu capsule journal my-slice
nexu capsule review my-slice
nexu capsule bundle my-slice
nexu capsule report my-slice
nexu capsule promote my-slice --dry-run
nexu capsule promote my-slice --apply
```
MCP 集成：
```
nexu mcp tools
nexu mcp serve --path .
```
当直接从可编辑检出运行且未安装控制台脚本时，请使用 `python -m nexu ...` 代替 `nexu ...`。
## 典型工作流
### 人工控制的重构
1. 使用 `nexu freeze` 冻结项目。
2. 创建一个仅包含与变更相关文件的 capsule。
3. 在 `.nexu/capsules//src/` 内编辑文件。
4. 运行 `nexu capsule verify `。
5. 审查 `nexu capsule diff ` 和 `nexu capsule report `。
6. 首先使用 `--dry-run` 进行提升，审查后使用 `--apply`。
### LLM 辅助实现
1. 创建 capsule 并运行 `nexu capsule blueprint`。
2. 使用 `nexu capsule export-prompt` 导出受约束的 prompt。
3. 将 prompt 提供给 IDE agent 或外部 LLM。
4. 确保 agent 仅在 capsule 内部工作。
5. 通过 Nexu 进行验证、审查和提升。
### IDE agent 集成
运行 MCP stdio 服务器：
```
nexu mcp serve --path .
```
MCP 服务公开了适用于 capsule 创建、状态、规划、蓝图绘制、迭代、prompt 导出、运行时生成、验证、审查、报告和提升规划的保守工具。
## Cinema：可视化 UI 演进
Cinema 是 Nexu 基于浏览器的 UI 演进模式。它为 capsule 生成本地播放器，包含：
- 一个活动的工作区 frame，
- 三个用于备选 UI 提案的选项 frame，
- 可视化选择和保留/移除标记，
- 由 Intract 风格的约束支持的政策账本，
- 可恢复的 UI 历史记录检查点，
- 为选定阶段发布的本地服务，
- 用于便携式交接的 Markpact 导出。
运行默认的计算器 Cinema 示例：
```
make cinema
```
打开命令打印的 URL。请勿假定固定端口。
### 在播放器中切换示例项目
Cinema 服务器在一个工作区 capsule（例如 `scientific_calc`）内运行，但播放器无需重启服务器即可加载任何目录项目（计算器、仪表板、`backend_service`、分析等）：
1. 打开 **Projects** 标签页并选择一个卡片，或使用深层链接：
`http://127.0.0.1:/cinema_player.html?project=backend_service`
2. 激活会重置前一个示例的策略账本，从项目副标题中植入目标契约，并从该项目的阶段重建**截然不同的**选项 A–C。
在激活响应中，`goal_bootstrap.status` 为 `requires_llm`（目标契约已就绪，选项生成推迟到 LLM 迭代步骤执行）。
3. 在 **workspace** frame 上标记元素（拖拽或审查模式），然后进行迭代或提升。
**导入您自己的项目：** 在 **Projects** 标签页上使用 **Upload ZIP**、**Git URL** 或 **HTTP website**。每个导入都会在本地转换为 Markpact 迁移 README，植入到 stage0–2 中，并出现在项目目录中。**HTTP 导入**在 stage0 中显示获取的页面（带有指向实时站点的 ` `: 动态追加子元素。
- `REPLACE `: 替换目标选择器的内部 HTML。
- `STYLE { css_rules }`: 实时将视觉样式更新应用于目标。
- `REMOVE `: 从页面中精准删除元素。
### 实时演进演示 (`./examples/mcp_patch_demo/`)
一个高级的毛玻璃实时预览仪表板：
- 挂载本地 Repatch JS SDK。
- 通过 Node.js WebSocket 服务器流式传输实时的 UI 修改。
- 显示接收到的 DSL patch 的交互式虚拟终端日志。
- 运行方式为，执行：`cd examples/mcp_patch_demo && npm install && npm start`。
## 双模式 Intract 支持
通过 **Intract** 进行意图验证现在支持两种强大的操作模式：
1. **内联注释（直接在代码中）：** 在源文件中，将 `@intract.v1` 规则直接放置在它们所管理的类、函数或块之前。
2. **独立清单 (`intract.toon.yaml`)：** 一个允许精确目标坐标寻址的外部清单：
- **`target.file`**: 目标文件路径。
- **`target.function`**: 目标函数名称。
- **`target.line`**: 目标代码行号。
- **`target.xpath` / `xpatch`**: 通过 XPath 定位目标 HTML/XML 节点。
`intract.toon.yaml` 示例：
```
contracts:
- id: forbid-destructive-updates
intent: ensure-no-write
forbid: [destructive_write, write]
target:
file: "src/calculator.py"
function: "add_numbers"
line: 45
- id: button-style-check
intent: validate-element-style
validate: [contrast_ratio]
target:
file: "index.html"
xpath: "//button[@id='btn-eq']"
```
## 许可证
基于 Apache-2.0 许可证授权。
标签：AI辅助编程, DLL 劫持, Python, SOC Prime, 代码管理, 大语言模型, 安全规则引擎, 开发工具, 无后门, 逆向工具