把开发对话中已经发生过的 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[人工审核]
- 从真实开发历史提炼知识：读取明确配置的 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 管理台，不设置发布阻断，也不输出“允许发布”结论。
要求 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 | 本地脚本、人工维护、可审计的自动化 | node dist/cli.js --home <私有目录> --json call bugs_search --file query.json |
| MCP | Codex、Claude Code 或其他支持 MCP 的智能体 | stdio 启动：node <仓库>/dist/cli.js --home <私有目录> mcp serve |
| Skill | 让项目智能体按固定安全流程使用 CLI/MCP | node <仓库>/dist/cli.js --json skill install --client codex --scope project --root <目标项目> |
Skill 安装位置：
- Codex：
<root>/.agents/skills/bug-manager - Claude 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、npm pack、独立安装、CLI、MCP、worker 与产品 Skill 安装检查 |
| 当前源码自动验证 | 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 | 未发布；package.json 保持 private: true，防止在最终包名、账号和发布决定明确前误发包 |
证据入口：
| 文档 | 内容 |
|---|---|
| 使用说明 | 安装、配置、CLI/MCP/Skill、完整闭环、错误处理 |
| 运行与维护 | 数据目录、备份迁移、升级和发布边界 |
| 接口契约 | CLI/MCP 对照、分页、响应信封和报告结构 |
| 数据模型 | 关系、版本、等级、去重、计划和证据模型 |
| 已确认决策 | 产品约束、讨论结论和工程默认值 |
| AGENTS.md | 开发本项目时必须遵循的规范驱动与隐私规则 |
| OpenSpec proposal | 首版目标和能力边界 |
| OpenSpec design | 架构和处理流程 |
| OpenSpec tasks | 实现与验证进度 |
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。