内容
# 可靠表面
> 通过明确授权、持久日志和验证来控制代理操作。
可靠表面是一个用于控制代理操作的Python和MCP工作台。
它允许代理感知有限目标，提出操作，通过操作员加载的授权进行，然后在允许时执行，并在之后验证结果。
## 为什么它很重要
代理工作流需要自主权而不能有沉默的权威。这个仓库为开发者提供了一个用于审查操作的明确循环：观察、提出、授权、执行、验证和记录收据。
## 尝试使用
```powershell
git clone https://github.com/HarperZ9/accountable-surface.git
git clone https://github.com/HarperZ9/coherence-membrane.git
git clone https://github.com/HarperZ9/proof-surface.git
cd accountable-surface
$env:PYTHONPATH = "src;..\coherence-membrane\src;..\proof-surface\src"
python -m pip install -e ".[test]"
python examples/demo.py
python -m pytest
```
## 首先测试什么
- 运行 `examples/demo.py` 以查看基本可靠循环。
- 运行 `examples/actuate_demo.py` 以查看执行路径。
- 在将其连接到MCP客户端之前，运行 `examples/smoke_mcp.py`。
## 当前状态
具有本地示例、Python测试和MCP服务器入口点的Alpha包。
它依赖于下面设置命令中列出的 sibling 包。
## 开发者入口点
- Python 包：`src/accountable_surface/`
- MCP 服务器：`accountable_surface.server`
- CLI 脚本：`accountable-surface-server`
- 测试：`tests/`
- 使用指南：`USAGE.md`
- 交付合同：`project-docs/specs/SPEC-accountable-surface-forward-delivery.md`
## 现有技术笔记
> *感知和敏感性是通往新前沿的途径。机器学习自我问责。*
一个实时缝隙，其中模型**感知**和**行动**仅通过问责制 -
见证感知、执行前授权和篡改证据、持久内存 -
在人类监管下。由现有审计部分组成：
[coherence-membrane](https://github.com/HarperZ9/coherence-membrane) 器官
（见证感知）和 [proof-surface](https://github.com/HarperZ9/proof-surface) 的
授权（允许 / 拒绝 / 需要人类）。它**不**触及 ORCA。
## 为什么
一个与 Playwright 驱动浏览器并读取**截图**的并行代理
正在猜测像素。这个表面感知**结构** - 见证、
内容寻址读取与可伪造的自检 - 并通过明确、可撤销的操作员授权控制每个操作。
感知你可以审计；操作你可以在发生**之前**拒绝。
那是安全自主权的基质：危险的“跳过每个权限”在每个步骤都被见证、授权和自我检查时被限制。
## 循环
```
感知 -> 授权（允许 / 拒绝 / 需要人类） -> 执行（效应器） -> 验证 -> 见证
传入 proof-surface fs · web · OS 再感知 日志
```
- **感知** -- 器官发出见证的`Observation`s（出处摘要 + 可伪造的`selftest`），而非截图。
- **授权** -- 每个提议的操作都针对操作员的授权由 proof-surface 的执行前授权检查。*模型不能提供自己的授权。*
- **见证** -- 每个感知和决策都被记录；`interocept()` 是表面的见证、内容寻址视图，其自身行为在会话间是持久的（仅追加的 JSONL + 重放）。
## 教义
- 感知是**见证的**，而非截图。
- **意识不是权威** -- 模型可以自由感知，但不能授权自己的操作。
- **随时间问责** -- 日志仅追加且重放；自我视图是内容寻址的，因此记录不能悄悄更改。
- **仅在`允许`时操作，并验证** -- `提议`是建议性的；`执行`
完成循环：它仅在授权`允许`时执行，通过构造限定的效应器，然后**通过再感知验证**并回滚失败的可逆操作。什么也不被假定为已完成。
## 布局
- `src/accountable_surface/surface.py` -- `AccountableSurface`：`perceive`、`propose`
（授权）、`actuate`（完整的问责执行循环）、`interocept`（见证的自我视图）、持久日志。
- `src/accountable_surface/effector.py` -- 传出臂：`Effector`合约 +
`FilesystemEffector`（惰性直到授权；限定；可逆；自我验证）。
- `src/accountable_surface/web_effector.py` -- 原生 Web 执行：`WebEffector`
（导航 / 按标签填充 / 提交，源限定；**无浏览器，无外部依赖**）。
- `src/accountable_surface/os_effector.py` -- OS 执行：`CommandEffector`
（允许列表命令，限定 cwd，无 shell；不可逆 → 需要人类）。
- `src/accountable_surface/reference.py` -- **参考皮层**：一个接地器官
（见证的、相关性评分的参考；允许“未接地”；原生 arXiv 通过标准库）。
- `src/accountable_surface/http_driver.py` -- 真正的原生后端：标准库
`html.parser` + 见证的干净 GET/POST；驱动实时服务器渲染页面。
- `src/accountable_surface/server.py` -- 一个 FastMCP **实时 MCP 服务器** 暴露
`perceive`、`propose`、`session_journal`、`interocept`。
- `tests/` -- 90 个测试。`examples/`：`demo.py`、`actuate_demo.py`、
`web_actuate_demo.py`（原生 Web 执行与真实的 localhost 服务器）、
`goal_demo.py`（限定自主权）、`grounding_demo.py`（参考皮层允许
当它无法接地时）、`grounded_actuate_demo.py`（一个操作必须引用接地
参考）、`smoke_mcp.py`（一个真实的 MCP stdio 往返）。
- `docs/` -- 设计规格（自我感知、持久性、执行）。
## 安装和运行
此项目组合了两个 sibling 仓库，不通过 PyPI；将它们放在路径上（或
可编辑安装它们）。**coherence-membrane 必须包含 `WebDocumentOrgan`**
（分支 `feat/web-and-external-organs` 或更高版本）。
```powershell
$env:PYTHONPATH = "src;C:\dev\public\coherence-membrane\src;C:\dev\public\proof-surface\src"
python -m pytest # pytest 添加 ./src
python examples/demo.py # 可运行的转录
python examples/smoke_mcp.py # 实时 MCP 往返（需要 mcp）
# 实时 MCP 服务器
python -m pip install -e ".[server]" # 添加 mcp
python -m accountable_surface.server
```
## 连接到 MCP 客户端
```json
{
"mcpServers": {
"accountable-surface": {
"command": "python",
"args": ["-m", "accountable_surface.server"],
"env": {
"PYTHONPATH": "C:/dev/public/accountable-surface/src;C:/dev/public/coherence-membrane/src;C:/dev/public/proof-surface/src",
"ACCOUNTABLE_SURFACE_GRANTS": "C:/path/to/operator-grants.json",
"ACCOUNTABLE_SURFACE_JOURNAL": "C:/path/to/session-journal.jsonl"
}
}
}
}
```
### 操作员授权（`ACCOUNTABLE_SURFACE_GRANTS`）
一个 JSON 文件，包含一个授权授权或列表。**模型不能提供其
自己的授权** -- 只有操作员加载的授权控制操作；如果没有加载，则
授权是**默认拒绝**。授权是自主权范围：其
`scope.allowed_actions` / `allowed_targets` 限定表面可以执行的操作。
### 持久内存（`ACCOUNTABLE_SURFACE_JOURNAL`）
一个追加 JSONL 文件的路径。当设置时，日志在启动时重放并
追加每个感知/决策 - 因此见证的自我视图跨会话持续。
## 路线图
**已构建（v0）：** 见证感知 · 执行前授权 · 自我感知 · 持久
内存 · 实时 MCP 服务器 · **传出臂** -- 可靠执行与 **三个
原生后端** (`FilesystemEffector`; `WebEffector` 在真实的 stdlib HTTP/HTML
驱动程序上 - 导航、填充标签、提交；`CommandEffector` 用于允许列表的 OS
命令），作用于*结构*而非像素，通过感知→计划→授权→执行→
再感知→验证循环与回滚。**不可逆**操作（POST、命令）
升级为需要人类，除非操作员传递`allow_irreversible`。构建为
*超越* Playwright 用于服务器渲染的 Web -- 无浏览器二进制文件。**目标/任务模式**
（`pursue`）以 **限定自主权** 运行多步骤计划 - 一个授权范围，无
每步提示 - 在步骤被拒绝或验证失败时停止。一个计划
（即使是模型的计划）不是权威；每一步都赚取它。**参考皮层**
（`ground`）为主题返回见证的、相关性评分的参考，并标记
**未接地** 而不是呈现无关的引用 - 接地不能洗白
坏源。它**连接到执行**：操作可能带有*理由*；一个
**未接地的前提升级为需要人类**（证据像权威一样被授权），并且
参考资料随结果一起传递作为操作的引用。
**下一步：** 更丰富的目标**规划**（将目标分解为步骤，每个步骤仍然被授权）；一个
更大的精选/内部语料库在参考皮层后面；和一个原生协议选项
用于实时表面。**核心中没有外部依赖**
- 标准库 + sibling 原生仓库；可选的 MCP 服务器（ `[server]`
额外）是唯一的边缘适配器。四个支柱：**问责制、可用性、
可访问性、效率**。
## 许可证
MIT (c) 2026 Zain Dana Harper
## 适用于开发人员
保持公共 README、包元数据和示例与当前行为一致。
在打开 PR 或推送发布之前，运行本地包验证路径。
```powershell
$env:PYTHONPATH = "src;C:\dev\public\coherence-membrane\src;C:\dev\public\proof-surface\src"
python -m pip install -e ".[test]"
python -m pytest
node --test web/*.test.mjs
```
