内容
# 代码克劳德工作器套件
[English](README.md) | [简体中文](README.zh-CN.md)
**状态：Alpha — 内部测试验证通过，但尚未达到生产就绪状态。**
一个同步、受监管的MCP桥接器，允许ChatGPT Web将有界限的项目工作委托给本地的克劳德代码工作器。ChatGPT充当监管者，负责需求解读、规划、审批和结果审查。克劳德代码工作器执行项目本地的读取、写入、编辑和审批检查。桥接器和PowerShell套件强制执行策略、捕获事件、验证审计声明、规范化结果并维护本地账本。
代码克劳德用于开发、调试和恢复该项目；它不是预期的主要用户界面。预期的Alpha工作流程在ChatGPT Web上启动和结束。
> **该项目不是一个沙盒环境。** 它是为受信任的本地环境提供的一个监管和监督层。使用虚拟机、容器、受限的操作系统账户或另一个真正的隔离边界来运行不可信的代码。
## 为什么存在
ChatGPT Web对于交互式的需求发现和监管决策非常有用，而本地代码代理可以检查和更改真实的项目。然而，单独使用本地工作器很难从浏览器监管：它的权限请求、实际工具使用和报告结果可能会出现偏差。
该项目分离了这些职责：
- **ChatGPT / GPT：** 监管者，需求解读、规划、审批和结果审查。
- **克劳德代码工作器：** 有界限的本地执行、文件检查和项目本地实施。
- **桥接器 / 套件：** 策略执行、审批检查、事件捕获、审计验证、结果规范化、预算、超时和账本记录。
Alpha版本证明了这条同步控制路径。持久的后台执行、自动恢复、运行时审批队列和通知属于B阶段，尚未实现。
## 架构
```text
ChatGPT Web
|
OpenAI 安全 MCP 隧道
|
本地 MCP 桥接器（环回）
|
PowerShell 套件 / 策略 / 账本
|
克劳德代码工作器
|
项目工作空间
```
### 核心组件
| 组件 | 责任 |
| --- | --- |
| 云 AI / ChatGPT Web | 解读需求、规划工作、请求审批、审查证据和报告结果。 |
| 安全 MCP 隧道 | 在ChatGPT和环回桥接器之间承载输出连接，而不直接发布端口 8787。 |
| 本地 MCP 桥接器 | 暴露七个固定的套件工具；它不是一个通用的 shell 或文件系统服务器。 |
| 套件 / 策略 / 审批 | 强制执行模式、路径、工具、预算、超时和审批元数据门控。 |
| 克劳德代码工作器 | 通过配置的提供程序执行有界限的项目本地读取、写入和编辑。 |
| 审计 / 账本 | 持久化流事件、交叉验证工作器声明、规范化结果和保留本地审查元数据。 |
审计返回路径与工作器的自我报告是分开的：
```text
克劳德流事件
|
claude-events.jsonl
|
tool-events.json
|
审计交叉验证
|
worker-result.normalized.json
|
cc_get_result / ChatGPT 监管者
```
## Alpha版本提供的内容
- 分离的 `plan`、`review` 和批准的 `run` 模式。
- 显式审批元数据用于具有写权限的运行。
- 项目根目录和外部目录边界。
- 工作器预算、超时和稳定的运行 ID。
- 使用 `--allowedTools` 和 `--disallowedTools` 的读取/写入/编辑策略。
- 克劳德代码 `stream-json --verbose` 事件捕获。
- 独立的 `observed_tools`、`observed_commands`、`permission_denials` 和读取/写入/编辑目标。
- 通过 `audit_issues` 在工作器声明和成功工具结果之间进行交叉验证。
- 拒绝或失败的工具调用永远不会计为成功的检查。
- 完整的严格 JSON 摘要，没有前者的静默 300 字符截断。
- 文件、目录和符号链接的副作用检测，用于强化的写入烟雾测试。
- Windows路径安全措施和绝对事件路径与相对工作器报告之间的匹配。
- 本地规范化结果和项目账本，供以后审查。
- 通过运行 ID 进行结果恢复，当浏览器端的同步调用首先返回或超时时。
本地狗粮流已通过批准的写入创建了静态的中文任务板，然后在GPT的监督下完成了后续的功能迭代。狗粮文件保留在本地， purposefully 不属于此存储库。
## MCP 工具
- `cc_ping` — 检查桥接器和套件的准备情况。
- `cc_plan_task` — 运行只读规划任务。
- `cc_review_task` — 在不进行编辑的情况下审查有界限的项目状态。
- `cc_run_approved_task` — 执行明确批准的写入任务。
- `cc_get_latest_summary` — 恢复最新的摘要，包括未完成的运行。
- `cc_get_ledger` — 读取最近的本地账本条目。
- `cc_get_result` — 通过运行 ID 或 `latest` 检索完整的规范化结果。
任务工具接受 `mockWorker: true` 用于无需付费工作器调用的传输测试。默认MCP预算为 0.20 美元；这是一个估计的克劳德代码端限制，可能会与提供商的计费略有不同。
## 端到端演示
```text
用户请求 -> 计划 -> 用户审批 -> 执行 -> 结果恢复
-> 只读审查 -> 独立验收 -> 最终报告
```
在 [端到端监督演示](docs/demo.md) 中遵循具体的双文件演练。它显示了MCP调用、审批边界、事件字段、账本检查和失败规则，而不添加演示特定的运行时功能。
## Windows 快速入门
### 要求
- Windows PowerShell 5.1 或 PowerShell 7
- Node.js 18 或更新版本
- 配置了兼容提供者的克劳德代码
- OpenAI 安全 MCP 隧道访问和用于 ChatGPT Web 集成的`tunnel-client`
- ChatGPT 开发者模式，用于连接 MCP 应用程序
将项目克隆或复制到非敏感位置，例如 `D:\path\to\project`。永远不要提交提供者凭证、隧道 ID、本地配置文件或代理凭证。
### 安装和配置
```powershell
cd D:\path\to\project
cd .\mcp-server
npm ci
cd ..
.\scripts\init-config.ps1
.\scripts\doctor.ps1
```
审查 `.agents/policy.json`。在忽略的 `.agents/local.config.json` 中保留特定于机器的覆盖。
| 文件 | 目的 | 提交它？ |
| --- | --- | --- |
| `.agents/policy.json` | 版本控制模式、工具限制和安全默认值。 | 是 |
| `.agents/local.config.json` | 机器本地预算覆盖。 | 否 |
| `mcp-server/config.example.json` | 公共桥接器配置模板。 | 是 |
| `mcp-server/config.json` | 本地项目根目录、端口、超时、来源和可选的审批默认值。 | 否 |
| 隧道配置文件 | 本地隧道 ID/配置文件状态由`tunnel-client`维护。 | 否 |
### 启动本地桥接器
在专用终端中运行环回桥接器：
```powershell
.\scripts\start-mcp.ps1
```
不要将端口 8787 直接暴露给公共互联网。
### 连接安全 MCP 隧道
使用占位符环境值：
```powershell
$env:CONTROL_PLANE_API_KEY = 'YOUR_RUNTIME_API_KEY'
.\scripts\start-openai-tunnel.ps1 -Initialize -TunnelId 'tunnel-example-id' -DoctorOnly
```
然后在单独的终端中运行隧道包装器并连接 ChatGPT 应用程序的隧道：
```powershell
# 专用隧道终端
.\scripts\start-openai-tunnel.ps1
# 单独的就绪检查
.\scripts\start-openai-tunnel.ps1 -ReadyOnly
```
### 逐步验证
```powershell
# 套件和提供者诊断
.\.agents\doctor.ps1
# 无需付费工作器调用
.\.agents\claude-task.ps1 plan -Task 'Return strict JSON with summary exactly ok.' -MockWorker
# 本地桥接器健康和模拟工作器烟雾测试
.\scripts\test-local.ps1 -MockWorkerSmoke
# 运行条件：没有桥接器正在使用端口 8787
.\scripts\test-mcp-protocol.ps1
# 小型真实只读验收
.\scripts\test-mcp-protocol.ps1 -RealPlan -MaxBudgetUsd 0.20
# 独立批准写入烟雾测试
.\scripts\test-mcp-protocol.ps1 -RealWrite -MaxBudgetUsd 0.20
```
从 ChatGPT 开始，使用 `cc_ping`，然后是模拟计划，然后是最小的真实只读任务。只有在审查确切的写入边界和审批元数据后，才使用 `cc_run_approved_task`。
推荐的首次运行顺序：
1. 安装依赖项并初始化本地配置。
2. 审查策略并运行 `scripts/doctor.ps1`。
3. 在专用终端中启动桥接器。
4. 运行模拟套件/MCP检查。
5. 初始化并在另一个终端中启动安全MCP隧道。
6. 检查隧道就绪状态并连接ChatGPT应用程序。
7. 运行 `cc_ping`、模拟计划、有界限的真实计划，最后是一个明确批准的最小写入。
## 安全模型
安全模型是分层的：
- 桥接器暴露固定的套件入口点，而不是通用 shell；
- 策略约束模式、工具、项目根目录、外部目录、预算和超时；
- 写入模式需要审批元数据；
- `--allowedTools` 授予特定工具，而 `--disallowedTools` 明确拒绝禁止的类；
- 系统禁止秘密、破坏性 Git 操作、递归删除和不安全的 Windows 路径；
- 流事件独立于工作器的 JSON 报告；
- 报告的命令、检查和文件操作与成功、非拒绝事件进行交叉验证；
- 不匹配的情况保守地失败为 `audit_validation_failed`；
- 写入烟雾测试在执行前后比较文件、目录和符号链接；
- 本地账本记录结果和审批上下文。
审批元数据记录谁或什么授权了运行以及为什么。它是一个工作流程和审计门控，而不是身份验证或人类同意的加密证明。公共默认值保持为空，需要显式用户确认现有文件编辑、删除、网络、依赖项、Git、广泛扫描或模糊边界。
账本记录运行 ID、模式、状态、审批元数据、允许的高风险开关、预算、超时、更改、检查、风险、阻止项、工件状态、成本和错误。它是一个本地审查辅助工具，而不是只追加或防篡改的安全日志。
这些是防护措施，而不是强隔离。事件审计是由克劳德代码发出的证据，而不是操作系统内核执行跟踪。如果 CLI 或提供者省略了必需的事件，则结果被视为不可验证，而不是成功。
在启用写入访问之前，请参阅 [SECURITY.md](SECURITY.md)。
## 验证的行为
- 源套件烟雾测试：19/19。
- 便携式安装套件烟雾测试：19/19。
- MCP 初始化、发现、ping、模拟计划、批准的模拟运行和确切的结果检索。
- 通过套件和 `cc_get_result` 的严格 Unicode 摘要轮询超过 300 个字符。
- `unverifiable_check_evidence`、`command_audit_mismatch` 和 `file_audit_mismatch` 回归。
- 拒绝和失败的工具结果不计入成功的证据。
- Windows 绝对/相对路径审计匹配。
- 文件、目录和符号链接的副作用防护。
- 真实的只读和批准的写入路径。
- 真实的狗粮期间的事件不匹配拒绝。
- 静态任务板的创建和后续的监督功能迭代。
证据和范围在 [验证结果](docs/validation-results.md)、[Alpha 版本说明](docs/alpha-release-notes.md) 和 [现实世界验证](docs/real-world-validation.md) 中记录。
## 已知限制
- 这是 Alpha 软件，尚未达到生产就绪状态。
- MCP 执行是同步的；ChatGPT 可能在长时间工作器完成之前超时。
- 没有持久的异步队列、租约、心跳、自动重新连接编排或通知邮箱。
- 运行时权限请求无法暂停并通过 ChatGPT 恢复。
- 这不是 OS 级的沙盒环境，不应运行任意不受信任的代码。
- 审计完整性取决于克劳德代码和提供者的事件完整性。
- 提供者预算会计可能会略微超过请求的限制。
- Windows 是主要的验证环境；其他平台没有等效的发布证据。
- 桥接器、`tunnel-client` 和任何必需的代理必须保持运行。
- 隧道和提供者配置仍然依赖于环境。
## 路线图
[阶段 B](docs/v0.2-roadmap.md) 提出但尚未实现：
- 持久的 SQLite 任务存储；
- 异步提交、轮询、暂停和恢复；
- 租约、心跳、取消和崩溃恢复；
- 持久的审批队列和事件流；
- 通知邮箱；
- 更好的后台进程生命周期管理。
## 作者的备注
<details>
<summary>关于该项目存在原因的个人备注</summary>
这个项目最初是一个假期编码项目，因为我不想浪费我的 Codex 额度。我的矛盾之处在于，这个额度似乎永远不够，而购买积分或使用 API 又感觉昂贵和不方便。我仍然希望一个 GPT 模型能够作为代理的决策中心，所以我开始关注 ChatGPT Web 作为主要界面。
最初的想法是让网络 GPT 将任务分解，设计工作器提示，审查需求和检查质量，然后使用 MCP 将执行工作发送到由较低成本的国内模型支持的克劳德代码。
事实证明这比预期更难。网络对话不能无限期运行，中断很常见，而隧道配置增加了摩擦。尽管如此，我仍然无法放弃我认为这个想法很出色，所以我继续努力，直到这个演示存在。完成的系统在两个方面减少了一些便利性和功能，这也许可以解释为什么这种方向在以前并不常见。
当我感到沮丧时，GPT 通过称它为“一个明显超出普通个人项目的 AI 代理基础设施实验”来安慰我。它的讨好技巧给我留下了深刻的印象，以至于我决定无论如何都要发布这个项目。这是我的第一个严肃的 GitHub 项目，因此来自感兴趣的访客的建议、实验、错误报告和小星星对我来说确实意义重大。
完整的原始中文备注可在 [README.zh-CN.md](README.zh-CN.md#作者的话) 中找到。
</details>
## 贡献和报告问题
欢迎提交 bug 报告和专注于 Alpha 强化贡献。在 GitHub 问题中开启：
- 最小的可复制性重现；
- 操作系统、PowerShell、Node.js 和克劳德代码版本；
- 模式和策略细节（无凭证）；
- 净化状态、错误代码和相关审计字段；
- 问题是否在 `mockWorker` 下重现。
不要在问题中粘贴 API 密钥、隧道 ID、个人路径、完整运行日志、提示、账本或用户数据。通过 [SECURITY.md](SECURITY.md) 中描述的 GitHub 安全顾问报告疑似漏洞。
有用的贡献包括 Windows 可移植性、固定覆盖范围、审计验证、文档和狭义的安全改进。B 阶段实施故意不在此 Alpha 版本之外。
## 许可证
MIT。参见 [LICENSE](LICENSE)。依赖许可仅作为工程发布检查审查，而非法律建议。
