Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 35 additions & 59 deletions README.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,25 +13,18 @@ approval checks, replay protection, and replayable Evidence.
The project originally validated this control path through a software-repair
scenario on [AgentTeams](https://github.com/agentscope-ai/AgentTeams). AgentTeams,
Higress, Matrix, and MinIO are reference integrations, not the Gateway's core
runtime boundary.

> **Verification baseline (2026-08-25):** AgentTeams `v1.1.2` completed the
> `Administrator -> Manager -> Investigator -> Verifier -> authenticated Higress
> -> Policy Broker -> immutable Docker pytest sandbox` path with
> `minimax-cn / MiniMax-M2.5` and exactly one governed `SUCCEEDED` ToolCall.
> Historical clean-clone Lite evidence is **339 passed / 0 failed / 3 skipped
> (opt-in Docker tests)**; the frozen `v0.1.0` gate is **375 passed / 3 skipped**.
> The latest public-main GitHub Actions gate built the immutable sandbox
> image and passed **380 tests / 0 skipped**; the current worktree collects 380 tests. The
> versioned Task 24 benchmark is **6 PASSED / 0 NOT_RUN**. The Skill catalog is
> **2 PUBLISHED / 4 QUARANTINED**; team-original `patch-scope-validator` v1.0.1
> has three strictly replayed governed invocations. Human L2 approval is `APPROVED`,
> and upstream PR [#1141](https://github.com/agentscope-ai/AgentTeams/pull/1141) remains
> `OPEN`. The real recording, anonymous public playback, and formal `v0.1.0`
> Release are verified. The audited eight-entry P0 package is complete with
> SHA-256 `0c5dfeb0ba6665609a14129a76cc1c239aed882a17e930c144aa5d3b88f6c306`;
> The project is now frozen as a reproducible resume-grade prototype; new
> AgentTeams features and competition-page work are out of scope.
runtime boundary. This is a reproducible resume-grade prototype, not a production
standalone Gateway distribution.

## Current Verification

| Scope | Result | Notes |
| --- | --- | --- |
| Local Lite | `382 passed / 3 skipped` | Current PR worktree; skipped tests require Docker. Ruff and strict mypy pass. |
| GitHub Actions Full | `380 passed / 0 skipped` | Latest verified public `main` baseline; this PR is awaiting CI. |
| Task 24 benchmark | `6 PASSED / 0 NOT_RUN` | Archived three-case, two-mode benchmark. |

These numbers describe different environments. See the [verification baseline and history](docs/verification-baseline.zh-CN.md) for archived integration and release evidence.

## Project Positioning

Expand All @@ -45,20 +38,6 @@ runtime boundary.
- Boundary: this is not a code-review product or an Agent orchestrator, and it
does not replace OpenCodeReview or AgentTeams

## Verification Evidence

- Paid evidence Provider: `minimax-cn / MiniMax-M2.5`
- Task 24 completed the three-case, two-mode matrix 6/6; Task 17 proves one
complete governed ToolCall path
- Latest public-main gate: 380 passed / 0 skipped with the immutable Docker
sandbox tests enabled; frozen `v0.1.0` gate: 375 passed / 3 skipped;
current local Lite snapshot: 377 passed / 3 skipped / 0 failed (380 collected);
Ruff, strict
mypy, and pip-audit pass
- Skill status: `code-review-and-quality` and team-original
`patch-scope-validator` v1.0.1 are `PUBLISHED`; four upstream Skills remain
`QUARANTINED`

Historical competition evidence remains indexed in the
[preliminary submission record](docs/competition/agentloom-preliminary-submission.md).
The Gateway boundary and migration plan are in the
Expand Down Expand Up @@ -86,7 +65,7 @@ The full design is in the [AgentLoom architecture](docs/architecture/agentloom-a

## Model-Free Quick Start

Prerequisites: Python 3.12 and Git. These commands make no model or paid API call.
Prerequisites: Windows 10/11, PowerShell 7, Python 3.12, and Git. The [Windows quickstart](docs/deployment/quickstart.md) provides one install/demo path, expected output, evidence locations, and troubleshooting. It makes no model or paid API call.

```powershell
python -m venv .venv
Expand All @@ -105,6 +84,8 @@ Run either deterministic repair case without an LLM or cloud quota:
```

Replace `severity-normalization` with `pagination-boundary` for the second case.
Inspect the independent verification summary at
`artifacts/demo/severity-normalization/artifacts/test-results.txt`.
Launch the local evidence control panel with:

```powershell
Expand Down Expand Up @@ -184,31 +165,26 @@ uses the pinned Docker backend and does not export that acknowledgement. Never
put the signing key, model credentials, or raw provider secrets in committed MCP,
Worker, or Provider Profile configuration.

## Historical Evidence

> The items below are retained for audit and reproduction. They are **not the
> current evidence baseline**. Qwen and DeepSeek remain disabled because their
> accounts have no balance. MiniMax and StepFun are authorized subscription
> Providers, but every new run must use a unique run ID and exact Provider/model
> evidence. The accepted Task 24 report remains immutable MiniMax history; a
> future MiniMax or StepFun diagnostic must never overwrite it. Do not replay
> historical paid paths as if they were new.

- On 2026-08-04, Qwen `qwen3.7-plus` completed an unattended repair that passed
independent visible, host-only hidden, and static checks. The generated patch
SHA-256 is
`7d9d571a833eabaedf97eac73dad50f6290bfa332d3ef504882398ba2e6d0833`.
Strict run evidence remains at
`artifacts/agentteams/live-repair-pagination-qwen-unattended-03.json`; independent
verification remains under
`artifacts/live-repair/AL-LIVE-PAGINATION-UNATTENDED-20260804-03/verified/artifacts/`.
- The earlier StepFun four-role rollback and DeepSeek message-baseline evidence
remain historical inputs to the Human L2 approval record. Their redacted
summary is in
[L2 approval and upstream contribution evidence](docs/competition/l2-approval-and-upstream-contribution-evidence.md).
- Historical replay entry points remain `scripts/competition-demo.ps1 -Mode replay`
and `scripts/competition-rollback-demo.ps1 -Mode replay`. Replay is model-free;
live mode is a separate, explicitly paid and authorized operation.
The FastAPI control plane's `/internal/*` routes are also a trusted boundary.
Apply database migrations, then inject a token of at least 32 ASCII characters
through the process environment or a secret manager before starting the service:

```powershell
.venv\Scripts\alembic upgrade head
$env:AGENTLOOM_INTERNAL_API_TOKEN = "replace-with-at-least-32-ascii-characters"
.venv\Scripts\agentloom serve
```

The service binds only to `127.0.0.1:8000` by default. Bind to another address
only behind a gateway that restricts sources and configures TLS. Callers must
send `Authorization: Bearer <token>` to `/internal/*`. A missing token prevents
startup; missing or invalid request tokens receive `401` before approval,
transition, or Grant verification logic runs.

Historical live evidence is retained for audit. Qwen and DeepSeek remain disabled;
new paid runs require a unique run ID and exact Provider/model evidence. The
archived Task 24 report must not be overwritten. Historical replay is model-free;
live mode is a separate, explicitly paid and authorized operation.

## Project Status

Expand Down
78 changes: 33 additions & 45 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,30 +10,23 @@

AgentLoom 是一个 **Agent Tool Policy Gateway** 原型。当 Agent 想调用工具(改代码、跑测试、写文件)时,Gateway 强制校验:调用方身份 / 短时一次性授权 / 参数白名单 / 审批 / 沙箱 / 可回放证据。任何一项不通过 = 拒绝并留证据。

**这个项目展示的工程能力**:多 Agent 系统的边界设计、HMAC 签名授权、防重放 nonce、不可变 Docker 沙箱、可观测证据链、Pydantic 契约测试——所有跑通的 380 项测试 + 6 项 AgentTeams 端到端任务都基于此。
**这个项目展示的工程能力**:多 Agent 系统的边界设计、HMAC 签名授权、防重放 nonce、不可变 Docker 沙箱、可观测证据链和 Pydantic 契约测试。可以先运行无模型 Demo,再查看分层验证证据。

**招聘者快速查看**:[两分钟项目速览](docs/portfolio-brief.zh-CN.md) · [公开 Demo(3:41)](docs/demo.html) · [无模型快速开始](#无模型快速开始)

## 为什么做这个

2026 年的 Agent 已经能写代码、改 bug、跑测试。但**它们能不能被信任**,是另一个问题。一次工具调用出错就可能删错文件、跑错测试、泄露密钥。AgentLoom 解决的是 Agent 工具调用层的可治理性——给 Agent 调用工具加上"权限校验 + 不可抵赖的证据",让 Agent 在工程团队里可被审计、可被回滚、可被审批。

---
## 当前验证状态

AgentLoom 是一个 Agent Tool Policy Gateway 原型,为 Agent 工具调用提供身份绑定、
短时单次 Grant、参数与路径限制、审批、防重放和可回放 Evidence。
| 范围 | 结果 | 说明 |
| --- | --- | --- |
| 本地 Lite | `382 passed / 3 skipped` | 当前 PR 工作树的默认测试;跳过项需要 Docker。 |
| GitHub Actions Full | `380 passed / 0 skipped` | 已验证的 public `main` 基线;本次 PR 尚待 CI 运行。 |
| Task 24 基准 | `6 PASSED / 0 NOT_RUN` | 三个案例分别在两种模式下完成。 |

> `v0.1.0` 门禁为 **375 passed / 3 skipped**。当前 public main 的 GitHub Actions
> 会构建不可变沙箱镜像;最新 Full 证据为 **380 passed / 0 skipped**,当前工作树
> 收集 380 项测试;Task 24 两模式基准为
> **6 PASSED / 0 NOT_RUN**。Skill 目录状态为 **2 PUBLISHED / 4 QUARANTINED**;
> 团队原创 `patch-scope-validator` v1.0.1 的三次治理调用均已严格重开。
> Human L2 审批为 `APPROVED`,上游 PR
> [#1141](https://github.com/agentscope-ai/AgentTeams/pull/1141) 仍为 `OPEN`。
> 真人录制、匿名公开播放和正式 `v0.1.0` Release 均已验证。最终八项 P0
> 提交包已完成审计,SHA-256 为
> `0c5dfeb0ba6665609a14129a76cc1c239aed882a17e930c144aa5d3b88f6c306`;
> 项目当前冻结为可复现的简历版原型,不再以竞赛页面或新的 AgentTeams 功能为开发目标。
这些数字描述不同验证环境,不能互相替代。完整历史记录和发布摘要见[验证证据](docs/verification-baseline.zh-CN.md)。

## 项目定位

Expand All @@ -45,16 +38,9 @@ AgentLoom 是一个 Agent Tool Policy Gateway 原型,为 Agent 工具调用提

## 验证证据

- 当前付费证据 Provider:`minimax-cn / MiniMax-M2.5`
- Task 24 三案例两模式矩阵完成 6/6;Task 17 证明一条完整受治理 ToolCall 链路
- 最新 public main Full 门禁:启用不可变 Docker 沙箱测试后 380 passed / 0 skipped;
冻结 `v0.1.0` 门禁:375 passed / 3 skipped;当前本地 Lite 快照:
377 passed / 3 skipped / 0 failed(当前工作树共收集 380 项);Ruff、strict mypy、pip-audit 通过
- Skill 状态:`code-review-and-quality` 与团队原创 `patch-scope-validator` v1.0.1
为 `PUBLISHED`,其余四个上游 Skill 保持 `QUARANTINED`

完整历史竞赛证据仍见[初赛提交记录](docs/competition/agentloom-preliminary-submission.md)。
Gateway 的目标边界和迁移计划见[产品规格](docs/specs/agent-tool-policy-gateway.md)。
受治理 ToolCall 的端到端记录、Task 24 基准和历史发布证据见
[验证基线与历史记录](docs/verification-baseline.zh-CN.md)。竞赛材料另见
[初赛提交记录](docs/competition/agentloom-preliminary-submission.md)。Gateway 的目标边界和迁移计划见[产品规格](docs/specs/agent-tool-policy-gateway.md)。

## 架构

Expand All @@ -77,7 +63,10 @@ pytest 放入全新、禁网、只读挂载工作区的 Docker 沙箱运行。

## 无模型快速开始

前置条件:Python 3.12 和 Git。以下命令不会调用模型或付费 API。
前置条件:Windows 10/11、PowerShell 7、Python 3.12 和 Git。以下命令不会调用模型或付费 API。

完整的单入口流程(安装、确定性 Demo、预期输出、证据位置和故障排查)见
[Windows 快速开始](docs/deployment/quickstart.md)。

```powershell
python -m venv .venv
Expand All @@ -96,6 +85,12 @@ python -m venv .venv
```

将 `severity-normalization` 替换成 `pagination-boundary` 即可运行第二个案例。
查看 Demo 的验证摘要:

```powershell
Get-Content .\artifacts\demo\severity-normalization\artifacts\test-results.txt
```

本地证据控制面板的启动方式为:

```powershell
Expand Down Expand Up @@ -167,25 +162,18 @@ $env:AGENTLOOM_POLICY_SIGNING_KEY = "replace-with-a-local-development-secret"
签名密钥、模型凭据和 Provider 原始密钥都不得写入已提交的 MCP、Worker 或 Provider
Profile 配置。

## 历史证据

> 以下内容仅为审计和复现而保留,**不是当前证据基线**。Qwen、DeepSeek 因账户
> 无余额继续禁用。MiniMax 和 StepFun 均已获得订阅调用授权,但每次新运行必须使用
> 唯一 run ID 并记录准确 Provider/模型;StepFun 证据不得混入只允许 MiniMax 的
> Task 24 版本化基准。不得把历史付费链路冒充为新运行。

- 2026-08-04,Qwen `qwen3.7-plus` 曾完成无人值守修复,并通过独立的可见测试、
主机专属隐藏测试和静态检查。生成补丁 SHA-256 为
`7d9d571a833eabaedf97eac73dad50f6290bfa332d3ef504882398ba2e6d0833`。
严格运行证据仍位于
`artifacts/agentteams/live-repair-pagination-qwen-unattended-03.json`,独立验证证据仍位于
`artifacts/live-repair/AL-LIVE-PAGINATION-UNATTENDED-20260804-03/verified/artifacts/`。
- 更早的 StepFun 四角色回滚和 DeepSeek 消息基线证据仍作为 Human L2 审批记录的
历史输入。脱敏摘要见
[L2 审批与上游贡献证据](docs/competition/l2-approval-and-upstream-contribution-evidence.md)。
- 历史回放入口保留为 `scripts/competition-demo.ps1 -Mode replay` 和
`scripts/competition-rollback-demo.ps1 -Mode replay`。回放无需模型;Live 模式是独立、
必须明确付费并授权的操作。
FastAPI 控制面中的 `/internal/*` 路由同样属于受信边界。启动服务前先应用数据库迁移,
再从进程环境或密钥管理注入至少 32 个 ASCII 字符的 token:

```powershell
.venv\Scripts\alembic upgrade head
$env:AGENTLOOM_INTERNAL_API_TOKEN = "replace-with-at-least-32-ascii-characters"
.venv\Scripts\agentloom serve
```

服务默认只绑定 `127.0.0.1:8000`;只有在网关限制来源并配置 TLS 后才应绑定其他地址。
调用方访问 `/internal/*` 时必须发送 `Authorization: Bearer <token>`。缺少 token 时服务拒绝
启动,缺少或错误的请求 token 返回 `401`,不会进入审批、状态迁移或 Grant 验证逻辑。

## 项目状态

Expand Down
37 changes: 35 additions & 2 deletions docs/deployment/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

This path runs a deterministic repair without Docker, AgentTeams, or a cloud
model. It is the fastest way to confirm that a clone and its Python environment
work.
work. It is also the recommended first link for a reviewer: the run is bounded,
repeatable, and leaves inspectable evidence.

## Requirements

Expand All @@ -19,13 +20,34 @@ Set-Location AgentLoom

.\scripts\bootstrap.ps1 -Profile lite
.\scripts\demo.ps1
.\.venv\Scripts\agentloom tui
```

The bootstrap creates `.venv`, installs AgentLoom, and applies the local SQLite
migrations. The demo runs the `severity-normalization` Case and writes ignored
evidence under `artifacts/demo/severity-normalization/`.

Expected output ends with:

```text
Demo passed. Evidence: ...\artifacts\demo\severity-normalization
```

Inspect the independent verification summary with:

```powershell
Get-Content .\artifacts\demo\severity-normalization\artifacts\test-results.txt
```

The file should contain `PATCHED TESTS: PASSED`, `HIDDEN TESTS: PASSED`, and
`STATIC CHECKS: PASSED`. The surrounding directory also contains the patch,
risk report, verification result, and redacted evidence JSON.

Open the local evidence panel separately with:

```powershell
.\.venv\Scripts\agentloom tui
```

Run the second bounded Case with:

```powershell
Expand All @@ -34,3 +56,14 @@ Run the second bounded Case with:

Neither command requires or reads a model API key. For the four-role runtime,
continue with [full AgentTeams deployment](windows-agentteams.md).

## Common failures

- **Python version error:** install Python 3.12 and rerun bootstrap. AgentLoom
deliberately rejects 3.11 and 3.13 so the evidence environment stays fixed.
- **Demo output already exists:** choose a new output directory with
`.\scripts\demo.ps1 -OutputRoot .\artifacts\demo\my-run`; the runner refuses
to overwrite evidence from an earlier run.
- **TUI cannot start:** run bootstrap first and verify that
`.venv\Scripts\agentloom.exe` exists. The TUI is a local evidence viewer; it
does not replace the deterministic verification command.
22 changes: 22 additions & 0 deletions docs/verification-baseline.zh-CN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# 验证基线与历史记录

此页区分当前工作树验证、已合并主线结果和历史集成记录。不同环境的数字不能互相替代。

## 当前验证

- 当前 PR 工作树 Lite:`382 passed / 3 skipped`;Ruff 和 strict mypy 通过。三个跳过项为可选 Docker 测试。
- public `main` 最近记录的 Full 门禁:`380 passed / 0 skipped`,CI 构建锁定的沙箱镜像后运行。本 PR 的 Full 门禁结果待 GitHub Actions 完成后更新。
- Task 24 三案例、两种模式基准:`6 PASSED / 0 NOT_RUN`。这是已归档基准,不是本次改动刚产生的结果。
- 冻结 `v0.1.0` 门禁:`375 passed / 3 skipped`。

当前付费链路记录的 Provider 是 `minimax-cn / MiniMax-M2.5`。Task 17 记录一条完整受治理 ToolCall。Skill 状态、原始证据引用和发布包审计摘要由仓库中的版本化证据文件维护;这些记录不等于新运行结果。

## 历史运行

以下材料仅用于审计和复现,不是当前验证基线。Qwen 与 DeepSeek 因账户无余额保持禁用。每次新的 MiniMax 或 StepFun 运行都必须使用唯一 run ID 并记录准确 Provider/模型;StepFun 记录不得计入只接受 MiniMax 的 Task 24 版本化基准。

- 2026-08-04,Qwen `qwen3.7-plus` 曾完成无人值守修复,通过独立可见测试、主机专属隐藏测试和静态检查。补丁 SHA-256:`7d9d571a833eabaedf97eac73dad50f6290bfa332d3ef504882398ba2e6d0833`。运行摘要位于 `artifacts/agentteams/live-repair-pagination-qwen-unattended-03.json`;独立验证产物位于 `artifacts/live-repair/AL-LIVE-PAGINATION-UNATTENDED-20260804-03/verified/artifacts/`。
- 早期 StepFun 四角色回滚和 DeepSeek 消息基线是 Human L2 审批记录的历史输入。脱敏摘要见[审批与上游贡献证据](competition/l2-approval-and-upstream-contribution-evidence.md)。
- 历史回放入口为 `scripts/competition-demo.ps1 -Mode replay` 与 `scripts/competition-rollback-demo.ps1 -Mode replay`。回放无需模型;Live 模式是独立的付费并授权操作。

完整竞赛沿革见[初赛提交记录](competition/agentloom-preliminary-submission.md)。架构目标和迁移计划见[产品规格](specs/agent-tool-policy-gateway.md)。
1 change: 1 addition & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ dependencies = [
"sqlalchemy>=2.0,<3",
"textual>=5,<6",
"typer>=0.16,<1",
"uvicorn>=0.35,<1",
]

[project.optional-dependencies]
Expand Down
Loading
Loading