内容
<br />
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/workspace-json-codex-lockup-dark.png">
<source media="(prefers-color-scheme: light)" srcset="assets/workspace-json-codex-lockup-light.png">
<img alt="workspace.json / Codex" src="assets/workspace-json-codex-lockup-dark.png" width="620">
</picture>
</p>
<br />
<p align="center"><strong>可移植的仓库历史记录，在有证据的风险编辑落地之前更改Codex的计划。</strong></p>
<p align="center"><code>@workspacejson/codex-mcp</code></p>
<p align="center">
<a href="https://github.com/workspace-json/codex-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/workspace-json/codex-mcp/actions/workflows/ci.yml/badge.svg"></a>
<img alt="Node 20+" src="https://img.shields.io/badge/node-20%2B-339933?logo=node.js&logoColor=white">
<img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue">
</p>
## 30秒了解
| | |
| --- | --- |
| 任务 | 更新checkout路由 |
| 没有 `workspace.json` | Codex建议一个文件 |
| 有 `workspace.json` | 钩子识别两个有证据的合作伙伴 |
| 执行 | 不完整的补丁被拒绝 |
| 结果 | Codex在编辑落地之前修订变更集 |
## 安装
```bash
npx @workspacejson/codex-mcp install --with-hook
```
这为您提供了MCP上下文 **以及** 确定的预编辑钩子 - 上面30秒演示中显示的执行。 它是幂等的，限定在此仓库的 `.codex/` 目录中，并且从不触及 `~/.codex`。 重新启动Codex，然后运行 `/mcp` 以确认 `workspacejson` 已连接。
**根据需要添加表面。** 每个标志都是累加的，并且只要求它需要的同意 - 不会默默安装任何内容：
| 命令 | 添加 | 触及 |
| --- | --- | --- |
| `install` | MCP上下文（读取工具）+ 可选的GPT-5.6审查器 | 此仓库的 `.codex/` |
| `install --with-hook` | + 确定的预编辑钩子 | 此仓库的 `.codex/` |
| `install --with-extension` | + VS Code编辑器界面 | 您的全局VS Code（明确同意） |
| `install --full` | 钩子 **和** 扩展 | 两个 |
**卸载** 反映了该同意。 `npx @workspacejson/codex-mcp uninstall` 仅删除此仓库拥有的内容 - MCP块、钩子和运行时 - 并 **保留您的全局VS Code扩展** 。 要删除编辑器扩展，请明确要求： `npx @workspacejson/codex-mcp uninstall --with-extension`。
<details>
<summary>MCP-only设置、CI检查、VS Code界面和手动验证</summary>
### 自己连接MCP服务器
将以下内容添加到 `.codex/config.toml` （项目）或 `~/.codex/config.toml` （全局）：
```toml
[mcp_servers.workspacejson]
command = "npx"
args = ["-y", "@workspacejson/codex-mcp", "server"]
# 可选：指向特定文件或搜索根目录。
# env = { WORKSPACE_JSON_PATH = "/abs/path/.agents/workspace.json" }
```
如果没有钩子，您仍然会获得读取工具，但不会有确定的执行。
### CI / 仓库本地检查 - 不需要编辑器
```bash
git diff --name-only | node hooks/pre-edit-check.mjs --paths-stdin
```
退出代码2表示脆弱的更改缺少合作伙伴；原因及其证据一同打印。 将其放入GitHub Actions中，以与钩子控制拉取请求相同的方式控制。
### VS Code编辑器界面（可选）
让安装程序为您处理 `code` CLI、幂等性和重新加载提示：
```bash
npx @workspacejson/codex-mcp install --with-extension
```
这安装了 `workspace-json.workspacejson-codex-decorations` 扩展：脆弱文件上的资源管理器装饰、**当前更改** 视图、同步状态项和基于收据的咨询审查 - 所有这些都从您的本地 `.agents/workspace.json` 读取，无需网络调用和无需遥测。
安装程序仅针对 **VS Code Stable** 。 如果 `code` CLI不在您的PATH上，它会报告 `UNAVAILABLE` 以及一行修复方法，并保留您的MCP/钩子安装不变 - 它永远不会默默地针对Insiders、Cursor、远程或容器。 要故意将其定位到其他编辑器的CLI，请设置 `WORKSPACEJSON_CODE_CLI` （例如 `cursor`）并重新运行。
从此仓库的checkout构建？ 首先生成VSIX，然后安装：
```bash
npm run build:extension
npx @workspacejson/codex-mcp install --with-extension
```
更喜欢手动安装固定的VSIX（离线或发布工件）？
```bash
code --install-extension workspacejson-codex-decorations-<version>.vsix
```
演示和固定仓库可能会通过 `.vscode/extensions.json` 推荐确切的扩展ID；这仅用于发现，永远不会自行安装任何内容。
### 两分钟内验证
从具有已提交 `.agents/workspace.json` 的仓库：
1. 在Codex中，请求编辑一个工作区标记为脆弱的文件。
2. 观察钩子拒绝补丁，引用记录的证据和更改遗漏的合作伙伴。
3. 请求Codex包含合作伙伴并重试 - 编辑继续进行。
除了上述步骤1之外，无需进行任何配置。 此仓库中的 `fixture/` 复制了演示中显示的确切拒绝。
</details>
## 工作原理
MCP提供上下文。 确定的钩子强制执行有证据的遗漏。 可选的直接只读GPT-5.6 API审查挑战提供的完整差异，并本地保留其请求/响应收据。 审查者永远不会控制钩子，`PASS`裁决不是安全认证。
证据层级的完整派生规则（`ASSERTED`/`OBSERVED`/`VERIFIED`）、钩子的 fail-open 行为和GPT-5.6审查者的范围位于 [`docs/how-it-works.md`](docs/how-it-works.md) 中。
## 运行保证
- 缺失的证据永远不会成为安全批准。
- 格式错误的证据永远不会使编辑循环崩溃。
- 审查者的输出永远不会控制确定的执行。
- 安装永远不会覆盖未管理的配置。
- 卸载仅删除所有权工件。
- 编辑器扩展仅在明确同意 `--with-extension` 下安装。
- 每个 `VERIFIED` 声明都映射到可复制的命令。
每个保证都是可检查的，而不是断言的：从干净的克隆运行 `npm run verify` 以复制此仓库自己的CI运行的门控，或阅读 [`docs/operational-guarantees.md`](docs/operational-guarantees.md) 中的源引用。 有关每个保证在缺少、格式错误或不可用输入下的行为，请参见 [`docs/failure-modes.md`](docs/failure-modes.md)。
## 信任边界
MCP和确定的钩子在stdio上本地运行，不会上传仓库内容。 初始包安装可能会联系npm。 可选的 `review` 命令仅将您明确提供的差异发送到配置的API提供商：OpenAI（`OPENAI_API_KEY`）或OpenRouter（`OPENROUTER_API_KEY`）。 当两个密钥存在时，请设置 `WORKSPACEJSON_REVIEWER_PROVIDER` 为 `openai` 或 `openrouter`；显式 `WORKSPACEJSON_REVIEWER_BASE_URL` 也会选择OpenRouter。 它对OpenAI使用 `store: false`，并保留一个本地请求/响应收据，该收据标识提供商和模型。 请勿提供包含机密的差异。
## 当前限制
- 执行目前涵盖Codex `apply_patch`。
- 其他编辑机制可能会在没有确定性阻止的情况下接收上下文。
- 缺失或格式错误的 `workspace.json` 以明确的不可用警告失败打开。
- 过时的证据不被视为当前风险的证明。
- `fragile:false` 表示文件没有记录的脆弱性，而不是它被验证为安全。
- 这不取代测试、审查或仓库指令。
## 了解更多
- [工作原理](docs/how-it-works.md) — 证据层级、钩子执行、GPT-5.6审查者
- [运行保证](docs/operational-guarantees.md) — 上述七项承诺，附带来源引用
- [故障模式](docs/failure-modes.md) — 在缺少、格式错误或不可用输入下的行为
- [工具](docs/tools.md) — 完整的MCP工具参考（`workspace_get_file_context`、`workspace_get_cochange_partners`、`workspace_list_fragile_files`、`workspace_assess_change`）
- [工作区.json合约](docs/workspace-contract.md) — 消费字段和规范化
- [验证](docs/verification.md) — 已验证的内容和验证方法
- [构建周披露](docs/submission/build-week.md) — 在窗口内创作的内容
- [开发](docs/development.md) — 构建、测试和烟雾套件命令
- [清洁安装审计](docs/clean-install-audit.md) · [固定验证](docs/fixture-verification.md)
## 许可证
Apache-2.0
