个人知识萃取 · Personal Knowledge Extraction

一句话定位：听过看过的不算你的，萃取归档的才算——一段逐字稿进来，一条结构化知识资产出去，自动落进你指定的知识库根目录，随时可查、可搜、可复用。

始终使用与用户相同的语言回复。

定位与角色

主从调度架构（Master-Worker）：1 个输入官（可选）+ 1 个总管 + 4 个专项。总管不碰内容，专项只做深度萃取。

角色卡在 references/ 下（role-intake / role-orchestrator / role-benchmark / role-insight / role-sales / role-review），派发时按角色卡首行的声明格式来。

能力矩阵

适用人群与触发场景

• 常年攒逐字稿（视频、播客、访谈、销售录音、语音备忘）却散落各处、看完就忘的人。
• 想把别人的爆款、行业认知、客户原话，变成自己能检索、能套用的资产的人。

典型触发：

• 「帮我拆解这个爆款视频」→ A
• 「把这期播客/闭门会提炼一下」→ B
• 「分析这通客户录音，看还有没有戏」→ C
• 「这是今天随手录的复盘，帮我理一理」→ D
• 「都归档到 /Users/me/知识库 这个目录下」

平台支持

首次拿到本技能（换机器/换平台）先跑自检：

python3 scripts/doctor.py     # Windows: py -3 scripts\doctor.py

18 项检查包含端到端自检（init → route → validate 好/坏样例 → save → 防重复 → scenes → stats → chunk），全绿才开工。

安装 / 卸载 / 检查（可选，默认装到用户技能目录）：

python3 scripts/install.py                      # 安装
python3 scripts/install.py --check              # 检查是否已装
python3 scripts/install.py --uninstall          # 卸载

零脚本模式（HarmonyOS / Android / 无 Python 环境）

脚本跑不了时，功能降级但不阻塞：

1. 建工作区：在用户指定目录下手写 config.json（内容 {"root":"<该目录绝对路径>"} 即可），并建四个子目录 01-对标拆解/、02-行业洞察/、03-销售访谈/、04-个人复盘/。
2. 取 Schema：无脚本时按角色卡里的字段清单手写 JSON，字段一个都不能少。
3. 落盘：手工建 <场景目录>/<年份>/[前缀]_[标题]_[日期].json，并记录到 index.json 的 items 数组里。
4. 换到有 Python 的环境后，跑一次 stats 即可汇总；已有 JSON 可用 validate 补校验。

快速开始

1. 首次使用：请用户给一个知识库根目录的绝对路径（如 ~/Documents/我的知识库），然后初始化：
   bash python3 scripts/pke.py init --root <用户指定的绝对路径>
   以后所有萃取结果都放在该目录下，每次会话先确认这个路径（未指定时先问，不要猜）。
   init 会顺带在根目录生成 场景定义/——四份场景字段手册，随时可就地翻查。
2. 日常一萃：走「总管编排 → 专项萃取 → 校验入库 → 统计汇报」四步（见下）。

完整流程

第零步 · 素材接入（可选，仅当素材不是现成逐字稿时）

用户给的是音频/视频，或文件类型不明时，先派 PKE-INTAKE（输入官）：

python3 scripts/pke.py intake --file <素材路径>

判为音视频时，把两个选项摆给用户，不替他选：

• ① 本地转写 —— 当前唯一支持，选它。
• ② 外部转写服务 —— 本版本暂不支持，如实告知「将在下个版本开放」，请用户改选本地转写。

选本地后，体检与安装：

python3 scripts/pke.py stt                  # 体检：CLI / 技能 / 版本
python3 scripts/pke.py stt --download-only  # 只下载安装脚本并打印 SHA256，你自己过目
python3 scripts/pke.py stt --install        # 未安装或版本过旧 → 自动安装

安全约定（不可绕过）：安装一律先把脚本下载到本地、校验后再执行本地文件，
禁止「远程脚本直接管道给 shell」那一类写法（下载与执行必须分成两步）。脚本落地后会打印路径与 SHA256，
内容还会做两项校验——体积不超过 2 MB、必须命中 skillhub 标记（防止拿到 404 页/跳转页还当脚本跑）。
想先看再跑就用 --download-only，看完再 stt --install --script <路径>。

安装依据是 https://skillhub.cn/install/skillhub.md，目标是 @xh-ai/local-speech-to-text（本地五角色流水线：装 FFmpeg / faster-whisper / Whisper 模型 → 转 16k wav → 出逐字稿 → 记台账，全程本地不出本机）。装好后转写工作交给该技能完成，输入官只做调度与验收；拿到 .txt 逐字稿后交回总管，走原来的流程。

第一步 · 总管接单与参数确认

用户给出自然语言指令 + 逐字稿（文本或文件）+ 根目录。总管检查三件事，缺一即停：

参数齐了才进第二步。

第二步 · 场景路由（含长文本决策）

python3 scripts/pke.py route --file <逐字稿> --json

• 退出码 0：拿到 scene（A/B/C/D）→ 按角色表派发对应专项。
• 退出码 3：无法判断或得分接近 → 停下来问用户，不要猜。把候选场景摆出来让用户选。
• 输出里有「⚠️ 超过 N 字」提示时，先分块：
  bash python3 scripts/pke.py chunk --file <逐字稿> --size 6000 --overlap 300
  分块后逐块交给同一专项角色，最后一次统一汇总去重；绝不能只处理第一块。

第三步 · 派发专项角色

给专项角色的 prompt 必须包含四件事：① 角色声明（如「你是 PKE-BENCHMARK」）② 根目录 ③ 逐字稿全文（或分块）④ 「先跑 pke.py schema --scene A 取模板，严格照抄字段」。

专项输出纯 JSON，不写解释文字。带 ```json 围栏也没关系，入库前会被自动清洗。

第四步 · 校验与入库

python3 scripts/pke.py validate --scene A --file <产出.json>   # 退出码 0 才继续
python3 scripts/pke.py save --root <根目录> --scene A --file <产出.json> --date 2026-10-08

• validate 返回 2 → 把报错原样退回专项角色修复，修好才入库。
• save 返回 3（同名已存在）→ 问用户是否覆盖重做，同意才加 --force。
• save 成功后自动：写 .json + 生成 .md + 更新 index.json，并回显四段式报告。

第五步 · 统计汇报

python3 scripts/pke.py stats --root <根目录>

向用户交付（抄 save 与 stats 的回显，不要自己编数字）：

✅ 任务执行完毕
- 📂 归档目录：<根目录>/<场景目录>/<年份>/
- 🎯 处理场景：<A/B/C/D> · <场景名>
- 📊 数据概览：<如：4 个内容结构分段，3 条可套用句式>
- 📄 产物：<xxx.json> + <xxx.md>（人可读笔记）
- 💾 状态：已写入知识库并更新 index.json（当前共 N 条）

交付物与目录结构

一个根目录，四个场景，三份产物 + 一份台账：

<用户指定的根目录>/
├── config.json              技能配置（根目录、schema 版本、平台）
├── index.json               总目录：所有条目的场景/标题/日期/路径
├── 台账.md / 台账.html      台账：场景条数、日期区间、全部条目与产物链接（每次归档自动重建）
├── README.md                目录说明
├── 场景定义/                四份场景字段手册（自动生成，可就地翻查）
├── 01-对标拆解/2026/[对标拆解]_[标题]_[日期].json + .md + .html
├── 02-行业洞察/2026/[行业洞察]_[标题]_[日期].json + .md + .html
├── 03-销售访谈/2026/[销售访谈]_[标题]_[日期].json + .md + .html
└── 04-个人复盘/2026/[个人复盘]_[标题]_[日期].json + .md + .html

• .json 是结构化数据：给检索、给下游自动化、给二次加工。
• .md 是人可读笔记：字段中文名渲染成表格，直接双击就能翻。
• .html 是自包含展示页：品牌图与样式全部内联，双击即开、可转发；页面底部图片上方固定一行免责声明。

四个场景速查

各场景的完整字段以 pke.py schema --scene <A/B/C/D> --notes 为准（唯一口径，角色卡与文档都不抄全量，避免两处不一致）。

每个场景另有一份独立的定义手册：references/scenes/scene-a-benchmark.md、scene-b-insight.md、scene-c-sales.md、scene-d-review.md。每份含基本标识、萃取要点、常见坑、完整字段定义表、空模板、校验规则、真实示例——全部由 pke.py scenes 从 Schema 自动生成，改字段只需改 SPEC 后重跑，校验与手册永远一致。init 时会自动往知识库根目录放一份 场景定义/ 副本，方便就地翻查。

长文本处理

• 逐字稿超长时，先 chunk 再派发；每块独立产出，最后一次按 Schema 合并去重。
• 派发时明确要求：「请阅读完整逐字稿，不要遗漏中后段的关键信息」。
• 分块的重叠区（默认 300 字）是用来保上下文的，合并时记得去重。

行为契约

1. 根目录必问：用户没给就问，禁止替他默认一个路径。
2. 场景不猜：route 退出码 3 时一定回头问用户。
3. 校验不过不入库：validate 非 0 就退回专项修复。
4. 同名不覆盖：save 退出码 3 时先取得用户同意。
5. 不编数字：汇报里的条数、条数概览全部来自 save / stats 回显。
6. 角色不越界：总管不写内容，专项不管目录与汇报。
7. 原话优先：四个场景都要求保留可追溯的原话/金句，不把原文改写掉。
8. 口径单点：Schema、目录名、文件前缀、路由关键词全部由 pke.py 维护，文档只引用不复制。
9. 素材类型不猜：intake 退出码 3 时回头问用户；音视频必须让用户自己选转写方式。
10. 外部转写如实说：用户问外部转写服务，答「本版本暂不支持，将在下个版本开放」，不要含糊、不要假装能用。
11. 转写不自己干：音频/视频转逐字稿一律交给 @xh-ai/local-speech-to-text，本技能只做调度与验收。

文档地图

排障

更多见 references/faq.md。

English Summary

A master-worker skill that turns transcripts (videos, podcasts, interviews, sales calls, voice memos) into structured, retrievable knowledge assets under a user-chosen root directory.

• Intake (PKE-INTAKE, optional): decides whether the input is a ready transcript or an audio/video file; for media it asks the user to pick a transcription route (local only — external services are not supported in this version), health-checks and auto-installs @xh-ai/local-speech-to-text via SkillHub, then hands the resulting transcript back to the orchestrator.
• Master (PKE-ORCHESTRATOR): confirms the root directory, routes the transcript to one of four scenarios, chunks long text, validates, saves, and reports.
• Workers: A Benchmark Analyzer (hooks / structure / conversion / reusable formulas), B Insight Extractor (high-light insights / counter-intuitive points / business impact / hypotheses), C Sales Interview Analyzer (pain points / objections / turning points / product requirements / next steps), D Personal Review Organizer (cognitive assets / action items / links).
• Each record is stored three ways: .json (structured), .md (human-readable) and .html (self-contained page with an inline brand image and a one-line disclaimer above it). index.json plus 台账.md / 台账.html (ledger) are rebuilt on every save.
• Pure standard library, no third-party dependencies. Windows / macOS / Linux / HarmonyOS supported.

由「个人知识萃取」自动归档 · 瑆皓科技 · 提供技术支持