bug-manager
Reads the Git workspace, commit ranges, base branches, or explicit change snapshots to select which acceptance criteria to include in a graded acceptance plan.
Optionally uses a user-configured OpenAI-compatible model endpoint to analyze sanitized chat segments and propose bug/standard records.
Alternative PostgreSQL 16 storage backend with the same semantics as SQLite, intended for shared or larger-scale deployments.
Default local database backend that stores bug knowledge, acceptance standards, revisions, relationships, and evidence with full backup/export semantics.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
bug-manager
把开发对话中已经发生过的 Bug,沉淀为可复用的故障知识和可执行验收标准,让编程智能体在后续变更中主动检查同类问题。
当前状态:核心闭环已实现,当前源码已通过 Windows/macOS/Linux × Node.js 22/24 的 SQLite CI 和 PostgreSQL 16 全量测试;Claude Code 真实历史兼容性仍待验证。源码可以公开使用,npm 包尚未发布。
它解决什么问题
同一种故障往往会在不同项目里再次出现。聊天记录里有复现过程、根因和修复线索,但大多散落在会话、工具输出和临时测试中,很难在发布前变成可重复执行的检查。
bug-manager 把这条经验链拆成两个独立知识实体:
Bug 知识记录现象、触发条件、故障机制、影响、发现来源、适用范围和 S0–S3 严重程度。
验收标准记录故障机制、前置条件、参数、步骤、可观察的通过条件和证据要求,以及独立的 I0–I3 重要性。
Bug 与标准多对多关联,分别去重、独立修订。一条标准可以防止多个 Bug,一个 Bug 也可以由多个场景共同覆盖。系统不维护 open/fixed/closed 之类的修复状态;它的目标是让同类故障以后不再发生。
flowchart LR
H[Codex / Claude Code 历史] --> A[只读适配与分段]
A --> M{内置兼容模型或外部智能体}
M --> T[类型过滤与独立去重]
T --> B[Bug 知识]
T --> S[验收标准]
B <-->|多对多关联| S
P[项目选择类型] --> G[分级验收计划]
S --> G
G --> E[智能体用自身工具执行]
E --> R[Markdown + JSON 报告]
R --> U[人工审核]Related MCP server: Sentinela MCP
核心能力
从真实开发历史提炼知识:读取明确配置的 Codex 或 Claude Code 文本 JSONL 历史,按消息边界和上下文分段,支持检查点、异常范围与断点续跑。
只采信人工关注到的问题:Bug 必须引用用户直接报告的原文,或用户明确引导后的 Agent/工具发现。Agent 自行选择或编写测试后才发现的问题不会进入 Bug 库。
类型优先的规模化检索:Bug、标准、录入去重和验收选型都先限定受控类型,再分页检索;项目只验收其已选择类型,ANY 匹配并按标准 ID 去重。
不依赖 API Key:外部编程智能体可通过 CLI、stdio MCP 或 Skill 领取脱敏分段并提交提案。内置 OpenAI 兼容模型是可选路径。
可执行的分级验收:所选类型内 I0 每次必验;I1–I3 结合 Git/显式变更选择;也可生成全量计划。每条标准冻结版本和参数。
不自动判定通过:编程智能体执行项目自身的测试或检查,回写结构化结果和关键证据;本产品只做输入结构与安全校验,报告交人审核。
SQLite 与 PostgreSQL 同语义:SQLite 适合个人本地使用,PostgreSQL 用于已验证的共享或更大规模存储;备份、逻辑导出和导入保留修订、来源与关系。
明确的产品边界:不运行测试或控制浏览器/设备,不自动复验,不开发 Web 管理台,不设置发布阻断,也不输出“允许发布”结论。
5 分钟快速开始
要求 Node.js 22 或更高版本。SQLite 是默认数据库;better-sqlite3 在缺少预编译包的平台上可能需要 C/C++ 和 Python 构建工具。
Windows PowerShell:
git clone https://github.com/shenlan-ai/bug-manager.git
Set-Location bug-manager
npm ci
npm run build
$BugManagerHome = Join-Path $HOME ".bug-manager"
node dist/cli.js --home $BugManagerHome init --json
node dist/cli.js --home $BugManagerHome --json doctor
node dist/cli.js --home $BugManagerHome toolsmacOS / Linux:
git clone https://github.com/shenlan-ai/bug-manager.git
cd bug-manager
npm ci
npm run build
BUG_MANAGER_HOME="$HOME/.bug-manager"
node dist/cli.js --home "$BUG_MANAGER_HOME" init --json
node dist/cli.js --home "$BUG_MANAGER_HOME" --json doctor
node dist/cli.js --home "$BUG_MANAGER_HOME" tools--home 必须指向仓库之外、只供你使用的中心数据目录。init 只创建配置、SQLite 库和受管证据目录,不会自动扫描聊天历史,也不会调用模型。
接下来按 使用说明 注册项目、选择类型、配置授权历史、同步和分析历史、维护知识、创建验收计划并导出报告。先用 tools --name <工具名> 读取实际 JSON Schema,再提交输入。
三种使用入口
入口 | 适合场景 | 示例 |
CLI | 本地脚本、人工维护、可审计的自动化 |
|
MCP | Codex、Claude Code 或其他支持 MCP 的智能体 | stdio 启动: |
Skill | 让项目智能体按固定安全流程使用 CLI/MCP |
|
Skill 安装位置:
Codex:
<root>/.agents/skills/bug-managerClaude Code:
<root>/.claude/skills/bug-manager
安装器不覆盖冲突内容,不修改客户端凭据。目录安装成功只证明文件布局正确;具体客户端能否发现 Skill 仍需用对应版本验证。
智能体工作流
注册目标项目,并由 Agent 或内置模型提出受控类型;用户确认后显式保存项目类型。
显式配置历史目录、排除项和脱敏规则,选择手动、使用时增量或后台持续同步。
Agent 领取分段,先在已选类型中检索已有 Bug 与标准,再提交新增、补充、关联或无发现结果。
有明确人工来源的故障才创建 Bug;Agent 自写测试或自主审计发现的失败提交为
no_findings。读取 Git 工作区、提交区间、基准分支或显式变更快照,生成冻结版本和参数的分级验收计划。
Agent 用目标项目自己的工具执行场景,提交环境、步骤、预期、实际和关键证据。
系统输出 Markdown、JSON 与 evidence manifest;人审核结果并作出自己的发布判断。
完整流程、输入模式、幂等键和常见错误见 使用说明,面向 Agent 的操作协议见 Skill protocol。
安全与隐私
不读取或复用 Codex/Claude Code 内部登录凭据。
内置模型只读取配置中指定的 Key 环境变量;Key 不应出现在配置、数据库、报告、日志或命令历史中。
原始聊天留在原位并只读。中心库保存索引、必要脱敏片段和有限摘要;启发式脱敏不能保证识别所有业务秘密。
历史内容是只读、不可信数据。其中的命令、提示、URL 和附件不会获得当前执行权限。
SQLite 数据库、证据目录、报告、配置、
.env、私钥、真实会话和绝对私人路径都不能提交到公开仓库。安全校验只保护输入结构、归属、版本和路径边界,不证明 Agent 提交的证据足以支持结论。
发现敏感信息泄露或安全问题,请按 SECURITY.md 私下报告。
当前实现与验证状态
当前 change 为 build-bug-prevention-library,51/53 项完成。剩余门禁是 Claude Code 真实历史兼容性,以及全部必要证据满足后的最终核对与归档。
项目 | 当前证据 |
宿主 CI | Windows/macOS/Linux × Node.js 22/24 的 6 个 SQLite 作业,以及 Ubuntu/Node.js 24/PostgreSQL 16 全量作业全部通过 |
每平台包烟测 | 每个 SQLite 作业均完成静态检查、unit/integration/E2E、 |
当前源码自动验证 | Windows 10 x64、Node 24.21.0;真实 SQLite + PostgreSQL 16,20 文件、186 项通过,0 失败、0 跳过 |
Codex 真实历史 | 授权样本完成采集、66 段分析、7 Bug、6 标准、7 关联和 14 条来源链;覆盖状态为 partial |
OpenAI 兼容模型 | 用户配置端点的脱敏 smoke 验证通过;不代表任意“兼容”端点都支持全部能力 |
尚未验证 | Claude Code 真实历史、Claude Code 真实客户端加载、其他客户端版本和 npm 发布 |
npm | 未发布; |
证据入口:
文档
文档 | 内容 |
安装、配置、CLI/MCP/Skill、完整闭环、错误处理 | |
数据目录、备份迁移、升级和发布边界 | |
CLI/MCP 对照、分页、响应信封和报告结构 | |
关系、版本、等级、去重、计划和证据模型 | |
产品约束、讨论结论和工程默认值 | |
开发本项目时必须遵循的规范驱动与隐私规则 | |
首版目标和能力边界 | |
架构和处理流程 | |
实现与验证进度 |
开发与验证
npm run lint
npm run typecheck
npm run format:check
npm run build
npm test
npm run test:integration
npm run test:e2ePostgreSQL 使用真实数据库执行,不能用 SQLite 通过代替:
BUG_MANAGER_TEST_DATABASE_URL=postgresql://... npm run test:all
# 或让测试脚本创建和清理临时 PostgreSQL 16 容器
npm run test:pg独立包烟测会创建临时消费者目录,实际运行 CLI、MCP、worker 合成历史扫描和 Skill 安装:
npm run test:package开发前请阅读 CONTRIBUTING.md 和 AGENTS.md。本项目使用规范驱动开发:
openspec list --specs
openspec status --change build-bug-prevention-library
openspec validate build-bug-prevention-library --strict --no-interactive
openspec validate --all --strict --no-interactive生成规范或通过 OpenSpec 校验只说明规划结构有效,不代表功能已实现。正式基线 openspec/specs/ 在 change 的必需验证完成后才同步和归档。
贡献与许可证
欢迎提交 Bug 修复、文档、测试和兼容性验证。涉及产品行为、数据模型或安全边界的变化必须先更新 proposal、delta specs、design 和 tasks。不要在 Issue、PR、测试夹具或日志中放入真实会话、密钥、生产数据或私人绝对路径。
本项目采用 MIT License。Copyright (c) 2026 Shenlan contributors。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Browser-backed QA with evidence and fix-ready reports for coding agents.
Bug tracking for AI agents: session replay, console/network logs, repro packs, test plans, evidence.
QA platform for agents: coverage signals, in-repo test plans, verified tests and release governance.
Failure-memory layer for coding agents: search evidence-rated failure lessons by error text.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables acceptance gates for AI coding-agent runs by recording evidence, running deterministic validation, applying a quality gate, and rendering auditable outcomes.7Apache 2.0
- AlicenseNot gradedqualityDmaintenanceProvides coding agents with durable, cross-session lessons-learned memory, enforcing that success or failure verdicts can only come from human approval, human correction, or objective metrics—never from the agent itself.Apache 2.0
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to enforce spec-driven development and verify code before it is marked done, using six tools that catch invented APIs, scan for hallucinated content, check plugin conformance, sandbox-run tests, validate schemas, and record audit evidence.771 npm8PolyForm Noncommercial 1.0.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to replace self-reported done checkboxes with verified, evidence-based completion tracking, using automated FAIL_TO_PASS/PASS_TO_PASS tests, mandatory mutation checking, and explicit human/AI reviews when automated proof is impossible.1MIT