# 文本图形代理（TGA）
安全优先的代理平台 — 模型提议，记录决策
简体中文
·
架构
·
操作指南
·
提交准备
·
更新日志
## 什么是 TGA？
TGA 是一个**安全优先的代理平台**。用户请求首先由母代理进行理解，
转换为限定范围的 `TaskSpec`，分发给一次性的子代理，并在任何提议被视
为已接受状态之前，接受确定性规则的检查。
TGA 在人类与 AI 代理之间定义了一种**双向治理协议**：人类意图在被
Intent Firewall 稳定为 `TaskSpec` 之前，不被视为任务权威；而 AI 输出
在通过确定性约束检查并成为 `CheckedRecord` 之前，不被视为可信任的
状态。
同样的权限分离原则也适用于 **LLM 游戏**：模型可以叙述已批准的事实、
组织对话或提出面向玩家的文本，但它绝不能直接编写规范的游戏状态。
游戏状态应当来源于规则、已验证的记录或明确由人类批准的状态转换。
在许多代理工作流中，允许 LLM 直接影响状态——如果它生成了
幻觉事实、超出范围的文件编辑或绕过指令，这种污染就可能成为永久性的。
TGA 通过严格的分离来应对这种风险：
- **子代理提议**（`AgentProposal`）——它们不能直接写入状态。
- **约束层决策**（`ConstraintChecker`）——17 项确定性检查
会把关每一项提议，然后才能将其作为已接受的状态。
- **母代理清洗**——原始用户文本永远不会到达子代理；它们
只能看到经过清洗的 `TaskSpec`。
- **人类批准高风险转换**——实时代理调用、凭据更改
和护栏禁用，都必须在明确的批准检查点停止并等待批准。
## 研究脉络
TGA 是早期检查状态研究路线的代理平台延续。相关的公开成果有：
| 代码库 | 作用 |
|------------|------|
| [`rgbd-safe-minimal`](https://github.com/910636071/rgbd-safe-minimal) | 最早的洁净室最小化符号流水线：提议 -> 验证 -> 决策。 |
| [`constraint-checked-state-records`](https://github.com/910636071/constraint-checked-state-records) | 用于规范化记录、有限约束和检查状态报告的外部评审产出。 |
| [`checked-state-benchmark`](https://github.com/910636071/checked-state-benchmark) | 用于有限检查状态评估的下游合成基准测试脚手架。 |
TGA 将相同的状态权威边界应用于代理工作流：
```
human intent -> TaskSpec -> child-agent proposal -> constraint-checked record
```
请参阅[公开溯源成果](./docs/provenance_artifacts_20260704.md)，以获取
带有时间戳的代码库脉络及其声明范围。
## 快速开始
```
# 零依赖 — 纯 Python standard library
python -m text_graphics_agent.gui
# 打开 http://127.0.0.1:8012
```
在聊天流中自然地输入。闲聊会获得直接回复。对于真正
的工作，请描述任务并使用右侧的 **Task Scope** 卡片来设置
特定于任务的文件和验收基准；TGA 随后会分派一个子代理
并返回经过约束检查的提议。
## 架构
```
User Input
│
▼
┌─────────────────────────────────────────────────────┐
│ Pipeline (pipeline.py) │
│ 1. Intent Firewall (intent.py) │
│ → separates user claims from objective facts │
│ 2. Agent Registry (registry.py) │
│ → routes to best-matching specialist │
│ 3. Specialist (specialists.py) │
│ → BaseSpecialist.run(task) → AgentProposal │
│ → ToolContext (tools.py) for file access │
│ 4. Constraint Checker (constraints.py) │
│ → 17 deterministic checks gate every proposal │
│ 5. Result │
└─────────────────────────────────────────────────────┘
│
│ Multi-task orchestration:
▼
┌─────────────────────────────────────────────────────┐
│ AsyncGraphExecutor (async_executor.py) │
│ Independent nodes run in parallel │
│ Fail-fast: first rejection cancels all remaining │
└─────────────────────────────────────────────────────┘
```
### 核心模块
| 模块 | 作用 |
|--------|------|
| `intent.py` | Intent Firewall —— 分解原始文本，检测污染，提取用户声明 |
| `constraints.py` | 17 项模块化约束检查（范围、证据、权限、绕过、锚点、目标漂移、置信度等） |
| `orchestrator.py` | 母代理 —— 清洗任务，分派专家，汇总分数 |
| `pipeline.py` | 编排完整的请求工作流（聊天 → 任务 → 裁决） |
| `registry.py` | 代理注册表 —— 基于能力并通过意图代码 + 目标标记进行路由 |
| `specialists.py` | `BaseSpecialist` 接口 + `LocalSimulationSpecialist` + `LiveSpecialist` |
| `tools.py` | `ToolContext` —— 实施范围限制的文件工具（read_file, glob, grep） |
| `memory.py` | 策展记忆 —— 辅助母代理的不可信上下文，绝不影响约束 |
| `async_executor.py` | 带有快速失败安全机制的并发图执行器 |
| `gui.py` | 零依赖的 HTTP 服务器（仅使用标准库） |
| `web_resources.py` | 单页仪表板（聊天流、历史记录、任务范围面板、设置、检查器） |
## 编写自定义专家
```
from text_graphics_agent.specialists import BaseSpecialist
from text_graphics_agent.profiles import SpecialistProfile
from text_graphics_agent.records import AgentProposal, RecordEnvelope, TaskSpec
class CodeReviewerSpecialist(BaseSpecialist):
profile = SpecialistProfile(
specialist_id="code-reviewer-001",
role="code_reviewer",
allowed_scopes=(),
tools=("read_file", "glob", "grep"),
)
def run(self, task: TaskSpec) -> list[AgentProposal]:
# Tools are scope-enforced — can't read outside task.allowed_scopes
result = self.tools.read_file(task.allowed_scopes[0])
content = result.data if result.ok else ""
return [AgentProposal(
envelope=RecordEnvelope.for_task(
actor="child:code-reviewer",
target=task.task_id,
cause="review",
scope_id="code",
),
task_id=task.task_id,
child_agent_id="code-reviewer-001",
child_role="code_reviewer",
proposal_kind="analysis",
claim=f"Reviewed {task.allowed_scopes[0]}: found {content.count('TODO')} TODOs",
evidence=task.allowed_scopes,
proposed_scopes=task.allowed_scopes,
proposed_outputs=("analysis",),
required_anchor_text="",
test_commands=("python tests/text_graphics_agent_test.py",),
confidence=0.85,
)]
```
注册它：
```
from text_graphics_agent.registry import AgentRegistry
from text_graphics_agent.pipeline import Pipeline
registry = AgentRegistry()
registry.register(
specialist_id="code-reviewer-001",
factory=lambda allowed_scopes=(), required_anchors=(): CodeReviewerSpecialist(),
handles_intent=("bug_review", "verification"),
handles_markers=("settings_panel", "layout"),
priority=100,
)
pipeline = Pipeline(registry=registry)
result = pipeline.submit("Check settings panel for bugs")
```
## 17 项约束检查
| # | 约束 | 拦截内容 |
|---|-----------|----------------|
| 1 | Envelope | 格式错误的记录元数据 |
| 2 | Proposal Kind | 超出 analysis/patch_plan/expression/test_plan 之外的虚构操作类型 |
| 3 | Task Mismatch | 针对不同任务 ID 的提议 |
| 4 | Sanitized Task | 绕过母代理清洗的任务 |
| 5 | Authority | 子代理声称拥有母代理/账本/系统角色 |
| 6 | Metadata Leak | 原始用户文本通过元数据字段泄漏 |
| 7 | Claim | 空的修改声明 |
| 8 | Evidence | 没有独立证据的提议 |
| 9 | Evidence Scope | 证据路径在允许范围之外或包含目录遍历 |
| 10 | Test | 当需要测试时缺失测试命令 |
| 11 | Test Command Safety | 破坏性 shell 命令（rm -rf, format 等） |
| 12 | Bypass Language | “跳过测试”、“直接批准”、“无需审查” |
| 13 | Scope | 文件更改在允许的范围白名单之外 |
| 14 | Forbidden Output | 直接写入持久化事实（confirmed_fact, committed_fact） |
| 15 | Anchor | 缺失或伪造的证据链锚点 |
| 16 | Goal Alignment | 偏离已清洗目标的提议 |
| 17 | Confidence | 置信度分数在 [0.0, 1.0] 之外 |
## 策展记忆（不可信）
TGA 的母代理会在不同会话间积累记忆——包括常见范围、任务
模式、违规反馈。**但记忆是不可信的上下文：**
- 它会进入 `mother_notes`（审计日志），**绝不**进入 `TaskSpec.objective`（子代理的指令）
- 它**绝不**影响约束决策
- 它会随时间衰减（每天 5%），并在置信度低于 15% 时被修剪
- 用户可以在 Inspector 面板中查看和删除记忆
## 适用范围
TGA 不宣称自己是 AGI、消除幻觉的万能药，或是完整的
提示词注入解决方案。它的声明范围更窄：它展示了一种协议
边界，在此边界中，子代理接收经过清洗的任务，只能提交提议，
并且在状态更改被信任之前，必须接受确定性约束和人类批准关卡的检查。
## 支持的 LLM 提供商
| 提供商 | 状态 | 备注 |
|----------|--------|-------|
| DeepSeek | ✅ 已测试 | OpenAI 兼容端点 |
| OpenAI | ✅ 已支持 | OpenAI 兼容端点 |
| Gemini | ✅ 已支持 | 原生 Gemini API |
| Mock | ✅ 内置 | 离线确定性模式 |
在 Settings → Connection 中配置，或编辑 `config.json`。
## 测试
```
python tests/text_graphics_agent_test.py
```
包含 1055+ 项断言，涵盖约束检查、协调器分派、图
执行、实时 LLM 修复、Web API 等内容。
## 论文与联系方式
- 论文草稿：[docs/paper_draft.md](./docs/paper_draft.md)
- 防御性出版物：[docs/defensive_publication.md](./docs/defensive_publication.md)
- 提交准备：[docs/submission_prep.md](./docs/submission_prep.md)
- 联系人：Lijie Wang，独立研究员，
## 许可证
Apache-2.0 —— 详见 [LICENSE](./LICENSE)。