README.md

Agent-RPA 开发路线图（SDD 驱动）

本路线图把蓝图拆分为可独立提案、可独立实现的 OpenSpec 变更（change），并给出依赖 DAG 与阶段。每个 change 是一个内聚的功能切片，产出 proposal → specs → design → tasks 四件套，位于 openspec/changes/<change-id>/。

进度快照（2026-07-12）：M0–M4 主体已归档；M5 的 agent-driver-adapters、mcp-agent-interface、本地 web-management-api 及其 close-console-api-contract-gaps 增量已归档。Web API 继续挂同一 daemon listener，并已补齐 Console 所需的 Schedule 单项 ETag、artifact links/PNG preview、Run/Overview 安全摘要、System v1/Cognition、skill opaque locator/evidence 与短期 validation report 下载；这只解除后端 Contract/Read/Mutation gate，不表示 Console 页面已实现。M6 service-mode-multinode 已实现并归档（28/28 任务）：mTLS+TCP 承载/多节点调度/Postgres+对象存储后端均为契约与真实后端（Postgres 16/minio）级验证，节点侧运行时（真实驱动挂载）仍是占位 gate。真实 Chrome/T0–T3/外部 Agent 全链仍需单独证据。

---

拆分原则

1. 契约先行：BrowserNode、Cognition Port、技能包 schema 三份契约是所有实现的地基（守蓝图 I-1/I-6），必须最先冻结。
2. 分级验证蓝图：M1 先以 BrowserNode 契约级 e2e 验证“探索→结晶→0 Token 影子回放”；真实 Chrome/T2 全链、目标站点与抗检测表现作为独立发布 gate。
3. 一个 change 一个能力边界：每个 change 对应 1–N 个 kebab-case capability，边界清晰、可并发实现。
4. 不变量守护贯穿：每个 change 的 tasks.md 必须把相关不变量（I-1..I-6）转为可验证任务。

---

变更依赖 DAG

flowchart TB
    subgraph M0["M0 · 骨架与契约（地基）"]
        A1["bootstrap-praxisd-skeleton"]
        A2["browsernode-contract"]
        A3["cognition-port-contract"]
        A4["skill-package-schema"]
    end
    subgraph M1["M1 · 高强度闭环（首个垂直切片）"]
        B1["browser-runtime-lifecycle"]
        B2["transport-driver-cdp-t2"]
        B3["explore-record-crystallize"]
        B4["replay-interpreter-zero-token"]
    end
    subgraph M2["M2 · 自愈与韧性"]
        C1["multimodal-sensing"]
        C2["locator-repository"]
        C3["self-heal-tiered"]
    end
    subgraph M3["M3 · 隐身阶梯完备"]
        D1["behavior-synthesis"]
        D2["fingerprint-coherence"]
        D3["stealth-ladder-tiers"]
    end
    subgraph M4["M4 · 编排治理与批量"]
        E1["orchestration-governance"]
        E2["batch-parameter-template"]
    end
    subgraph M5["M5 · Agent 接口与驱动可插拔"]
        F1["mcp-agent-interface"]
        F2["agent-driver-adapters"]
    end
    subgraph M6["M6 · 服务化（可选）"]
        G1["service-mode-multinode"]
    end

    A2 --> B1
    A2 --> B2
    A1 --> B1
    A4 --> B3
    A3 --> B3
    A2 --> B3
    A4 --> B4
    B1 --> B4

    A2 --> C1
    A4 --> C2
    B4 --> C3
    C1 --> C3
    C2 --> C3
    A3 --> C3

    A2 --> D1
    B1 --> D2
    B2 --> D3
    D1 --> D3
    D2 --> D3

    A1 --> E1
    B4 --> E1
    B4 --> E2
    A4 --> E2
    E1 --> E2

    B3 --> F1
    B4 --> F1
    E2 --> F1
    A3 --> F2
    C3 --> F2

    E1 --> G1
    F1 --> G1

Loading

---

变更清单

阶段	change-id	主要 capability	依赖	蓝图出处	状态
M0	bootstrap-praxisd-skeleton	daemon-runtime, config	—	01/05	✅ 已实现并归档（2026-07-11）
M0	browsernode-contract	browsernode-contract	—	04 §4	✅ 已实现并归档（2026-07-11）
M0	cognition-port-contract	cognition-port, agent-adapter-contract	—	10	✅ 已实现并归档（2026-07-11）
M0	skill-package-schema	skill-package, skill-registry	—	07	✅ 已实现并归档（2026-07-11）
M1	browser-runtime-lifecycle	browser-lifecycle, session-pool, profile	browsernode-contract, bootstrap	04	✅ 已实现并归档（2026-07-11，27/27 任务）
M1	transport-driver-cdp-t2	driver-cdp, stealth-selfcheck	browsernode-contract	03/04	✅ 已实现并归档（2026-07-11，33/33 任务）
M1	explore-record-crystallize	explore, recorder, crystallizer	skill-package-schema, cognition-port, browsernode-contract	02 §2-3	✅ 已实现并归档（2026-07-11，34/35 任务）
M1	replay-interpreter-zero-token	replay-interpreter, shadow-replay	skill-package-schema, browser-runtime-lifecycle	02 §4	✅ 已实现并归档（2026-07-11，26/26 任务；internal/interpreter/ + shadow/ 门禁 + SC1/SC2 e2e）
M1	browser-transport-runtime-wiring	driver-runtime-assembly；modified：session-pool	transport-driver-cdp-t2, browser-runtime-lifecycle, replay-interpreter-zero-token, orchestration-governance	04	✅ 已实现并归档（2026-07-20，18/18 任务）——runtime.driver 显式启用时由 production supervisor 经 UDS 拉起 driver-cdp/真实 headful Chrome，探索与 0 Token 回放接入同一 daemon；process-level REST gate 在本地确定性页面完成探索→结晶→回放并验证 PID/端口回收。缺省仍是无驱动空池（I-6）；真实站点、T0/T1/T3、driver-side Secret Broker provisioning 与完整 checkpoint resume adapter 仍是后续 gate。
M2	multimodal-sensing	multimodal-sensing；modified：browsernode-contract（SnapshotRequest 通道选择 + NetworkSignal 细化）、cognition-port（Candidate.bbox）	browsernode-contract, cognition-port；驱动侧采集实施 gate：transport-driver-cdp-t2（已满足）	12	✅ 已实现并归档（2026-07-11，30/30 任务；internal/sensing/ + driver-cdp 通道选择/局部 OCR/DOM 展平/网络信号 + SC11 采集侧集成验证）
M2	locator-repository	locator-repository	skill-package-schema, skill-registry（复用 SQLite）	03 §6	✅ 已实现并归档（2026-07-11，24/24 任务；internal/locator/ 三方映射/重排/索引/计划构造 + I-4/I-6 静态与运行时双守护）
M2	self-heal-tiered	self-heal	replay-interpreter, locator-repository, cognition-port, multimodal-sensing	02 §5	✅ 已实现并归档（2026-07-11，31/31 任务；internal/selfheal/ 分级协调器 L1/L2/L3 + patch 事务应用 + 回写升版/状态处置 + 护栏计量 + SC7 三级自愈 e2e，I-2/I-4/I-5/I-6 守护齐备）
M3	behavior-synthesis	behavior-synthesis	browsernode-contract	03 §5	✅ 已实现并归档（2026-07-11，27/27 任务；internal/behavior/ 控制面派生/采样/dwell/自检 + 注入工厂，driver-cdp BiomechanicalSampler（Bezier/Fitts/lognormal/惯性）+ 可切换注入器（OS 级/CDP 诚实降级），0 modified capability，I-1/I-2/I-3/I-4/I-5 守护齐备）
M3	fingerprint-coherence	fingerprint-coherence；modified：browsernode-contract（LaunchSessionRequest 追加可选 FingerprintSpec）	browser-runtime-lifecycle	03 §4	✅ 已实现并归档（2026-07-11，29/29 任务；internal/fingerprint/ 关系型派生 DAG（OS 家族单源→UA/UA-CH/WebGL/canvas·audio 噪声/screen/字体/地理）、sub-seed 命名空间（D9）、地理校正/GeoMismatch、自洽判据；browsernode.proto 追加可选 FingerprintSpec（14 方法不变、I-5 无机密）；internal/transport 启动适配点 BuildLaunchRequest + M0 fake 契约用例；driver-cdp 消费派生指纹注入/自检（真实 Chrome e2e gate）；兑现 profile/stealth-selfcheck 既有委托、三切片零改动，I-1/I-3/I-5 守护齐备）
M3	stealth-ladder-tiers	stealth-ladder, tier-selection, site-memory	transport-driver-cdp-t2, behavior-synthesis, fingerprint-coherence	03 §1-3	✅ 已实现并归档（2026-07-12，控制面切片全绿；0 modified）——internal/stealth/ 档位规格（T0-T3 Capabilities/组合规则/诚实边界）+ 闸门探针确定性 gate 分类 + 最小够用档选择 + 被拦升档状态机（换会话，严格单调）+ 硬挑战 onEscalation 升级人工 + site-memory 升级记忆/定期重探针（复用 SITE_MEMORY 不改 schema）；Tier.Compatible 降档兼容细化（接口内，session-pool 暖复用降档复用）；T0/T1/T3 fake 驱动过同套契约测试（I-1 四档可替换）+ T3 %vault/GeoMismatch；选档接入 internal/transport 请求入口（AcquireForRequest，未接入回落显式档位）+ 组合规则接真实 fingerprint-coherence 派生；I-1/I-3/I-4/I-5/I-6 守护齐备。实施 gate 待解：T0/T1/T3 真实驱动子进程（5.3）、orchestration-governance（M4）的 Run NeedsHuman 审批回环/SITE_MEMORY 数据面单源（5.4/5.5）——升级事件先经 cognition human fallback 兜底，真实驱动/e2e 就绪后经 BrowserNode 契约注入、控制面零改动。
M4	orchestration-governance	orchestrator, run-model, policy, vault, observability；modified：config（注册 orchestrator/policy/observability 顶层段）	bootstrap, replay-interpreter	05	✅ 已实现并归档（2026-07-12，37/37 任务）——internal/runmodel/ Run 记录/状态机（Queued→Admitted|Rejected→Running→Healing|NeedsHuman→Succeeded|Failed）+ RUN/HEAL_EVENT/ESCALATION 持久化（接管 self-heal 让渡，复用 registry SQLite 自有迁移）+ trust_score 数据面 + 崩溃恢复检查点；internal/orchestrator/ Run Manager（准入→会话→0 Token 回放→终态，编排零 Cognition）+ 崩溃恢复续跑（SC5）+ Scheduler 四类触发 + Work Queue（业务键幂等/指数退避/身份分片）+ 审批回环（Approve/Reject + ESCALATION 处置回写）；internal/policy/ Site Policy 按域模型 + 准入门（速率/禁行区/高风险许可/预算/并发，结构化拒绝原因）+ session-pool 护栏权威（GuardrailFor）；internal/vault/ AES-256-GCM 加密静态存储（主密钥 PRAXIS_VAULT_KEY 进程外注入）+ Secret Broker 实现 interpreter.VaultResolver + Redactor 出口脱敏 + TOTP 托管（pquerna/otp，硬挑战一律升级人工）；internal/observability/ Run Store 留痕 + token_cost=0 守门告警（I-4 守门员）+ 自愈频发/升档告警 + 审批可见性 + trust_score 计算（经 registry.SetTrustScore）+ artifact 治理（URI 契约不变）；config 注册三治理段（宽松透传，observability 段强类型校验启动期快速失败）；daemon 装配层占位全部替换（共库装配、端口适配器桥接、orchestrator.Start 崩溃恢复）。I-4 静态/运行时双守护、I-5 脱敏否定用例、I-6 无认知闭环、SC5/SC8、契约闭环、存储可移植、回滚验证共 5 个 governance_* 不变量测试文件齐备。实施 gate 待解：真实回放适配（ReplayRunner 占位待传输驱动装配）、policy ConcurrencyView 接 session-pool 真实计数、持久化 DSN 配置化。
M4	batch-parameter-template	parameter-template, batch-execution	replay-interpreter, skill-package-schema, orchestration-governance	11	✅ 已实现并归档（2026-07-12，38/38 任务）——CSV/XLSX 模板、严格导入/漂移检测/错误报告、业务键与 dry-run、BATCH/BATCH_ROW 簿记、Work Queue/Run 接线、预算与恢复、统一汇聚及三格式导出、失败重试闭环；SC10 普通与自愈升版变体均通过契约路径，回放账目为 0。真实浏览器 ReplayRunner 仍是发布 gate。
M5	mcp-agent-interface	mcp-server, agent-tools；modified：cognition-port（骨架桩落地为完整工具面）、skill-registry（追加只读枚举）	explore-record-crystallize, replay-interpreter, batch	06	✅ 已实现并归档（2026-07-12，34/34 任务）——internal/agenttools/ 13 工具语义单源（高层 explore_task 零决策认知泵/run_skill 0 Token 承诺（cost>0 必附 heal_events 机器强制）/search_skills+get_skill+diff_skill 确定性检索、generate_template+run_batch 接真实 internal/batch；低层 open_session+close_session（intent_params 参数化通道）/observe+act+extract 原语暴露/approve 审批回环）+ 依赖注入接缝（RunManagerBridge/BatchBridge 真实接线）；internal/mcpserver/ MCP 协议面（官方 Go SDK streamable HTTP loopback/UDS、13 工具可发现、取消传播）+ 真实会话表（CallerSessionSource 使 attached 路由生效 + adapters.CallbackSessionSource 双接口、sampling 反向请求经同一 inbound 会话、client 无能力结构化降级）+ 本地 REST 程序化面（I-6 无 Agent 可用）+ 六语义码统一信封（双面一致）+ 入参机密守卫（复用 skillpkg I-5 特征单源）；cmd/praxisd 装配点占位替换（MCPServerStub 零修改退役为测试 fixture）；skill-registry 追加只读枚举 ListSkills。SC6 e2e 三旅程 + 批量姿势仅经 MCP CallTool 全绿（test/integration/mcp_sc6_test.go，fake BrowserNode 契约路径），验收报告 docs/acceptance/sc6-mcp-agent-interface.md；I-4/I-5/I-6 守护、调用边静态校验、会话双接口契约、回滚验证齐备。遗留 gate：真实 Chrome 全链（M1/M3 发布 gate 同源）；Cursor 真实 client 的 sampling 支持面按验收报告手动复跑；close_session 的 save_as 仅作结晶开关（产物名由轨迹 meta 推导，v1 边界）。
M5	agent-driver-adapters	agent-adapters	cognition-port-contract, self-heal-tiered	10 §5	✅ 已实现并归档（2026-07-12，30/30 任务；0 modified）——internal/cognition/adapters/ 共享 envelope codec（信封渲染/六 schema 严格解码/usage 归一化单源，R10）+ 四厂商适配器：mcp-client（官方 MCP Go SDK stdio、codex/codex-reply、run→threadId LRU 会话保持、approval/sandbox 受控下发）、openai-compatible（chat-completions 缺省 + anthropic-messages dialect 承载 Claude，凭据出站瞬间解析只写鉴权头）、cli/openclaw（sandbox: isolated + loopback/UDS + 零本地执行三重机器强制，R11）、mcp-server-inbound/Cursor 回调（attached 专属，CallbackSessionSource 消费接口 + fake 会话先行；validateDriverRef 追加"不得任 detached 默认驱动"校验）；注册表/工厂/cognition.Service 装配链（human 恒注册、零配置仅 human、Probe 失败降级告警，I-6）+ SecretResolver 端口（vault Broker 桥接 + dev-only env 实现，I-5）；contracttest 套件向后兼容扩展后四适配器 + fake/human 过同一准入套件；SC9 驱动侧自动化验收 test/integration/sc9_driver_swap_test.go（真实 stdio 子进程/httptest/fake 会话上换驱动只改配置 + attached 回调 + 无驱动底线 + 坏驱动降级）+ 手动验收清单 docs/acceptance/sc9-agent-drivers.md；I-4/I-5/I-6 守护与冻结面/导出面/依赖边界静态校验齐备（test/invariants/agentadapters_isolation_test.go）。实施 gate 待解：6.2 Cursor 真实会话接线（注入点 cmd/praxisd/cognition.go，待 mcp-agent-interface 会话表同时实现 CallerSessionSource+CallbackSessionSource）；真实外部 Agent（Codex CLI/Claude API/本地模型/openclaw）验收按手动清单复跑回填。
M5	web-management-api + close-console-api-contract-gaps	web-management-api；modified：skill-registry	orchestration-governance, batch-parameter-template, mcp-agent-interface 的 registry 枚举	05/06/11	✅ 已实现并归档（2026-07-12）——基础 51/51 任务之外，增量补齐 Schedule detail ETag、artifact descriptors 与 verified PNG inline、Run/Overview bounded summaries、System v1/Cognition、sid1 skill locator/canonical routes、原子持久 evidence（SQLite/Postgres）和 TTL/capacity validation-report store；Console 后端 Contract/Read/Mutation gate PASS，但 Console UI/浏览器 e2e 仍属独立 change。控制面证据不等同真实 Chrome；详见 docs/web-management-api.md。
M6	service-mode-multinode	service-mode；modified：browsernode-contract（承载放宽 mTLS+TCP）、config（注册 service 段）	orchestration-governance, mcp-agent-interface	05 §8	✅ 已实现并归档（2026-07-12，28/28 任务）——传输演进：internal/transport/ UDS/mTLS+TCP 双承载 dialer（同一 DialFunc 契约），browsernode-contract 契约测试套件在两种承载下零修改全绿（I-1 机器守护，14 方法/message 逐字不变）；mTLS 双向鉴权证书/私钥只经 %vault:...% 占位（internal/service/transport_mtls.go，明文只驻内存，statusz/日志否定用例守护 I-5）；inbound 远程承载复用 daemon.allow_remote + 叠加 mTLS（无 mTLS 拒绝非 loopback，启动期快速失败）；多节点调度：internal/service/ 节点注册表/心跳巡检/失联故障转移（resumable 重调度、不可幂等步安全收尾升级人工）+ 形状一致准入门（复用 CoherenceReport，headless/webdriver 痕迹机器拒绝、无容量放宽旁路，守 I-3/R7）；存储演进：internal/registry/pg.go+internal/locator/pg.go Postgres 后端（pgx，DDL 单源共享 schema 逐字一致）、internal/sensing/artifact_object.go 对象存储后端（minio-go，artifact:// URI 契约与遮罩不变），真实 Postgres 16 + minio 集成证据已跑通（PRAXIS_TEST_POSTGRES_DSN/PRAXIS_TEST_S3_* 门控可复跑）；config 注册 service 顶层段（缺省空 = 本地模式）+ cmd/praxisd 两形态装配（撤段整体回滚本地 UDS/SQLite/文件）。实施 gate 待解：节点侧运行时（真实驱动挂载 + 节点本地 session-pool 委派）——跨节点会话委派以结构化错误占位、协调器回落安全收尾；runmodel/policy/observability 等治理共库的 Postgres 后端随其存储接口渐进（本 change 落 registry/locator 参考实现）；真实多机 e2e（M6 里程碑「多节点服务化端到端」）待节点运行时就绪后另附证据。

证据口径：表中的“已实现并归档”表示 change 的主体实现、规格合并和仓库内门禁完成，不自动等价于生产 e2e。runtime.driver 显式启用时，praxisd 已使用真实 supervisor/dialer/replay runner；缺省或 enabled: false 时仍保留 NoTransportDialer/noDriverReplay 空池回滚路径。2026-07-20 的真实 Chrome 证据只覆盖本地确定性页面的 process-level 结构闭环，不覆盖真实站点或抗检测；stealth-ladder-tiers 仍保留 T0/T1/T3 真实驱动与数据面接线 gate。

---

里程碑验收（对齐蓝图成功标准）

里程碑	完成即验证	蓝图 SC
M0	三份契约冻结 + 骨架可起停；契约测试通过（守 I-1/I-6）	架构就绪
M1	fake BrowserNode + bufconn 契约级门禁已通过；另有 driver-cdp + 真实 Chrome 在本地确定性页面经 daemon REST 跑通 explore→crystallize→replay（0 Token），真实站点仍未验收	SC1/SC2 process-level 本地页
M2	fake BrowserNode 与 stub healer 的分级自愈场景已通过；真实复杂页面全链未验收	SC7/SC11 集成级
M3	选档、行为与指纹控制面已验证；T0/T1/T3 真实驱动仍是 gate	SC3/SC4 控制面
M4	生命周期/恢复、护栏/审批、参数模板→批量 0 Token→部分失败重试均已验证（真实治理组件 + fake ReplayRunner 契约路径）	SC5/SC8/SC10 契约级
M5	双半边已验收：SC9（契约级：四适配器换驱动只改配置闭环 + 无驱动底线）+ SC6（契约级：三旅程 A 探索结晶/B 三组输入 0 Token 复用/C 漂移自愈可见后恢复 0 Token + 批量姿势，全部仅经 MCP 工具面，test/integration/mcp_sc6_test.go）；真实外部 Agent 与真实 Chrome 按手动清单/发布 gate 复跑	SC6/SC9
M6	服务化装配（mTLS 承载 + 双后端存储 + 节点准入/故障转移）契约级与真实后端（Postgres/minio）验证；多机真实节点 e2e 待节点运行时 gate	服务化

---

建议实现顺序

1. M0 四个契约并行提案与实现 → 冻结契约。✅ 已完成并归档（2026-07-11）。
2. M1 垂直切片：基础四个 change 与 browser-transport-runtime-wiring 已归档；除 fake BrowserNode + bufconn 门禁外，test/e2e/browser_transport_fullchain_test.go 已在本地确定性页面用 driver-cdp + 真实 Chrome 验证 daemon REST 探索→结晶→回放与 token_cost=0。这不等价真实站点抗检测验收。
3. M2 控制面与集成场景完成：multimodal-sensing、locator-repository、self-heal-tiered 已归档。test/integration/selfheal_sc7_test.go 使用 fake BrowserNode，L2/L3 使用 stub healer；因此它证明分级编排与回写语义，不代表真实站点端到端验收。
4. M5 已完成：agent-driver-adapters 与 mcp-agent-interface 均已归档；Cursor 双角色接线落地（inbound 会话表同时实现 cognition.CallerSessionSource 与 adapters.CallbackSessionSource，attached 路由与 sampling 反向请求经同一条 inbound 会话）。M6 service-mode-multinode 已归档（可选服务化按本地优先原则落地，撤 service 段即整体回滚）。已归档 change 的细节见上表与 openspec/changes/archive/。
5. 各 change 实现严格按其 tasks.md（含 Parallelization Plan 与 Architecture Verification），完成后 openspec archive <change>。

需要为某个 change 补充/修订提案时，指名该 change-id 即可按同样方式分派 Fable 5 sub-agent 生成或迭代。