maodingAgent

一个本地优先、可插拔的 AI 编程 Agent 会话监控器，目标是复刻 AgentDesk 的核心使用体验，但不直接复制腾讯内部实现、品牌、内部服务或私有协议。

当前阶段

阶段 0–5 ✅（共 135 项测试全部通过）；M0 收尾 ✅：App 层补齐设置窗口、首次引导、诊断导出与 --self-check 自检（6 项全 PASS），提供 M0 验证清单 供 GUI 环境验收；下一步：阶段 6 远程 Relay（可选）或阶段 7 发布准备

已完成：

• R1 静态结构盘点；
• R2 模型与事件恢复；
• R3 Bridge 结构恢复和独立协议边界；
• R4 Hook 安装、Manifest 与健康检查规格；
• R5 隔离 Hook 输入捕获和 fail-open 边界验证；
• 阶段 1 产物：
  • 协议 JSON Schema（event / command / response / hello / envelope）；
  • EventEnvelope / Message / AgentEvent 类型化编解码；
  • Unix Socket Bridge（BridgeServer + EventStreamClient + CommandClient）；
  • Hello 握手、request ID、response timeout 和 fail-open；
  • 模拟事件 CLI（maoding-simulator：generate / send / demo 子命令）；
  • SessionReducer 状态机（去重、乱序、stale、审批/回答归约）；
  • SessionStore（Actor + 原子持久化与恢复）；
  • JSONL fixture（8 类：session_start / user_prompt / tool_permission / answer_needed / stop / session_end / malformed / unknown_version / unknown_event）；
  • 协议、reducer、Bridge 集成和超时 fail-open 测试（37 项全部通过）；
  • 阶段 2 产物：
    • Overlay 核心（可测试）：面板触发状态机（hover 防抖 / click 不误触 / 拖动不误判点击）、浮球位置（归一化坐标、边缘吸附、贴边折叠、顶部避让、多显示器迁移）、会话分组排序；
    • UI 偏好持久化（ui-state.json 原子写入）与皮肤 Manifest 解析/回退（reduceMotion 时回退 minimal-dot）；
    • macOS App 骨架（maoding-app）：菜单栏入口、桌面浮球窗口（拖动/吸附/折叠）、SwiftUI 会话面板、OverlayCoordinator 落地状态机与计时器；
    • 阶段 2 测试（34 项，累计 71 项全部通过）；
  • 阶段 3 产物：
    • 新手引导：OnboardingStateMachine（步骤/可跳过/可恢复/可重开/needsRepair）+ onboarding.json 持久化 + 模拟会话演示；
    • Adapter 协议：AgentAdapter / InstallPlan / ManagedHookManifest / HookHealthReport / AgentInstallStatus；
    • HookInstaller：备份、原子安装、幂等、只删精确匹配受管命令的卸载、无效配置不覆盖；
    • Codex Adapter（第一个真实 Adapter）：检测、配置读取、安装计划、model 必需字段诊断（MVP-016）、deny stdout 编码、健康检查；
    • Claude Adapter 骨架：独立事件集、输入规范化、Claude directive stdout；
    • HookOutputEncoder：Agent-specific stdout（未知 directive fail-open）；
    • 阶段 3 测试（29 项，累计 100 项全部通过）；
  • 阶段 4 产物：
    • 终端目标匹配：TerminalTarget / RunningTerminal / TerminalMatcher（TTY>SessionID>PaneID>工作目录>标题 加权匹配、子目录、前置窗口破平局、歧义检测）；
    • 跳转错误分类：TerminalJumpError（终端不存在/目标不可用/权限不足/歧义/执行失败）与可恢复性、用户提示；
    • 脱敏日志 SanitizedLogger：Token/私钥/邮箱/Bearer/敏感键值/长串/自定义 secrets/代码块截断（MVP-015）；
    • 诊断导出 DiagnosticReport：脱敏条目 + 健康快照，JSON 导出；
    • App 层 TerminalJumpCoordinator：辅助功能权限检查、AppleScript 激活、匹配落地（骨架）；
    • 阶段 4 测试（23 项，累计 123 项全部通过）；
  • 阶段 5 产物：
    • AdapterRegistry：统一注册/发现（codex + claude）与已安装 Agent 检测；
    • SessionMerger：会话合并（同 agent+cwd 归并 canonical、成员最近信息提升、合并组追踪）；
    • CompensationScanner：补偿扫描（进程快照 vs 已记录会话，生成补录事件）；
    • Codex 深度集成边界：App Server/rollout 必须以单独研究报告为基础（核心代码只保留已证实部分）；
    • 阶段 5 测试（12 项，累计 135 项全部通过）；
  • M0 收尾产物：
    • App 设置窗口/设置视图（入口可见性、触发模式、浮球开关、皮肤、低动态、引导重开、诊断导出）；
    • 首次启动引导窗口（8 步导航 + 可跳过，接入 onboarding.json）；
    • OverlayCoordinator 扩展：入口可见性、引导状态驱动、脱敏诊断导出（DiagnosticReport + SanitizedLogger）；
    • 状态栏菜单补全（设置…/重新打开引导/导出诊断…）；
    • maoding-app --self-check 自检（协议/状态机/皮肤/脱敏/屏幕 Profile/权限状态，6 项全 PASS）；
    • M0 验证清单（GUI 环境人工验收步骤）。

明确未恢复、且不阻塞独立实现：

• AgentDesk 私有 BridgeResponse 的完整 Swift Codable case；
• native Hook 在合法私有 response 下的完整 stdout roundtrip。

代码、测试和构建产物进入对应目录前，仍需遵循下方协议、隐私和回滚约束。

目录约定

maodingAgent/
├── README.md                 # 项目入口和当前状态
├── Package.swift             # Swift Package 清单
├── docs/                     # 面向开发和协作的正式文档
├── specs/                    # 可执行的功能规格和验收标准
├── research/                 # 对 AgentDesk/Open Island/Agent 行为的研究记录
├── protocols/                # Hook、Socket、事件模型等协议定义与 JSON Schema
├── decisions/                # ADR 技术决策记录
├── notes/                    # 临时但需要保留的开发笔记
├── Sources/
│   ├── MaodingCore/          # 核心库：协议、Bridge、Session、模拟事件
│   └── maoding-simulator/    # 模拟事件 CLI（generate / send / demo）
├── Tests/
│   └── MaodingCoreTests/     # XCTest / Swift Testing 测试（含 JSONL Fixture）
├── Resources/                # 后续资源文件
└── dist/                     # 后续本地预览/打包产物

第一批文档

• 开发文档总览
• 产品需求与范围
• 技术架构设计
• 分阶段开发计划
• 验证与验收方案
• 研究与合规边界
• 逆向分析计划
• 逆向发现：模型与 Bridge
• R4 安装与健康检查规格
• R5 Hook/Bridge 隔离测试报告
• R5 隔离捕获工具
• R5 Codex 脱敏 fixture
• 用户体验优化规格
• 后续动作实施说明
• Open Island 公开参考记录
• 事件协议草案
• 协议 JSON Schema（event / command / response / hello / envelope）
• 模拟器 CLI（swift run maoding-simulator --help）
• M0 验证清单（GUI 环境人工验收）
• ADR-0001 独立兼容实现

基本原则

1. 本地优先：默认只在本机处理会话事件，不默认上传提示词、代码、Token 或日志。
2. 兼容而非复制：复现公开可观察的产品能力，不复制 AgentDesk 的私有代码、品牌或内部服务。
3. 适配器隔离：每个 Agent 的配置、事件和交互差异收敛在独立 Adapter 中。
4. 可诊断：Hook 安装、Socket、会话状态和终端跳转都必须有可验证的健康检查。
5. 可回滚：任何修改 Agent 配置的操作都要支持备份、预览和卸载。
6. 先 MVP 后扩展：先实现模拟事件、本地 Socket、会话浮层和一个 Agent 适配器，再做 Codex 深度集成、远程连接和可选云服务。
7. 证据分层：已证实行为可进入 fixture；强推断必须保留替代方案；待验证内容不得写成兼容承诺。
8. Hook fail-open：Bridge 或 response 不可用时不得自动批准，不得永久阻塞 Agent。
9. macOS Demo 优先：先完成顶部状态栏、浮球、触发设置、新手引导和一个真实 Adapter，再做多端同步。
10. 入口可替换：顶部状态栏和浮球共享状态，不把用户绑定到单一入口。