Skip to content

AGENTS.md

Latest commit

 

History

History
84 lines (63 loc) · 5 KB

AGENTS.md

File metadata and controls

84 lines (63 loc) · 5 KB
Raw

AGENTS.md · Agent-RPA 开发指南

面向在本仓库工作的 Agent 与开发者。先从 docs/blueprint/ 理解系统边界，再按 OpenSpec change 实施；蓝图是目标架构真理源，openspec/specs/ 是已实现行为的规格真理源，活跃 change 表达尚未归档的增量。

项目定位

Agent-RPA 是面向 Agent 的浏览器 RPA 底座：外部 Agent 探索一次，底座把过程结晶为参数化技能，之后以确定性执行引擎进行 0 Token 回放与批量运行。底座本身不内置 Agent，认知能力经 Cognition Port 接入。

当前仓库处于 alpha：M0–M3 和 M4 orchestration-governance 已归档；batch-parameter-template、mcp-agent-interface、agent-driver-adapters、service-mode-multinode 仍是活动 change。daemon 中真实 transport/replay 装配尚有占位，fake/契约级 e2e 不得表述为真实站点生产验收。

不可违背的架构不变量

  • I-1 传输是接口（BrowserNode），上层不依赖具体驱动库。
  • I-2 技能包只存“做什么”；轨迹与时序在回放时按身份画像重新采样。
  • I-3 指纹从单一 (profile, seed) 派生并跨面自洽，不逐面随机。
  • I-4 回放/批量期底座零 LLM 调用；Token 只发生在外部 Agent 侧且被计量。
  • I-5 机密只进 Vault；技能包、配置示例和日志只见 %vault:...% 占位符。
  • I-6 底座不内置 Agent；无 Agent 时仍能完成确定性回放/批量，认知失败升级人工。

违反不变量的改动必须在对应 change 的 design.md 中说明理由、替代方案、风险与回滚，并增加守护测试。

技术栈与边界

  • Go 1.26+：praxisd 控制面单二进制。
  • MCP inbound + gRPC/REST；Cognition Port outbound。
  • BrowserNode 使用 gRPC over UDS，本地驱动藏在契约之后。
  • T0 TLS-HTTP / T1 Patchright / T2 裸 CDP / T3 极限档位。
  • OpenSpec 1.4.3，schema 为 spec-driven。
  • Python 只属于驱动子进程；控制面不得因驱动实现引入 Python/Node 依赖。

核心目录：

cmd/praxisd/        守护进程入口与装配
internal/           orchestrator、registry、recorder、crystallizer、interpreter、
                    selfheal、batch、locator、sensing、cognition、transport、
                    policy、vault、observability
api/proto/          BrowserNode / Cognition 契约
drivers/            T0–T3 传输驱动子进程
pkg/                技能包 schema 与公共类型
test/               integration / e2e / invariants
docs/blueprint/     目标架构真理源
docs/roadmap/       change DAG 与实施 gate
openspec/           现状规格、活动 change、归档 change

工作方式

  1. 先读与任务直接相关的蓝图、openspec/specs/、活动 change 的 proposal.md、design.md、tasks.md；不要把规划能力当作已实现能力。
  2. 编码前写明假设、歧义、成功标准和验证方式。涉及新能力或架构边界时先建/修订 OpenSpec change，并通过 openspec validate <change> --strict。
  3. 实现严格对应 tasks.md，及时更新任务状态。共享契约先冻结，再按 Parallelization Plan 分派互不重叠的 sub-agent 文件切片。
  4. 优先复用现有接口和实现；新增抽象、依赖或跨包调用必须在 design.md 论证。
  5. 注释解释“为什么、权衡和约束”，不复述代码行为。
  6. 不把 fake、stub、bufconn 或静态守护测试包装成真实 Chrome、真实站点或生产验收。

产出物使用简体中文；命令、路径、代码标识符、API 名和 JSON/YAML key 保持英文。

验证门槛

常规变更至少运行：

go test ./...
go build ./...
openspec validate --all --strict
git diff --check

按风险追加：

  • 契约：BrowserNode / Cognition Port 契约测试，确保驱动可替换（I-1/I-6）。
  • 集成：go test -tags=integration ./test/...；真实浏览器声明必须提供本地 Chrome 运行证据。
  • driver-cdp：make driver-cdp-test、make driver-cdp-license-check；不得内联未评估的 AGPL 代码。
  • 不变量：回放/批量 token_cost == 0，仓库/技能包/日志无机密明文。
  • e2e：明确记录所用 driver、是否真实 Chrome、目标站点和未覆盖 gate。

Git 与发布卫生

  • 未经用户明确要求不创建 commit、tag、release 或 push；得到授权后仍只提交已审阅范围。
  • 不提交 .env、私钥、Vault 数据、浏览器 Profile、截图/trace/HAR、运行数据库、日志、覆盖率、构建产物、虚拟环境、依赖缓存或导出结果。
  • 暂存前运行 git status --short --untracked-files=all、git diff --cached --check，并检查大文件与疑似凭据。
  • 不用 git add -A 掩盖混合工作区；已存在的用户改动必须保留、归属并验证。
  • commit 信息聚焦“为什么”并关联 change 名；归档 change 与实现/规格状态保持一致。
  • 对外发布必须准确说明 alpha 状态、实施 gate、许可证状态与责任使用边界。