Metadata-Version: 2.4
Name: kba-cli
Version: 0.3.0rc5
Summary: KBA - read-only knowledge base auditor (local-first)
Author: KBA
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: extract
Requires-Dist: pypdf>=4.0; extra == "extract"
Requires-Dist: python-docx>=1.1; extra == "extract"
Requires-Dist: python-pptx>=0.6.23; extra == "extract"
Requires-Dist: openpyxl>=3.1; extra == "extract"
Dynamic: license-file

# 知库体检（KBA）

> 只读体检本地知识库：健康分、重复裁决建议、治理计划；数据不出本机。
> 独立项目，不修改 `D:\content_hub`；复用其算法与规则（独立实现）。

## 状态（2026-11-05）

**v0.3.0rc4（内部预发布）：P0 报告诚实层 + P1 抽取层 + P1 准确性前两批 + 抽取并行/TTL + 标注评测。**
**Gate 1 外部语料验证未通过，不能对外称稳定版或“完整审阅”。**

- 真实内部语料（215 文件 / 58.2MB）只读跑通：抽取 110/113（失败 0、no_text 3）、文本覆盖 97.4%、健康 80、重复 2 组、标签有效覆盖 75.8%、自检索 48%、owner 0%；仍是单个内部语料，不是 Gate 1
- 真实语料 54 文件 AI 辅助标注样本：抽取 97.35%、PII 8/8；近重复/同名/页级标签由预测簇反推，仅验证链路；标签 exact 0、Jaccard 0.13，说明推断标签过标，需人工校准
- P0：A/B/C 数据置信度、健康分按可用指标归一化并显示权重覆盖度、抽取三态、Office 计入盘点、正文缓存 TTL 与 `--purge-text`、报告“数据覆盖与结论适用范围”；C 级元数据报告不展示综合健康分
- P1 抽取：`kba extract` 用 pypdf / python-docx / python-pptx / openpyxl 抽取 PDF、Word、PPT、Excel 正文；Excel 结构指纹（sheet/公式模式/named range）识别“同模型不同版本”；旧版 `.ppt/.xls/.doc` 显式标 unsupported
- P1 准确性：PDF 去页眉页脚、PDF/PPT 页级切分、跨文档页级重合（不自动合并）、终稿/底稿信号 + 正文字数/相似度差异、人工裁决队列、PII 正则初筛（仅计数）、标签/领域三层推断（frontmatter + 路径/文件名 + 内容）、负责人覆盖与本地断链检测、`kba clean --purge-extract`
- P1 运维：`kba extract --workers` 并行抽取、默认 7 天 sidecar TTL、`tools/bench_scan.py` 合成基准
- 评测：`kba eval` 读取标注 JSON，输出近重复/同名/页级/版本/PII 的 P/R/F1、标签 exact/Jaccard、抽取成功率；合成语料只证明回归，不代表外部准确率
- 本地连接器：免费 `connector-local`（kba-local）+ `kba scan-summary`；付费专家依赖它，连接器不可用才回退粘贴摘要
- 产出：[demo/report.html](demo/report.html)、[demo/share.md](demo/share.md)（均为 P0 前版本，重新生成后含新章节）
- 50 个测试通过（P0 验收 + 抽取/结构指纹/失败态/UTF-16/页级/版本/PII/标签/断链/purge/并行/TTL/评测）
- **免费入口旧版在线**；新包 v0.1.7「知识库体检与治理顾问」已构建，待 0.1.6 审核结束后上传；企业账户可建连接器但**无法开通收款**，已回退到个人账户的付费技能路径

## 快速开始

```bash
cd D:\kba
pip install -e ".[extract]"       # 含 PDF/Office 抽取依赖；不装也能跑元数据模式
# 或安装内部预发布 wheel（本地构建，不对外发布）：
# python -m pip install "dist/kba_cli-0.3.0rc4-py3-none-any.whl[extract]"

python -m kba doctor                # 环境自检
python -m kba extract --root "D:\你的资料" --out "D:\kba-extract"
python -m kba audit start --root "D:\你的资料" --extract-dir "D:\kba-extract" --foreground
python -m kba audit analyze
python -m kba audit report --out report.html
python -m kba audit share  --out share.md
python -m kba eval --root "D:\你的资料" --labels labels.json --json  # 标注语料评测
python -m kba clean --purge-text    # 立即清理 job/text 正文缓存（默认 TTL 7 天）
python -m kba clean --purge-extract --dir "D:\kba-extract"  # 清理抽取 sidecar
```

只做元数据盘点时可跳过 `kba extract` 与 `--extract-dir`；报告会标 C 级且不展示综合健康分。

平台内使用（WorkBuddy）：

```
连接器：connector/（CLI + Skill 方案）
技能：kb-audit / kb-clusters / kb-taxonomy
```

## 目录

```
kba/
├── kba/                 # Python 包（cli/doctor/jobs/fingerprint/extract/tags/links/pii/analyze/report/telemetry）
├── connector/           # WorkBuddy 发布包（meta / cli.json / 3 个 SKILL）
├── plugin-free/         # 免费引导插件包（技能入口：.codebuddy-plugin + skills）
├── plugin-free-expert/  # 免费引导专家包（专家入口：plugin.json + agents + avatar）
├── plugin-paid-expert/  # 付费专家包 v0.1.1（体检与治理顾问；不读本地文件）
├── plugin-paid/         # ¥1 付费试用插件包（旧方案）
├── packs/generic/       # 通用行业包（taxonomy/tags/rules/report）
├── tests/               # smoke tests
├── tools/               # vendor 同步 / 插件打包 / 提审检查 / 合成基准
├── demo/                # 真实语料报告（本地生成，不入库）
└── docs/                # PRD、平台 6 问、访谈提纲、定价实验
```

## 文档

| 文档 | 说明 |
|---|---|
| [CHANGELOG.md](CHANGELOG.md) | 版本变更与预发布说明（0.3.0rc4） |
| [docs/eval-labels.md](docs/eval-labels.md) | `kba eval` 标注格式、指标口径与 Gate 1 用法 |
| [docs/summary-v2.md](docs/summary-v2.md) | `kba-summary v2`：领域/标签/覆盖 caveat/脱敏字段 |
| [docs/tag-precision.md](docs/tag-precision.md) | 标签准确率治理：指标、规则、holdout 与限制 |
| [docs/free-entry-runbook.md](docs/free-entry-runbook.md) | 免费专家召唤验收、冻结规则与反馈表（旧版 5 问流程） |
| [docs/free-expert-0.1.6-update.md](docs/free-expert-0.1.6-update.md) | 免费专家 0.1.6 顾问版更新与平台发布步骤 |
| [docs/free-expert-0.1.7-update.md](docs/free-expert-0.1.7-update.md) | 免费专家 0.1.7：summary v2 + 10 个黄金摘要；待 0.1.6 审核后上传 |
| [docs/development-plan-0.1.7.md](docs/development-plan-0.1.7.md) | **0.1.7 / CLI 0.3.0rc5 完整开发、测试与发布计划** |
| [docs/platform-test-guide.md](docs/platform-test-guide.md) | **逐项测试手册**：免费专家 / 本地 CLI / 付费技能 |
| [docs/paid-skill-test.md](docs/paid-skill-test.md) | ¥1 付费技能本地执行测试：提交、购买、判定与退款 |
| [plugin-paid-audit/README.md](plugin-paid-audit/README.md) | 付费本地扫描技能 kba-local-audit v0.1.0 |
| [docs/paid-audit-review-notes.md](docs/paid-audit-review-notes.md) | kba-local-audit 审核说明与答辩 |
| [plugin-paid-expert/README.md](plugin-paid-expert/README.md) | 付费专家包 v0.1.1：定位、发布字段与提审检查 |
| [docs/paid-expert-listing.md](docs/paid-expert-listing.md) | 付费专家上架文案：花名、职称、100 字能力介绍 |
| [connector-local/README.md](connector-local/README.md) | 免费本地连接器 kba-local：结构、命令与提审顺序 |
| [docs/connector-submission.md](docs/connector-submission.md) | 连接器提审手册（当前因企业收款不可开通而冻结） |
| [docs/handoff.md](docs/handoff.md) | **新任务交接**：现状、决策、P0/P1 状态、验收与启动提示词 |
| [docs/master-assessment-and-plan.md](docs/master-assessment-and-plan.md) | **单一事实源**：完整缺口、可信度分级、P0/P1/P2 计划与验收门 |
| [docs/prd-conformance-review.md](docs/prd-conformance-review.md) | PRD 与 WorkBuddy 专家规范符合性评审、偏差与修正清单 |
| [docs/PRD.md](docs/PRD.md) | PRD v1.8：需求、FR、接口、决策建议、v0.3.0rc4 实现状态 |
| [docs/platform-questions.md](docs/platform-questions.md) | 平台 6 问调研答案、提审避坑清单与剩余 2 个待验证项 |
| [docs/interview-guide.md](docs/interview-guide.md) | 10 人次访谈提纲与评分 |
| [docs/interview-guide-investment-research.md](docs/interview-guide-investment-research.md) | 投研首站的 10 人次访谈提纲（卖方/买方/独立/IT） |
| [docs/vertical-investment-research.md](docs/vertical-investment-research.md) | 投研垂直方案：ICP、痛点、体检产品、定价与 90 天验证 |
| [docs/pricing-experiment.md](docs/pricing-experiment.md) | 免费/付费切分与 ¥99/199/299 实验 |
| [docs/paid-trial-runbook.md](docs/paid-trial-runbook.md) | ¥1 付费试用技能的完整执行步骤、判据与分流 |
| [docs/pre-submit-review.md](docs/pre-submit-review.md) | 提审前评审：自动化检查、逐项合规、修复项与剩余风险 |
| [docs/submission-log.md](docs/submission-log.md) | 平台提交记录、审核状态与过审后的操作顺序 |
| [docs/repo-setup.md](docs/repo-setup.md) | 远程仓库、CI、分支保护与公开前的拆分计划 |
| [docs/developer-profile.md](docs/developer-profile.md) | 开发者主页：头像、昵称、简介与联系方式填写建议 |
| [docs/product-gap-assessment.md](docs/product-gap-assessment.md) | 产品缺口深度评估：数据接入、分析准确性、报告可信度与优先级 |

## 已知限制

- **只读**：v0.3.0rc4 不提供 apply/undo，治理执行仍在服务侧。
- **抽取是可选的**：不跑 `kba extract` 时仍是元数据模式，报告标 C 级、不展示综合健康分；`pip install -e ".[extract]"` 是抽取前置。
- **旧版 Office 只计数**：`.ppt/.xls/.doc` 不做 LibreOffice 转换，显式标 unsupported；`.pptx/.xlsx` 已可抽取。
- **Excel 结构指纹只识别有公式/named range 的模型**：纯数值工作簿即使 sheet 同名也不会被当作“同模型不同版本”，避免误报。
- **页级重合不是整档裁决**：PDF/PPT 单页高重合会报告，但不进入重复簇、不自动折叠；版本差异目前是终稿/底稿信号 + 字数/相似度/增删字符摘要，未做逐段正文语义 diff。
- **PII 是正则初筛**：只覆盖邮箱/手机号/身份证/银行卡/密钥/合同编号模式，可能误报/漏报；报告只显示计数与文件名，不展示原文。
- **编码仍有边界**：UTF-8/GB18030/UTF-16(BOM) 可读；Big5/Shift-JIS 在 GB18030 可解码时仍可能是乱码（已报 `text_unreadable` 的只覆盖解码失败场景）。
- **正文缓存有 TTL 但不加密**：`job/text/` 默认保留 7 天；`kba extract` 默认在抽取前清理超过 7 天的 sidecar（`--ttl-days -1` 关闭）；`kba clean --purge-text` / `--purge-extract` 可立即清理。金融/律所客户仍需显式说明缓存策略。
- **标签/领域推断是关键词规则**：frontmatter + 路径/文件名 + 内容关键词，单篇最多 6 个标签；可能误标/漏标，未接入行业词表校验。
- **负责人只读 frontmatter**：`owner/负责人` 字段；ACL、最后访问、文档系统 owner 未接。
- **断链只查 Markdown 本地相对链接**：跳过 http/https、`file:`/`javascript:` 等 URI scheme 和 `@ref` 占位符；不查外链、仓库外目标、非 Markdown 引用。
- **性能基线只是合成 5k**：`tools/bench_scan.py` 本机 5k 文本约 scan 9.6s / analyze 1.9s；50k 与真实 PDF/Office 语料未测。
- **时效判断不可靠**：文件系统 mtime 在复制/迁移后会重置；报告会提示“仅供参考”，后续接入文档系统 `updated`。
- **PDF/docx 标签不在文件内**：推断可补一部分，但二进制标签仍不如文本 frontmatter 可靠。
- **行业包未加载**：`packs/generic` 目前是配置草案，v0.4 起生效。
- **许可证暂用 MIT**：待 Q10 决策后可能切 Apache-2.0。

## 下一步

1. **P1 剩余准确性**：逐段正文语义 diff、ACL/文档系统 owner、标签误报治理与行业词表；用 3 个外部语料验收抽取 ≥90%、近重复召回 ≥80%。
2. **报告可验收**：PDF 报告、报告哈希/签字页、执行摘要；默认脱敏分享。
3. **工程门禁**：Windows CI 已在 `.gitcode/workflows/ci.yml` 增加；补 5 万文件性能基线、云占位/权限拒绝/Big5 fixtures。抽取并行与 sidecar TTL 已加。
4. 按 [docs/paid-trial-runbook.md](docs/paid-trial-runbook.md) 走路径 B：免费包 → 过审 → 收入变现 → ¥1 付费技能验证。
5. 按 [docs/interview-guide.md](docs/interview-guide.md) 约 10 人访谈；3 个外部语料跑通前不卖“完整审阅”。
6. 连接器提审；根据 ¥1 验证结果决定付费报告形态。
