| name | PKM |
| description | 当用户显示的使用 @pkm /pkm 时，或者想要"整理知识"、"管理笔记"、"捕获想法"、"归档项目"、"组织 PARA"、"知识提炼"、"整理知识库"、"任务管理"、"项目开发"、"项目归档"时，应使用此技能。 |
Skill: PKM (Personal Knowledge Management)
统一的知识管理入口，基于 PARA（Projects/Areas/Resources/Archives）和 CODE（Capture/Organize/Distill/Express）方法论。
本文档内容以 docs/ARCHITECTURE.md 架构设计为准，与之冲突时以架构文档为准。
自动定位知识库
AI 自动执行：每次调用 PKM Skill 时，会自动从配置文件读取知识库位置。
CONFIG_FILE="${HOME}/.pkm/.config"
if [ -f "$CONFIG_FILE" ]; then
DATA_HOME=$(grep "^DATA_HOME=" "$CONFIG_FILE" 2>/dev/null | cut -d'=' -f2 | tr -d '"' | tr -d "'")
CURSOR_HOME=$(grep "^CURSOR_HOME=" "$CONFIG_FILE" 2>/dev/null | cut -d'=' -f2 | tr -d '"' | tr -d "'")
CLAUDE_HOME=$(grep "^CLAUDE_HOME=" "$CONFIG_FILE" 2>/dev/null | cut -d'=' -f2 | tr -d '"' | tr -d "'")
GEMINI_HOME=$(grep "^GEMINI_HOME=" "$CONFIG_FILE" 2>/dev/null | cut -d'=' -f2 | tr -d '"' | tr -d "'")
OPENCLAW_HOME=$(grep "^OPENCLAW_HOME=" "$CONFIG_FILE" 2>/dev/null | cut -d'=' -f2 | tr -d '"' | tr -d "'")
fi
PKM_HOME="${PKM_HOME:-${HOME}/.pkm}"
DATA_HOME="${DATA_HOME:-${HOME}/.pkm/data}"
配置文件位置：~/.pkm/.config（安装后由 .config.template 复制为 .config 并按需修改）
知识库位置：配置文件中 DATA_HOME 指定的目录（默认为 ~/.pkm/data），即 PARA 的 10_50 目录所在根。
PKM 根目录：DATA_HOME 的上级目录（如 DATA_HOME=/home/user/.pkm/data 则根目录为 /home/user/.pkm）。skill 代码位于 ~/.pkm/skill/，不在 data 下。
快速开始
最简单的用法
@pkm
我会自动判断当前需要执行的操作：
- ✅ 检查知识库结构（Verify）
- 🗄️ 若有已完成任务 → 调用
@pkm task archive 执行归档回流（Archive）
- 📦 如果 50_Raw/ 有文件 → 自动组织分类（Organize）
- 💎 如果 20_Areas/knowledge/03notes/ 有新增/变动 → 自动提炼（Distill）
查看帮助
@pkm help
显示完整的命令列表和使用说明。
命令列表
一键整理知识
@pkm
一键全自动处理，系统智能整理和提炼知识，无需人工干预。
自动顺序执行（不推荐单独使用）：
@pkm verify - 自动检查知识库结构完整性（5 个顶级目录：10_Tasks、20_Areas、30_Resources、40_Archives、50_Raw）- 主流程中的 Archive - 调用
@pkm task archive 自动扫描所有任务工作空间，归档含 completed.md 的已完成任务（知识回流到 20_Areas/knowledge/ 与 20_Areas/Projects/，任务移至 40_Archives/）
@pkm organize - 自动分类整理 50_Raw/ 中的待处理内容@pkm distill - 自动提炼 20_Areas/knowledge/03notes/ 中的知识
适用场景：
- ✅ 每天结束前执行一次，自动整理当天积累的知识
- ✅ 任务完成后，自动归档并回流知识
- ✅ 定期维护，保持知识库整洁有序
快速捕获
@pkm inbox <内容> # 快速捕获，默认不解析链接内容
@pkm inbox --parse <内容> # 先解析链接内容，再捕获
智能咨询
@pkm advice <问题> # 默认模式（common + local）
@pkm advice --scope <范围> <问题> # 指定范围模式
scope 值：
- common # 仅 AI 通用知识
- local # 仅当前知识库
- task # 指定任务知识库
- 默认：common + local（可叠加）
任务管理
@pkm task add <内容> # 添加新任务，创建任务区（交互式补全：想法、4象限、计划完成时间、工作量）
@pkm task ls # 列出所有任务（按计划完成时间排序，含延期风险提示）
@pkm task ls --all # 列出所有任务（含已归档）
@pkm task use <id> # 切换到指定任务，加载任务区信息
@pkm task edit <id> # 编辑任务
@pkm task update <id> # 更新任务进展
@pkm task done <id> # 完成任务，总结任务清单
@pkm task delete <id> # 删除任务
@pkm task archive # 自动扫描含 completed.md 的任务并归档，回流知识到知识库
任务字段：状态、ID、标题、工作空间路径、4象限、计划完成时间、工作量
长期项目管理
@pkm project add <名称> # 在 20_Areas/Projects/ 添加新的长期项目
@pkm project delete <project_name> # 删除项目
@pkm project ls # 列出所有长期项目
PKM 自管理
@pkm status # 查看 PKM 状态（配置、知识库概况、项目/任务列表、版本、上次总结报告简述）
@pkm upgrade # 更新 PKM（在 ~/.pkm 执行 git pull）
帮助与信息
@pkm help # 显示帮助信息
工作流程
1. 前置验证（自动执行）
调用 _Verifier 模块：
- ✅ 定位知识库目录：
${DATA_HOME}
- ✅ 检查
${DATA_HOME} 中 5 个顶级目录（10_Tasks/、20_Areas/、30_Resources/、40_Archives/、50_Raw/）是否存在且结构完整
- ✅ 确认操作范围白名单（限定在知识库目录内）
- ✅ 生成写权限白名单（manual/ 只读）
- 缺失目录则自动创建，然后继续
2. 命令路由
根据命令参数路由到相应模块：
一键整理知识（无参数）：
- 执行
@pkm：主流程 Verify → Archive → Organize → Distill
- 其中 Archive 阶段 = 调用
@pkm task archive（由 _TaskManager 执行，归档已完成任务并回流知识）
- 对应可单独调用的子步骤：
@pkm verify、@pkm organize、@pkm distill；任务归档通过 @pkm task archive 执行（自动扫描含 completed.md 的任务）
手动命令（带参数）：
inbox <内容> → _Verifier → _Inbox（快速捕获）inbox --parse <内容> → _Verifier → _Inbox（先解析链接再捕获）advice <问题> → _Verifier → _Advisor（默认模式：common + local）advice --scope <范围> <问题> → _Verifier → _Advisor（指定范围）task <操作> → _Verifier → _TaskManager（任务管理）project <操作> → _Verifier → _ProjectManager（长期项目管理）organize → _Verifier → _Organizer（组织分类）distill → _Verifier → _Distiller（提炼知识）verify → _Verifier（仅验证）status → _Verifier → _PkmSelfManager（查看状态）upgrade → _PkmSelfManager（更新版本）help → _Help（显示帮助信息）
3. 执行与报告
执行相应操作，生成统一格式的报告。
内部模块说明
PKM 由 9 个内部模块组成，每个模块负责知识管理的一个环节（与 ARCHITECTURE 5.1 / 5.2 一致）：
| 模块 | 职责 | 对应阶段 | 触发方式 |
|---|
_Verifier | 范围守卫，验证结构（5 个顶级目录、操作范围、写权限白名单） | 前置检查 | 自动（每次操作前） |
_Inbox | 快速捕获器 | Capture | @pkm inbox |
_Advisor | 智能顾问 | Express | @pkm advice |
_Organizer | 智能组织器 | Organize | @pkm organize 或主流程 |
_Distiller | 知识提炼器 | Distill | @pkm distill 或主流程 |
_ProjectManager | 长期项目管理器 | 支撑 | @pkm project（add/delete/ls） |
_TaskManager | 任务管理器 | 支撑 | @pkm task（含 archive 归档回流） |
_Help | 帮助信息 | 支撑 | @pkm help |
_PkmSelfManager | 自管理器 | 支撑 | @pkm status / @pkm upgrade |
📋 _Verifier（范围守卫）
职责：验证知识库结构，缺失目录则自动创建，生成操作白名单
触发：每次操作前自动执行
检查范围：${DATA_HOME} 下 5 个顶级目录（10_Tasks/、20_Areas/、30_Resources/、40_Archives/、50_Raw/）存在且结构完整；不包含 skill（skill 位于 PKM 根目录）。
详细文档：_Verifier.md
📥 _Inbox（快速捕获器）
职责：快速捕获信息到 Inbox，降低记录门槛
对应阶段：CODE 的 Capture（捕获）
触发：
- 手动调用：
@pkm inbox <内容>
- 解析链接后捕获：
@pkm inbox --parse <内容>
前置要求：
- ⚠️ 必须先调用
_Verifier 验证环境
- 确认
50_Raw/inbox/ 存在且可写
核心功能：
- 快速保存文本、想法、链接到
50_Raw/inbox/
- AI 生成文件名（简单总结内容，5-10 字标题）
- 智能处理链接（默认仅引用，
--parse 模式先解析链接内容再捕获）
- 保存格式：
YYYYMMDD_HHMMSS_标题_inbox.md
详细文档：_Inbox.md
🤔 _Advisor（智能顾问）
职责：提供决策支持和知识咨询
对应阶段：辅助所有阶段的决策
触发：
- 默认模式：
@pkm advice <问题>（等价于 --scope common,local）
- 指定范围：
@pkm advice --scope <范围> <问题>
--scope common：仅 AI 通用知识--scope local：仅当前知识库--scope task 或 --scope <任务名>：仅指定任务知识库--scope common,local：AI 通用知识 + 当前知识库（默认）--scope local,任务名：当前知识库 + 指定任务知识库
前置要求：⚠️ 必须先调用 _Verifier 验证环境
核心功能：根据 scope 检索知识库，结合 AI 通用知识回答问题，提供分类建议（如笔记应放目录）。
详细文档：_Advisor.md
📦 _Organizer（智能组织器）
职责：处理 50_Raw/ 中的未分类内容，合并同类内容，分类归位到 PARA 体系
对应阶段：CODE 的 Organize
触发：主流程中有待处理内容时自动执行，或手动调用 @pkm organize
核心功能：
- 扫描
50_Raw/（包含 inbox/ 和其他待分类素材）
- 可选插件预处理：若存在
skill/plugin/SKILL.md，先按内容类型匹配插件，命中则用对应 template_<类型>.md 模版整理，再继续分类
- 按主题/类型合并同类内容到
50_Raw/merged/
- 判断类型（项目/知识/资料）和主题，分类归位：
- 项目 →
20_Areas/Projects/<项目名称>（仅当有关联项目时）
- 知识 →
20_Areas/knowledge/03notes/<领域>/（先放在 notes 层）
- 资料 →
30_Resources/Library/
- 整理完清理已分类的文件，清空
50_Raw/
详细文档：_Organizer.md
💎 _Distiller（知识提炼器）
职责：将 20_Areas/knowledge/03notes/ 中的零散知识按金字塔原理提炼成结构化知识
对应阶段：CODE 的 Distill
触发：主流程中有新增/变动时自动执行，或手动调用 @pkm distill
核心功能：
- 扫描
20_Areas/knowledge/03notes/ 各领域目录
- 与已有知识深度整合（去重、交叉引用、结构化）
- 按金字塔原理提炼：零散知识（notes）+ 20_Areas/manual（只读）→ 整理知识 → 应用知识（knowledge/02playbooks/02templates/02cases）→ 原则知识（knowledge/01principles）
- 沉淀到对应目录；系统性检查（一致性、过时性、冗余、逻辑合理性）
- 总结提炼结果，生成报告到
30_Resources/summary/，格式 YYYYMMDD_HHMMSS_标题_Distill.md
- 整理 Project 区内容：扫描
20_Areas/Projects/ 下所有项目，对每个项目内文件检查重复、冗余、一致性等问题，并进行整理（与方案 4.2 一致；规模过大时一次最多处理 20 个文件）
详细文档：_Distiller.md
📁 _ProjectManager（项目管理器）
职责：管理 20_Areas/Projects/ 下的长期项目（添加、删除、列表）
对应阶段：支撑任务与知识沉淀的长期项目容器
触发：@pkm project add、@pkm project delete、@pkm project ls
核心功能：
- 在 20_Areas/Projects/ 下添加新长期项目、删除项目、列出所有长期项目
- 项目目录格式可为
01_xxx 等（以宪章 2.4 为准）
详细文档：_ProjectManager.md
📋 _Help（帮助信息）
职责：显示完整帮助信息，包括所有命令列表、使用示例、数据存储路径等
触发：@pkm help
详细文档：_Help.md
📋 _TaskManager（任务管理器）
职责：管理任务，支持 4 象限管理；add/ls/use/edit/update/done/delete/archive；任务工作空间 10_Tasks/TASK_WORKSPACE_YYYYMMDD_HHMMSS_xxx/，任务数据 task.md；archive 时回流知识到 20_Areas/knowledge/ 与 20_Areas/Projects/
触发：@pkm task <子命令>
详细文档：_TaskManager.md
🔧 _PkmSelfManager（自管理器）
职责：查看 PKM 运行状态、更新 PKM 项目
触发：@pkm status、@pkm upgrade
status：输出配置文件（~/.pkm/.config）、数据目录位置、知识库数量概况、长期项目列表（引用 @pkm project ls）、任务列表（引用 @pkm task ls 与 @pkm task ls --all）、PKM 版本、上次 pkm 执行时间、上次 pkm 总结报告简述（不超过 100 字）。
upgrade：在 PKM 安装目录（默认 ~/.pkm）执行 git pull，更新 skill 与 command。
详细文档：_PkmSelfManager.md
使用示例
场景 1：日常工作流（完全自动）
# 每天结束前
@pkm
# 输出示例：
✅ Verifier 验证通过
🗄️ 检测到已完成任务
🔄 执行 @pkm task archive（TaskManager）...
└─ 知识回流到 20_Areas/knowledge/ 与 20_Areas/Projects/，任务移至 40_Archives/ ✅
📦 检测到 50_Raw/ 有 8 个文件
🔄 执行 Organizer...
├─ 合并同类内容到 50_Raw/merged/
├─ 知识 → 20_Areas/knowledge/03notes: 5 个
└─ 50_Raw/ 已清空 ✅
💎 检测到 20_Areas/knowledge/03notes/01_react/ 有新增
🔄 执行 Distiller...
└─ 报告 → 30_Resources/summary/YYYYMMDD_HHMMSS_知识提炼报告_Distill.md ✅
🎉 完成！主流程执行完毕。
场景 2：只组织分类 50_Raw/
@pkm organize
场景 3：只提炼知识
@pkm distill
场景 4：查看帮助
@pkm help
安全机制
双重防火墙
-
内部防火墙：受保护区 vs AI 可写区
- AI 可写：
20_Areas/knowledge/（03notes、02playbooks、02templates、02cases、01principles）、10_Tasks/、20_Areas/Projects/、50_Raw/、30_Resources/Library/、40_Archives/
- AI 只读：
20_Areas/manual/，绝不直接修改
-
外部防火墙：知识库内 vs 知识库外
- Verifier 强制检查目录结构，操作仅限
${DATA_HOME} 内
- 禁止操作知识库外路径
白名单机制
可写区域（AI 可以创建/修改/删除文件）：
50_Raw/、10_Tasks/（任务工作空间）、20_Areas/knowledge/（03notes、02playbooks、02templates、02cases、01principles）、20_Areas/Projects/、30_Resources/Library/、40_Archives/
只读区域：20_Areas/manual/、skill/
禁止区域：知识库根目录（DATA_HOME）外的任何路径
核心原则
- 自动化优先：能自动处理的不要人工干预
- 安全至上：先验证后操作，永不越界
- 人类决策：AI 提建议，人类做决策
- 渐进式：从简单到复杂，从手动到自动
- 可追溯：所有操作都有日志和报告
故障排查
问题：提示「知识库结构不完整」
说明：Verifier 会自动创建缺失的 5 个顶级目录，通常不会出现此提示。若仍出现，多为 DATA_HOME 路径不可写或不存在。
解决：确认 ~/.pkm/.config 中 DATA_HOME 指向的目录存在且可写；或手动创建 DATA_HOME 目录后再执行 @pkm。
问题：文件被标记为「待确认」
原因：Organizer 无法判断文件类型。
解决：人工判断类型后，将文件移动到正确位置（如 20_Areas/knowledge/03notes/<领域>/ 或 30_Resources/Library/）。
问题：草稿质量差
原因：原子块质量参差不齐。
解决：可手动编写到 20_Areas/manual/（受保护区），或重新收集高质量片段到 50_Raw/inbox/。
高级配置
手动执行单个步骤
若只想执行部分操作，可单独调用：
@pkm organize # 只执行组织分类（处理 50_Raw/）
@pkm distill # 只执行提炼（处理 20_Areas/03notes/）
@pkm task archive # 归档所有已完成任务（扫描含 completed.md 的，回流知识并搬运到 40_Archives/）
@pkm verify # 只验证知识库结构
反馈与支持
若使用中遇到问题：
- 执行
@pkm help 查看命令列表
- 查阅具体模块文档（
_Verifier.md、_Inbox.md 等）
- 对照架构设计：
docs/ARCHITECTURE.md
祝你的知识管理之旅愉快！
