BugX

Version 0.9.11 BugX 是一个让 AI 挖掘、验证和报告真实 Bug 的审计 Agent。它把测试策略、并发执行、 证据校验、生命周期、错题集和最终报告组织成一套可重复的协议。

BugX 是给人看的产品名称；bugx 是安装、配置和诊断命令。真正的测试动作由 OpenCode、Codex、Cline、Claude Code、ZCode、Pi、ChatGPT 或 DeepSeek Harness 等 AI 宿主执行，CLI 本身不会启动模型或执行审计。

产品优先级：第一是高效、准确、快速地挖掘真实 Bug，以及一切能提升挖掘收益的工具、模型 交互、复盘和知识复用；第二是安全与可信；第三才是隐私最小化。当前云端是用户本人账号下的 私有项目多设备同步，不包含公共项目发布或公共分享。Alpha 模型原文以及与 Finding/Incident 相关的非敏感源码片段可作为不可信证据参与 项目知识复盘，并在私有 project sync 开启且安全扫描通过后异步同步；未经验证的原文不能 直接成为 active 规则，global 只接收验证并去项目化的结构化经验（允许携带可复用的最小源码示例）。

架构

源码仓库按职责分层：core/ 是公共协议源码，integrations/ 是各宿主的安装适配资源， src/bugx_cli/ 是只负责安装、配置和诊断的 CLI，evals/ 是 Agent 行为评测集。 这些源码目录不会被误认为用户项目的运行态目录。

使用流程很简单：用户通过 CLI 安装到 AI 宿主，AI 宿主加载 BugX 协议。测试任务由宿主 自身的执行能力完成，可以串行运行，也可以使用宿主提供的并发、子 Agent 或其他编排能力； BugX 负责统一策略、证据、生命周期和报告门禁。

能干什么？

• 0.8.2 全面更新项目设计文档并增加全景架构图与流程图：新增现代分层与模块解耦全景架构图、生命周期端到端核心状态机流程图与 Cloud Sync 增量推拉及删除 GC 闭环时序图，同步升级系统设计规范。
• 0.8.1 完成全量架构深度解耦（DOC-072）：对全代码库排名前四的大单体文件（plugin.py、lesson_ledger.py、round_orchestrator.py、cloud_onboard.py）完成领域子包拆解与 Facade 架构重构，单体代码行数平均削减 60%+，100% 保持向后兼容。
• 0.8.0 完成 Cloud Sync 删除闭环（DOC-071）与深度架构解耦（DOC-070）：拆解 MCP Server 命令模式（core/mcp_handlers/）、CLI 基础设施（src/bugx_cli/infra/）、Supervisor 领域服务（core/supervisor/）与 CLI 领域测试套件，单体代码净减逾 6,500 行，100% 保持向后兼容。
• 0.7.4 闭环测试用例质量复盘与修复（DOC-053）：收紧跨平台子进程超时（124 / -15）确定性差分裁决断言，强化 Supervisor 终态落盘与重载断言，提高 CLI 诊断与更新链路验证鲁棒性。
• 0.7.3 推出漏洞挖掘方案全息保证框架与测试用例能力动态验证框架：支持主体全息勘测、威胁模型精准对齐与四维（准确/完整/有效/全面）100 分量化审计（bugx mining-audit）；建立基于 AST 语义微观变异（ROR/AOR/LCR/BCR/EOR/SVR）与沙箱隔离的测试能力动态验证器（bugx test-verify），量化击杀率与评级，杜绝假断言与覆盖盲区。
• 按代码结构、业务链路和风险优先级寻找 Bug。
• 支持白盒审计、黑盒测试、宿主原生串行/并发编排和多轮生命周期。
• 要求复现、独立 Oracle、负对照、根因和真实证据，减少误报。
• Supervisor 可在完成态强制执行 Finding 确认门禁，并输出可解释的确认质量分数。
• 使用项目级和用户全局 SQLite 错题集，复用已验证的根因模式。
• 记录「工具 × 问题类别」归因反馈，按实测命中派生工具经验等级 （unproven/candidate/active）与场景→工具矩阵，用数据修正工具选型。
• 热点再排序：每轮 findings 驱动单元优先级、风险计划与命中列实测校正， 兄弟模块热点自动扩散；incident 深案例按错误签名自动提示。
• 内置差分对照执行器与行为引导模糊进化，最高级 differential Oracle 必须引用真实差分报告；观察/负对照支持工件哈希绑定，报告期重算防伪造。
• 错题模式可执行化：探针扫描器直接输出嫌疑文件:行 线索；种子缺陷靶场 用开/关 A/B 实证经验系统增益；修复看护巡查修后代码是否仍在。
• 分层指南（L0 快速卡 ~1k token 常驻）+ MCP 知识工具面 + 边际收益顾问； 目标内容注入防御红线贯穿全协议。
• 计量校准：provider 真实 usage 提取（unmeasured 显式标记不冒充 0）； 非 Python 语言 tree-sitter 调用图；已修 bug 一键生成可执行回归重放包； 账本增长治理与 incident 归档。
• 修复转绿立即沉淀 incident 案例（修前/修后、错误签名、决策链），下次同类 问题按签名命中并用深案例做 few-shot。
• 黑盒/半黑盒任务支持 audit_campaign 功能清单：以 DAG 前置依赖控制派发， 以 runtime:/env:BUGX_* 安全引用复用测试账号、会话和 fixture；清单不保存秘密值， 真实并发与 Worker lease 仍由 Supervisor 负责。
• 0.6.47 将云端同步与结论共享的正式打包默认端点固化为 https://bugx.dev；dev alpha 包由流水线注入 UAT，仍可用全局配置或 BUGX_CLOUD_API_BASE / BUGX_SHARE_API_BASE 覆盖。
• 输出 Markdown、JSON、SARIF 等测试报告，并支持修复后的回归验证。
• 可安装到 OpenCode、Codex、Cline、Claude Code、ZCode、Pi、ChatGPT 桌面应用和 DeepSeek Harness。
• 0.7.0 为统一交互增加 zh-CN/en-US 首版国际化：部署与启动会按 BUGX_LOCALE、用户偏好 或系统语言自动选择；原生请求、headless 转发和 TTY 菜单共享同一消息目录，未知语言回退英文， 稳定的 value/action 不随显示语言变化。
• 0.6.2 支持本人账号下私有 global/project 多设备 Cloud Sync V2-only；默认同步完整详情， 可按选定 scope 使用 --detail-mode summary 降级为摘要。公共发布、公开分享、跨账号订阅和 community catalog 不属于本版本。
• 0.6.3 增加低交互、可恢复的项目/全局重置：项目级默认只重置运行产物并保留项目错题集， 全局级默认重置全局错题集；凭证、设备身份、MCP 缓存和历史备份可在同一次确认中选择处理， 全局引擎永不被 reset 删除。
• 0.6.4 增加 CLI、项目和全局引擎版本一致性门禁；每次 Agent 启动前自动核验，发现版本漂移 会阻止审计并提示使用 bugx install --force 修复。
• 0.6.48 修复云端登录设备登记结果漏检；统一启动门禁的机器可读选项，宿主按 value/action 执行并校验，不再依赖解析中文选项文本。
• 0.6.5 修复 Python 3.9 日志兼容性、pre 失败日志盲区、项目核心静态文件漂移、账本状态误报和大型覆盖清单 status 超时。
• 0.6.6 固化 Agent 启动版本横幅，并让旧项目在 pre 启动时强制完成云同步/登录 onboarding 决策。
• 0.6.7 将效率工具降级纳入启动门禁：无终端或未完成用户选择时停止，不再静默进入审计； 明确选择回退后才允许继续。
• 0.6.8 明确 OpenCode MCP 配置变更必须重启宿主会话；配置已启用但当前工具未挂载时标记 MCP_SESSION_STALE，继续使用既有 bugx-supervisor 控制面，不新增重复恢复入口。
• 0.6.9 固化启动交互顺序为云端登录/同步 → 轮询策略 → 修复模式；非交互环境不再静默 跳过云同步决策。
• 0.6.10 增加审查方式启动交互：手动审查、MCP 自动审查或下次再说；选择下次再说时本轮 默认手动审查、下次启动重新询问，MCP 自动模式缺少控制面工具时按会话过期门禁停止。
• 0.6.12 明确云同步启动菜单：未登录为立即登录/本地模式/下次再说，已登录为云端同步/本地模式/ 下次再说；本地模式持久化为项目级 local 状态，显式同步可重新开启。
• 0.6.13 收紧 MCP 缺失启动门禁：发现 MCP 未安装/未配置后立即交互询问安装配置、本轮回退或 下次再说；选择下次再说会停止本轮，空回车不会静默跳过。
• 0.6.14 增加 MCP 调用失败交互门禁：失败后立即询问重试、切换手动/回退或下次再说，禁止 自动吞错、无限重试或直接进入下一审计单元。
• 0.6.15 统一交互菜单：登录态有效、过期、未登录、启动策略、分享和重置确认均使用编号菜单； 登录态过期不再单独弹出 yes/no 确认。
• 0.6.17 将审查方式、轮询策略和修复模式升级为真实 TTY 的方向键单选控件；宿主不支持时安全 回退为编号菜单，并补全每个选项的执行语义。
• 0.6.18 增加全局云端 Base URL 配置：支持 bugx cloud config --base-url、查看和清除；环境变量 BUGX_CLOUD_API_BASE 可临时覆盖，凭证与地址分离保存。
• 0.6.21 增加启动环境探测：识别宿主与 TUI/ACP/headless/TTY 交互能力；非 TTY 启动只返回一个 BUGX_INTERACTION_REQUEST 结构化单选门禁，并显式校验 OpenCode 原生 question 权限；旧 dismissed 云同步状态自动迁移为 pending。
• 0.6.22 增加受控覆盖清单引导和 Supervisor MCP 缺失门禁；已启用云同步的项目每次启动都会 执行同步，版本契约失败只允许一次受控更新并要求重启宿主；同时固化 Session → Round → Life、 RoundExecutionPlan、Life/全局知识复盘和最终 Round 结论共享流程。
• 0.6.23 修复 BUGX_FLOW_DESIGN_DRAFT × DOC-009~012 对齐差异：统一 StartupContext 字段与唯一权威、校正项目理解与 Life 结算时序、补全自动终止三类条件、收敛孤儿术语与编号。
• 0.6.24 修复并发公式双定义与知识仲裁旧措辞，补齐共享重放入口、超时/取消语义与 manual 中断边界，标注分类学占位并明确共享优先级。
• 0.6.25 落地 Session / Round / Life 运行时：Session 状态外置、Supervisor 按 Session/Round/Life 绑定、云端同步延后至 Session 提交后。
• 0.6.26 增加意图—逻辑链—Oracle—证据最小契约：支持分析包校验和任务绑定，最终确认仍复用既有 confirmation gate。
• 0.6.50 修复启动门禁顺序、工具/知识 tombstone 删除闭环、validated 快照重放、manifest 绑定和 cursor 单调性，并补齐 67 模块全量回归验证。
• 0.6.52 落地黑盒功能清单与安全资源引用：schema 2、DAG 依赖阻断、过期/撤销/外部环境资产校验、 resource_context 和可审计复用统计；补齐不落明文秘密的 CLI、Session 绑定与回归测试。
• 0.6.53 增加黑盒状态迁移候选、显式反馈向量 Fuzz、收益预算建议与指南切片；新增只读优先的 self_audit 自举入口，支持 CLI/MCP 异常最小化、回归快照和候选知识产物，不自动改源码或写账本。
• 0.6.64 新增宿主无关的统一交互组件：统一 native question、TTY 单选、文本菜单和 ACP/headless 请求；启动、云端、工具、重置等问题串行呈现，非 TTY 使用 BUGX_INTERACTION_REQUEST，敏感输入不回显且不记录。
• 0.6.90 落地 Phase 3 语法感知/覆盖导向 Fuzzer（JSON 语法树保持突变与 Coverage Gap 引导注入）、Phase 4.1 增量 AST 变更波及剪枝引擎（基于 git diff 与 AST 的 2-hop 扇入扇出分析）与 Phase 4.2 确定性沙盒隔离双跑差分验证器（双沙盒独立运行、非确定性噪音归一化清洗与三态差分裁决）。
• 0.6.93 全量架构解耦与生命周期阶段化（launch_phases/）、统一探针注册中心（probe_registry.py）、物理级三层提示词渐进装载（L0 路由/L1 阶段 Harness/L2 规则）、Session Profile 快速启动通道（--profile）、并发时序死锁专项探针（concurrency_fuzzer.py）、业务状态机推演器（stateful_fuzzer.py）与自包含零依赖单文件复现脚本合成器（minimize_repro.py --synthesize-standalone）。
• 0.6.94 全系统代码冗余消除、核心超长文件深度解耦与经验账本包架构落地（DOC-036）：统一防越界路径核验（bugx_paths.assert_no_symlink_components，兼容 macOS 系统别名）、多探针移动设备解析统一（platform_adapter）、Supervisor 状态与契约模型解耦（supervisor_models.py，-878行）、Round 调度器生命周期报告与经验上下文解耦（lesson_context.py、lifecycle_reporter.py，-795行）、经验账本包架构落地（core/ledger/，-766行，双身份单例无死锁保障）。
• 0.6.95 落地开发文档与生命周期协同 Skill 模块（dev-doc，DOC-037）：实现“开发前方案生成与 5 问逐条设计审计门禁（dev-doc plan）➔ 方案就绪核验（dev-doc check）➔ 开发后自动对齐文档、Release Notes、版本号与完整性清单（dev-doc close）”，保障需求、方案、代码与测试四位一体闭环。
• 0.6.105 下一代智能 Prompt Harness 架构落地（DOC-043）：实现 AST 静态语义推断与 L2 专项规则智能切片（analyze_source_rules / detect_unit_rule_slice）、状态机驱动的主动注入任务修饰器（decorate_stage_task）、长堆栈与 Fuzz 异常结构化证据蒸馏器（distill_evidence）以及异构模型分级调度建议契约（get_stage_metadata）。
• 0.7.2 落地测试用例四维质量保证引擎与全息脚手架生成器（DOC-051）：实现自动化全息测试用例与脚手架生成引擎（test_generator.py，覆盖 AAA 结构与边界/负对照/故障/并发/状态机矩阵）、四维质量量化审计评估器（test_quality_auditor.py，准确/完整/有效/全面 100 分制与门禁）、修复最小化复现断言模式硬编码缺陷、消除 module_coverage 虚假覆盖漏洞并提供 bugx test-generate 与 test-audit CLI 统一入口。

怎么用？

1. 安装 BugX CLI

BugX 要求 Python >=3.11。安装或直接运行核心脚本前，不要假定系统的 python3 满足要求；优先使用已经安装的 bugx 命令。需要从源码安装时，先用下面的 一次性片段发现并校验受支持的解释器；找不到时应停止，不要回退到 Python 3.9：

if [ -n "${BUGX_PYTHON:-}" ]; then
  if ! "$BUGX_PYTHON" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)' >/dev/null 2>&1; then
    echo "BUGX_PYTHON 必须指向 Python >=3.11" >&2
    exit 2
  fi
else
  for candidate in python3.14 python3.13 python3.12 python3.11 python3 python; do
    if command -v "$candidate" >/dev/null 2>&1 &&
       "$candidate" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)' >/dev/null 2>&1; then
      BUGX_PYTHON="$(command -v "$candidate")"
      break
    fi
  done
fi
if [ -z "${BUGX_PYTHON:-}" ]; then
  echo "未找到 Python >=3.11；请安装受支持的 Python 或设置 BUGX_PYTHON" >&2
  exit 2
fi
export BUGX_PYTHON
"$BUGX_PYTHON" --version

"$BUGX_PYTHON" -m pip install .

2. 安装到 AI 宿主

在目标项目目录执行：

bugx agent discover --root . --json
bugx install --root .

CLI 会发现当前环境中的 AI 宿主并询问安装目标。也可以明确指定：

bugx install --root . \
  --agent opencode --agent dsh --agent codex --agent cline --agent claude --agent zcode --agent pi --non-interactive

ChatGPT 桌面应用使用：

bugx install --root . --agent chatgpt

安装完成后，在对应 AI 宿主中选择或调用 BugX，并让它开始审计当前项目：

• OpenCode：任意项目目录启动后输入 @bugx（并发 Worker 用 @bugx-worker）或在 Agents 列表选择 BugX
• Claude Code：/agents 选择 bugx 或 AskUserQuestion 触发 BugX
• ZCode：在目标项目中新开会话，于 Subagents/Agent 列表选择 bugx（用户级入口，~/.zcode/agents/bugx.md）；并发 Round 由主 Agent 按 subagent_type=bugx-worker 派发同名子智能体。bugx 与 bugx-worker 以用户级注册：安装时写入 ~/.zcode/agents/（ZCode 桌面端 user 作用域扫描根，Settings → Subagents 全项目可见，无需逐项目安装），0.7.22 起项目级 .zcode/agents/ 不再写任何入口——宿主按名字合并作用域时项目级同名副本胜出，双写会把用户级条目遮蔽出"用户级"列表，旧版本遗留副本由安装期清扫按模板比对移除。安装时还会幂等写入用户级 ~/.zcode/cli/config.json 的 mcp.servers，登记 bugx-supervisor 与 worker 双通道；跨项目分发也可用本地插件 plugins/bugx（agent 命名 bugx:bugx 与 bugx:bugx-worker），脚本化登记：bugx plugin zcode --root <项目>（写入 ZCode 的 plugins.dirs，--remove 移除），或手动在 Settings → Plugin Management 添加
• Codex：Skills 列表选择 bugx
• Cline：bugx install --agent cline 会写入项目 Skill .cline/skills/bugx/SKILL.md，并按 Cline CLI 的真实格式幂等写入 ~/.cline/data/settings/cline_mcp_settings.json 的 mcpServers（可用 CLINE_MCP_SETTINGS_PATH 覆盖）；随后在 Cline 的 Skills 中启用 bugx
• Pi：pi --approve --skill .pi/skills/bugx/SKILL.md 后在 Pi 会话中调用 BugX
• ChatGPT：bugx install --agent chatgpt 后在桌面应用 Plugins/Skills 中启用 BugX
• DeepSeek Harness：bugx install --agent dsh 写入 .dsh/ patch 与 Skill；dsh 会话内用原生单选控件逐组完成启动 Gate，非 TTY 时承接 BUGX_INTERACTION_REQUEST <json>

3. 检查安装状态

bugx doctor --root . --installation-only

云端和知识库的诊断/维护入口如下；状态查询是只读的，不会登录、联网或创建同步数据库：

bugx cloud login
bugx cloud auth login
bugx cloud auth status --json
bugx cloud auth status --verify --json   # 只读向云端验证缓存凭据
bugx cloud auth logout
bugx cloud status --scope all --json
bugx cloud sync               # 默认同步 global + project；也可使用 project 或 global
bugx cloud export --scope project --output .bugx/project-sync.json  # 本地 JSON bundle，不联网
bugx cloud upload --input .bugx/project-sync.json --mode local_authoritative  # 本地同 ID 优先恢复
bugx cloud onboard on         # 开启并立即同步 global + project
bugx lesson validate --deep --json
bugx lesson rebuild-fts
bugx lesson incident-archive --older-than-days 90
bugx lesson archive-events --output .bugx/archives/events

cloud status 查看本地 committed cursor、最近错误、outbox/inbox 和冲突；它不会联网，登录态 仅代表本地凭据状态，需使用 bugx cloud auth status --verify 才能确认服务端是否接受当前凭据； 远端设备接口仍使用 bugx cloud devices。cloud auth logout 只清理云端凭证，不删除设备身份或 本地同步状态。

cloud export/cloud upload 使用同一份 Cloud Sync V2 JSON envelope；上传支持 merge 与 local_authoritative。后者只覆盖 bundle 中出现的同 ID 记录，保留云端独有记录，并在成功后 建立新的本地同步基线。服务端接收的是 JSON request body：会保留原始 import JSON，并从中 提取 typed records；不是 multipart 文件上传。

同步 pull 以 tool_name/category 作为工具经验主键，工具 tombstone 会在 cursor 提交前落为 deleted 记录；Pattern tombstone 会在同一账本事务内撤销仍可运行的子 Incident。cursor 是 opaque 值，旧版本且 cursor/snapshot 不同的响应会被拒绝。隔离文件 .bugx/knowledge/cloud-synced.json 必须带有与四类原始 records 匹配的 manifest_hash， 伪造或缺失 hash 不会被显式导入。

逻辑分析包可在 Worker 提交前校验或绑定到任务：

bugx logic-analysis validate --root . --input <logic-analysis-bundle.json>
bugx logic-analysis bind --root . --input <logic-analysis-bundle.json> --task <task.json> --output <bound-task.json>
bugx logic-analysis bind-finding --root . --input <logic-analysis-bundle.json> --finding <finding.json> --output <bound-finding.json>

Agent 每次启动审计前都会核验 CLI、项目核心引用和全局 ~/.bugx/core 是否为同一版本。 .bugx/manifest.json 仅保存项目身份和历史安装信息，不作为运行引擎版本来源。若提示核心版本漂移，执行：

bugx install --root . --force --non-interactive
bugx doctor --root . --installation-only

启动时会先输出 Agent 版本和 CLI/项目/全局引擎版本契约。旧项目若尚未决定云同步， launch_bugx pre 会按认证状态要求明确选择立即登录/云端同步、本地模式或下次再说；选择登录后会立即拉起 device-code 授权页，未完成授权不会进入下一启动 gate。显式 bugx cloud sync 遇到服务端 401 也会自动重新登录； status --json 的 stdout 仍保持纯 JSON。

OpenCode 安装后会自动登记本地 bugx-supervisor MCP。它只协调 .bugx 中的租约、心跳、 checkpoint 和并发门禁，不执行任意 Worker 命令；其他宿主可使用：

bugx mcp serve --root . --role host

bugx install --agent cline|zcode 同样会写入各自的原生 MCP 配置：Cline 使用 ~/.cline/data/settings/cline_mcp_settings.json 的 mcpServers，ZCode 使用 ~/.zcode/cli/config.json 的 mcp.servers。安装只更新 BugX 自己的两个保留名称，保留其他 MCP；bugx doctor 必须同时验证 host/worker 两个名称及其命令，不会因 Skill/Agent 入口存在而误报 MCP 就绪。

MCP 配置通常在宿主会话启动时加载，但启动器会先对当前项目执行一次有界、只读的 host/worker 主动探活；两个硬通道都命中时无需重启即可继续，首次真实 MCP 调用仍是最终权威。只有配置已启用、 主动探活未命中且当前工具列表没有 bugx_supervisor_* 时才标记 MCP_SESSION_STALE，再由最终 启动动作单选决定重启、手动开始或暂不启动；不能让 Agent 退回调用被权限拒绝的 pre/resume。

4. 卸载

不带参数的 bugx uninstall 是两级意图引导，用大白话说清后果：

1. 仅卸载当前项目——删除本项目下的 .bugx/ 与各 AI 工具的 BugX 入口，本项目 回到未接入状态；其他项目与全局数据不受影响（删除前自动备份到项目外）。
2. 全局卸载（所有 AI 工具都不可用）——移除 BugX 本体（全局引擎、全局数据与 所有 AI 工具的登记）；当前项目仍接入时会先执行 1 再移除全局层。

终端里经原生单选/菜单选择；脚本与 Agent 场景（非 TTY）输出两级选项与建议命令 （--json 可解析）。精细控制仍可用显式 flag（--agent/--all/--purge-data/--self）。

按宿主卸载只删除 BugX 自己安装且未被用户修改的入口，测试报告、证据、错题集和 OpenCode 配置默认保留：

bugx uninstall --root . --agent pi

彻底清理项目级 BugX 数据时必须显式确认；命令会先把 .bugx/ 备份到项目外的 ~/.bugx/backups/uninstall/（可用 BUGX_UNINSTALL_BACKUP_ROOT 指定备份根目录）， 并在删除前补充归档卸载过程中新增的宿主配置备份和最终诊断日志： project-uninstall-backups/、project-final-logs/，并写入 uninstall-receipt.json 记录删除与保留项。 外部归档会保留，便于恢复， 不会被项目级卸载自动删除：

bugx uninstall --root . --all --purge-data --yes

全局错题集会影响其他项目，只有额外指定 --purge-global-data 才会清理。

项目级卸载只管单个项目。项目级卸载也支持 --dry-run 预览；预览不会写日志、宿主登记、 项目文件或备份，即使同时提供 --yes 也不会执行卸载：

bugx uninstall --root . --all --purge-data --dry-run --json

移除本机所有 BugX 自有工件（全局引擎 ~/.bugx/、 OpenCode 全局入口链接、ZCode plugins.dirs 登记、Pi/DeepSeek 全局注册、 codex 插件登记）使用全局自卸载——先用 --dry-run 审计全机残留，确认后执行； ~/.bugx/ 会先整体备份到 HOME 下的 .bugx-self-uninstall-backup-<时间戳>/：

bugx uninstall --self --dry-run
bugx uninstall --self --yes

注意：--self 不卸载 pip 包本体，结束后按提示执行 pip uninstall bugx-agent； --self 不会在当前工作目录创建项目级日志或 .bugx/； 且要求所有接入 BugX 的项目先完成各自的项目级卸载，否则其它项目的 .bugx/core 软链接会悬空。

5. 重置运行态和错题集

项目级重置只清理轮询、生命周期、状态、日志、证据、索引、项目内备份，以及旧版本可能遗留在 .bugx/core/ 中的运行态文件/链接，并重新生成初始运行结构；静态核心链接不受影响。 项目错题集默认保留。如需同时重置项目错题集，只增加一个范围参数：

bugx reset --root . --reset-knowledge

全局级重置默认清空并重建全局错题集/经验集；它不会删除 ~/.bugx/core 全局引擎，也不会默认删除 云端凭证或设备身份。需要时可在同一条命令中合并附加范围，交互模式只确认一次：

bugx reset --scope global --reset-identity --reset-credentials --reset-mcp-runtime

项目级重置还会清理项目 .bugx/cloud-sync/ 的 cursor、inbox/outbox 等同步传输状态，但不清理 项目错题集（除非指定 --reset-knowledge）；全局重置相应清理全局同步传输状态。两种重置都会先写入项目外的可恢复备份；任务正在运行或暂停时会拒绝重置。非交互环境使用 --yes， 执行前可用 --dry-run 查看范围。宿主入口、项目身份和用户自定义配置不属于默认重置范围。

6. 查看结果

测试过程和报告保存在项目的 .bugx/ 目录中。逻辑层级是 Project → Session → Round → Life；当前运行时使用 .bugx/pollings/<polling-id>/lifecycles/<lifecycle-id>/ 作为内部物理路径，目录名不改变上述 协议语义。其中 state/ 保存 Life、运行态、Supervisor 和覆盖证据，rounds/ 保存 Life 检查点，events.jsonl 保存 Session 过程事件，report.md、conclusion.json、integrity.json 保存当前 Round 的正式报告、结论和完整性校验。Session 收尾前必须完成证据确认、Life 结算和 Round 报告；如果当前 Round 仍有可执行 Life，只结束该 Life 检查点，不结束 Round 或 Session。

关键目录

路径	用途
core/	仓库中的公共 BugX 协议、运行脚本和模板源码
integrations/	OpenCode、Pi 等宿主的源码适配资源；安装时写入宿主原生目录
src/bugx_cli/	BugX CLI 实现；只负责发现、安装、配置和诊断
evals/	Agent 行为评测案例、黄金结果和评分基线，不参与真实项目计数
.bugx/	当前项目的测试过程、生命周期、报告和项目错题集
.bugx/README.md	当前项目运行目录说明，给人阅读
.bugx/logs/bugx.jsonl	CLI、安装和运行诊断日志；结构化、脱敏、自动轮转
.bugx/core/bugx_mcp_server.py	本地 stdio MCP Supervisor 适配层，不执行 Worker
.bugx/core/	项目级静态目录骨架；其中每个核心载荷文件/目录逐项以相对软链接指向全局引擎（目录本身保留为项目边界）
.bugx/core/bugx.md	指向全局引擎 ~/.bugx/core/bugx.md 的相对软链接（DOC-004 引擎与状态分离）
.bugx/core/AGENT_GUIDE.md	指向全局引擎 AI 执行手册的相对软链接
docs/DOC-002_PROJECT_OVERVIEW.md	项目高级概述、核心技术与量化收益
docs/DOC-003_DESIGN_EXPERIENCE.md	设计经验、宿主接入避坑指南与复盘方法论
docs/DOC-004_ENGINE_AND_STATE_SEPARATION.md	全局引擎与项目双层架构规范（引擎与状态分离、双层错题集）
docs/DOC-006_ARCHITECTURE_MCP_SECURITY_REMEDIATION_PLAN.md	架构、MCP、daemon、云同步与供应链安全整改方案及自动化验收矩阵
docs/DOC-007_KNOWLEDGE_TRUST_CLOUD_MCP_UPGRADE_PLAN.md	知识可信链、Cloud Sync V2 与 MCP 二次升级的审计和实施基线
docs/DOC-008_CLOUD_SYNC_V2_ONLY_0.6.1_IMPLEMENTATION_PLAN.md	0.6.1 私有多设备同步、V2-only、完整详情、遗留安全闭环与发布计划；公共发布仅列后续 TODO
docs/DOC-017_PROJECT_UPGRADE_PLAN_2026-08-31.md	本轮同步恢复、宿主/MCP 能力、命令边界、覆盖率、调度效率和全量验收记录
docs/DOC-018_MODULE_AUDIT_AND_UPGRADE_2026-08-31.md	本轮模块级全量审计、逐条设计复审、升级实现证据和遗留边界
docs/DOC-019_WEB_STANDARDS_CONFORMANCE_PLAN_2026-08-31.md	Web 项目 WCAG/WAI-ARIA/HTML 标准合规审计方案与验收规则
docs/DOC-021_BLACKBOX_FEATURE_MANIFEST_AND_RESOURCE_REUSE_PLAN.md	黑盒功能清单、DAG 依赖与安全资源引用复用方案及验收记录
docs/DOC-022_BLACKBOX_AUDIT_EFFICIENCY_AND_HIT_RATE_UPGRADE_PLAN.md	黑盒状态反馈、Fuzz 进化、预算建议和指南切片方案与设计审计
docs/DOC-023_BUGX_SELF_AUDIT_DYNAMIC_MINING_PLAN.md	BugX CLI/MCP 自举动态挖掘、ddmin 和回归快照方案与设计审计
docs/DOC-024_ALPHA_STABLE_TRANSCRIPT_DIAGNOSTICS_PLAN.md	Alpha/Stable 模型诊断追踪、原文知识回流、私有同步和升级失败日志方案与设计审计
docs/DOC-028_HOST_ADAPTER_AND_OWNERSHIP_MODEL.md	宿主适配层数据模型、hosts.json 哈希归属判定与镜像一致性架构的归档审计
docs/DOC-029_CLI_AND_LAUNCH_SPLIT_PLAN.md	cli.py / launch_bugx.py 渐进式拆分规划（分阶段，规划先行不执行）
docs/DOC-031_ARCHITECTURE_RATIONALE_AUDIT_2026-09-05.md	全量架构合理性审计（分层/数据/生命周期/演进四域，0.6.80 基线）与修复排序
docs/DOC-032_OPENWIKI_NARRATIVE_LAYER_PLAN.md	OpenWiki 叙述层知识接入评估、v1 探针设计与 A/B 验证方案
docs/DOC-033_PRODUCTION_VERSION_POLICY.md	生产仓（AI/bugx）版本策略：alpha 线、退出判据与导出流程
docs/DOC-034_TOKEN_EFFICIENCY_VERIFICATION.md	Token 效率优化方案与核验清单（guide 分层，基线实测与逐阶段判据）
docs/DOC-034_IMPACT_PRUNER_AND_DIFFERENTIAL_ORACLE_DESIGN.md	语法感知 Fuzzer、AST 波及剪枝与确定性差分验证器实施设计
docs/DOC-035_ARCHITECTURE_PROMPT_INTERACTION_AND_MINING_LEAP.md	全景架构解耦、提示词分层与 Bug 挖掘能力跃升设计方案
docs/DOC-036_REDUNDANCY_AND_LARGE_FILE_MODULARIZATION.md	全系统冗余消除、超长代码解耦与模块化重构规范
docs/DOC-036_TEST_SELECTOR_REGISTRY_PLAN.md	注册模式回归测试框架改造方案（test_selector）
docs/DOC-037_DEVELOPMENT_DOCUMENTATION_AND_LIFECYCLE_ALIGNMENT_SKILL.md	开发文档与生命周期协同 Skill（dev-doc）设计与实现规范
docs/DOC-038_SYSTEM_PROMPT_2_0_MODULAR_PROGRESSIVE_HARNESS.md	系统提示词 2.0 分层装载与阶段 Harness 架构
docs/DOC-039_TOKEN_HIGH_CONSUMPTION_OPTIMIZATION_AND_BUDGET_GOVERNANCE.md	Token 高消耗优化与预算治理实施方案
docs/DOC-040_BUGX_MD_STREAMLINE_AND_LAZINESS_GATE.md	Agent 宪法精简与防偷懒门禁设计与实施方案
docs/DOC-041_LOGGING_SYSTEM_UPGRADE.md	诊断日志分析系统升级与双轨耗时/Token瀑布图
docs/DOC-041_STRATEGY_PLANNING_LAYER_PLAN.md	策略规划层设计与实施计划（Strategy Planning Layer）
docs/DOC-042_TOKEN_CONSUMPTION_TELEMETRY_AND_ANOMALY_DETECTION.md	Token 消耗遥测与异常检测设计方案
docs/DOC-043_NEXTGEN_HARNESS_SEMANTIC_SLICING_ACTIVE_INTERCEPTOR.md	下一代 Harness 语义切片与主动拦截器设计方案
docs/DOC-044_NEXTGEN_SCHEDULER_CONCURRENCY_ENGINE.md	下一代任务调度与高并发弹性控制引擎设计方案
docs/DOC-045_MCP_NEXTGEN_PROTOCOL_AND_BUNDLE_UPGRADE.md	下一代 MCP 协议演进与并发亲和对齐设计规范
docs/DOC-046_PROBE_PIPELINE_AND_FUNCTIONAL_COVERAGE_PLANNING.md	统一并发探针调度引擎与环境画像持久化设计规范
docs/DOC-047_CROSS_SECTOR_ALIGNMENT_AND_ISLAND_MODULE_OPTIMIZATION.md	全仓板块功能对齐、孤岛能力修复与模块收益分布优化
docs/DOC-048_I18N_INTERACTION_UPGRADE.md	统一交互组件 zh-CN/en-US 国际化升级方案
docs/DOC-048_WEAK_SECTOR_CAPABILITY_ELEVATION.md	弱能力板块与算法深度专项升级设计规范
docs/DOC-049_GLOBAL_TELEMETRY_AND_TOKEN_GOVERNANCE.md	全局跨项目耗时与 Token 治理看板（bugx stats）
docs/DOC-050_EXCEPTION_RECOVERY_AND_RESILIENCE.md	异常自愈弹性保障与韧性容错设计方案
docs/DOC-051_TEST_GENERATION_QUALITY_ASSURANCE.md	全息测试用例与脚手架生成引擎（bugx test-generate/test-audit）
docs/DOC-052_MINING_AND_TEST_CAPABILITY_ASSURANCE_FRAMEWORK.md	漏洞挖掘全息保证与测试能力验证框架（bugx mining-audit/test-verify）
docs/DOC-053_TEST_QUALITY_AUDIT_AND_REMEDIATION_2026-09-07.md	测试用例质量复盘、修复方案与断言收紧实施记录
docs/DOC-054_FULL_ASSESSMENT_CODE_REVIEW_AND_DOC_ALIGNMENT.md	全量评估、代码审查修复与文档全景对齐设计与实施方案
docs/DOC-055_MCP_MINING_AND_TEST_CAPABILITY_TOOLS_UPGRADE.md	原生 MCP 漏洞挖掘保证与测试用例动态变异验证工具升级
docs/DOC-056_CROSS_PLATFORM_PYTHON_RUNTIME_AND_STANDALONE_FALLBACK.md	跨平台 Python 运行时自动探测优选与 Standalone 便携包引导兜底
docs/DOC-057_PROJECT_CODE_ANALYSIS_AND_SCALE_PROFILING.md	工程代码体量分析、测试比率度量、规模估模与云端看板同步（bugx project）
docs/DOC-058_CODE_ANALYSIS_ENGINE_DEEP_INTELLIGENCE_AND_RISK_PROFILING.md	代码分析引擎深度智能升级：圈复杂度、巨石组件/神仙函数、敏感攻击面与内在风险评分热点画像
docs/DOC-059_ENTERPRISE_CODE_INTELLIGENCE_METRICS_AND_DEBT_MODEL.md	企业级代码智能分析、架构拓扑与技术债经济学模型规范（认知负荷、Halstead MI、代码克隆、Tarjan循环依赖、COCOMO II）
docs/DOC-060_CODE_INTELLIGENCE_DRIVEN_MINING_PIPELINE.md	代码智能驱动漏洞挖掘全链路打通规范（调度优先级倾斜、高危靶点勘测融合、动态提示词注入与作战方案更新）
docs/DOC-061_MULTI_LANG_SAST_AND_SUPPLY_CHAIN_SECURITY_ENGINE.md	多语言声明式静态代码扫描与轻量供应链安全引擎架构设计（通用结构化模式匹配、跨语言规则体系与非侵入容灾）
docs/DOC-062_MULTI_LANG_SCA_EXPANSION.md	全主流语言依赖供应链安全 (SCA) 扩展与确定性锁文件解析规范（PHP/Ruby/.NET/Flutter/Swift/Poetry 纯标准库高信噪比探测）

| docs/AI_REFERENCE.md | AI 使用参考和宿主边界 | | ~/.bugx/core/ | 全局引擎：81+ 核心协议模块（136 个静态引擎文件）单点维护，CLI 升级自动更新 | | ~/.bugx/knowledge/ | 全局通用错题集：跨项目 promote 提炼，新项目 init 继承 | | .bugx/knowledge/ | 项目级 SQLite 错题集 | | ~/.config/opencode/agents/ | 全局注册的 OpenCode Agent 入口（指向全局引擎的符号链接） | | .opencode/agents/ | 项目级 OpenCode 原生入口（指向 .bugx/core/bugx.md 的相对符号链接） | | .codex/skills/bugx/ | Codex 原生 Skill 入口 | | .claude/agents/ | Claude Code 原生 Agent 入口 | | .zcode/agents/ | ZCode 原生 Agent 入口（0.7.22 起不再写入；主/worker 收敛为用户级 ~/.zcode/agents/，旧副本由安装期清扫移除） | | .pi/skills/bugx/、.pi/extensions/bugx/ | 选择 Pi 后生成的原生 Skill 和 Extension |

边界

BugX CLI 只负责发现宿主、安装资源、配置和诊断；它不代替 AI 宿主执行测试，也不自动 启动外部 MCP。插件和 MCP 的加载方式由宿主及其配置决定。

诊断日志默认写入 .bugx/logs/bugx.jsonl，可用 --log-level DEBUG 或 BUGX_LOG_LEVEL=DEBUG 提高详细程度。每条记录带有 event_id 和 trace_id，并可关联 run_id、lifecycle_id、round、worker_id、Finding 和 Incident；日志只用于排查， 生命周期事实仍以 events.jsonl、状态文件和最终报告为准。并发进程通过锁文件协调日志轮转。

模型可见 Prompt 和 stdout/stderr 原文不进入上述 JSONL。Alpha 构建由 core/metadata.txt 的 bugx_channel: "alpha" 显式开启本地 transcript 工件，按 trace_id 保存到当前 Session 的 artifacts/transcripts/（没有 Session 时使用 .bugx/debug/transcripts/）；Stable、缺失或非法通道均不保存原文。Transcript 受输出上限、 0700/0600 权限和原子写入约束。Alpha 原文以及与 Finding/Incident 相关的非敏感源码片段可作为不可信证据参与项目级知识复盘，由 Supervisor 提炼为 candidate Pattern/Incident/Tool Experience；启用私有 project Cloud Sync 且安全扫描通过 后，可随结构化结果进入异步 outbox。global 只接收验证并去项目化的结构化经验（允许携带可复用的最小源码示例），public scope 不属于当前版本。若客户端/服务端尚未提供 transcript artifact wire，必须保留 sync_pending 并报告未实现，不得伪造原文同步成功。详细边界与验收见 DOC-024。

开发验证

"$BUGX_PYTHON" tests/run_tests.py --mode quick
"$BUGX_PYTHON" tests/run_tests.py --mode module --module tests.test_cli --module tests.test_launch_bugx
"$BUGX_PYTHON" tests/run_tests.py --mode all-units --parallel --workers 4
"$BUGX_PYTHON" tests/run_tests.py --mode all-units --parallel --timings-file /tmp/bugx-test-timings.json
BUGX_PYTHON="$BUGX_PYTHON" bash tests/run_tests.sh  # 默认启用隔离并发；可传 --workers N 调整

开发阶段先运行 quick 或受影响的 module；跨模块、状态、SQLite、CLI 安装、日志和发布 改动运行 BUGX_PYTHON="$BUGX_PYTHON" bash tests/run_tests.sh，它默认使用隔离并发，包含单元测试和协议、报告、覆盖、平台、CLI、一致性门禁； 仅需全部单元测试时运行 --mode all-units。run_tests.py 会为每个测试模块创建独立的 HOME、 临时目录和全局错题集；并发只分片执行单元测试，协议、报告和一致性门禁仍串行。--parallel 现在会真正启用并发，未指定 --workers 时默认最多 4 个进程，避免进程型测试过度争用资源。 tests.test_launch_bugx 等慢模块进入独立串行队列，先执行其余模块，再执行慢模块，仍然覆盖全部 测试但避免并发拖慢关键路径；启动协议模块默认再拆成独立测试用例进程，防止单个场景污染同组状态， 并以最多 4 个用例并发执行。模块按历史耗时画像从重到轻调度。可用 --serial-module MODULE 增加慢模块，--case-split-module MODULE 增加用例级隔离模块，或用 --no-serial-slow/ --no-case-split 做基准对比。每个分片默认 600 秒超时，可用 --timeout-seconds N 调整；通过 --timings-file PATH 读取并更新耗时画像，画像只在显式指定时写入。 每次提交代码都必须同步更新受影响 的文档和项目版本号，默认递增补丁版本，并通过一致性检查、定向测试和全量测试。 版本脚本只自动放行同一 MAJOR.MINOR 下一个 PATCH；补丁进位、次版本、主版本、跳跃或回退需人工确认，执行 scripts/bump_version.py 或 dev_doc close 时显式追加 --confirm-version-transition。 GitHub 和其他公网 Git 远端默认禁止推送；只有当前任务明确授权时才允许推送。提交前 必须用 git remote -v 核对远端，只向当前任务明确授权的受控远端提交，禁止 --all、 --mirror 或多远端推送。