Ysj knowledge

ysj-knowledge：知识库搭建与自检

一句话定义

把用户已有的文件夹变成 AI 能稳定工作的知识库：有输入归口、有执行约束、有原始事实、有业务输出，也有反馈检查和经验写回；并让这套知识库自己暴露断链、冲突和维护风险。

这里的知识库不是“把文件放整齐”，而是一套能运行、能反馈、能进化的 Harness：

录音、笔记、网页、对话和项目资料有固定归口
  → Guides 约束：入口、用户画像、人格、规则、导航和 Skill
  → Model 执行：读取原始资料、判断、执行并产出
  → 业务输出：内容、课程、项目交付或企业服务
  → Sensors 反馈：启动自检、输出自检、纠正捕获、知识库巡检
  → 经验写回规则和 Skill，下一次执行更稳

导航只负责指路。回答问题时继续读取原始文件，不把索引摘要当成事实本身。

当前版本直接负责本地知识库的 Harness Core、导航、事实源和 Sensors。外部工具自动同步、向量数据库、云端 RAG 和具体业务输出系统属于独立接入或下游能力，不在本 Skill 中冒充现成功能。

任务路由

用户意图	模式
从零搭建、把文件夹变成知识库	搭建
已经有很多资料，希望 AI 能找到和使用	接入
检查断链、冲突、入口、目录健康度	自检
修复巡检发现的问题	修复（先确认后写入）

用户同时提出搭建和自检时，先审计现状，再搭建，最后跑一次自检验收。

工作边界

默认可以直接做

• 只读扫描用户指定的目录。
• 读取根级、主要目录入口和完成任务所需的原始文件。
• 运行 scripts/audit_knowledge_base.py 做确定性检查。
• 输出搭建方案、修改预览和巡检报告。

必须先让用户确认

• 创建或修改文件。
• 复制、移动、重命名或归档资料。
• 改写 AGENT.md、AGENTS.md、CLAUDE.md 等入口规则。
• 指定某个冲突文件为当前有效版本。

默认不做

• 不安装向量数据库、Embedding 服务或云端 RAG。
• 不上传用户资料到第三方平台。
• 不覆盖、删除或批量搬家。
• 不根据文件名猜正文内容或权威性。
• 不读取 .env、密钥、Cookie、浏览器数据、聊天数据库和密码文件。
• 不为了“看起来完整”预建大量空目录。

第一步：确定根目录

按顺序判断：

1. 用户给出明确路径：使用该路径。
2. 用户说“这个文件夹”，且当前工作目录边界清楚：使用当前目录。
3. 当前目录是用户主目录、磁盘根目录、下载目录或包含多个无关项目：请用户缩小范围。
4. 目录尚不存在：只询问会改变真实路径的最小信息，例如名称和保存位置。

使用规范化绝对路径。Skill 自己的安装目录不是用户知识库。

第二步：只读审计

先看根级和 1～2 层目录，不要一上来读取全部正文。

优先检查：

• AGENT.md、AGENTS.md、CLAUDE.md
• INDEX.md、根级和主要目录中的 README.md
• system/SOUL.md、system/USER.md、system/PROCEDURES.md
• _本周.md 或其他当前工作文件
• system/log.md、system/MEMORY_LOG.md、system/state/
• 文件名中带日期、版本、最终版、最新版、原始、汇总、归档的文件

默认排除：

• .git/、node_modules/、缓存、构建产物和依赖目录
• 回收站、明确归档区和历史备份
• 密钥、凭证、Cookie、浏览器数据和聊天数据库
• 与当前任务无关的大型二进制文件；只登记类型、大小和路径

审计时回答六个问题：

1. 这个知识库主要服务什么工作？
2. 用户当前最重要的事情是什么？
3. 哪些目录是输入、输出、业务资产和项目档案？
4. 哪些文件是候选事实源？依据是什么？
5. Agent 从哪里启动，怎样找到原始资料？
6. 哪些冲突或缺口必须让用户确认？

证据不足时写“待确认”，不要替用户宣布权威版本。

第三步：识别状态

状态 A：空目录或资料很少

使用最小模板，不预建复杂业务树：

知识库根目录/
├── AGENT.md
├── AGENTS.md
├── CLAUDE.md
├── INDEX.md
├── _本周.md
├── 00.收件箱/
├── 01.资料库/
├── 02.输出区/
├── skills/
└── system/
    ├── SOUL.md
    ├── USER.md
    ├── PROCEDURES.md
    ├── MEMORY_LOG.md
    ├── log.md
    └── state/

先运行预览：

python3 scripts/init_knowledge_base.py --root "<绝对路径>" --name "<知识库名称>"

用户确认后再加 --apply。初始化脚本不会覆盖已有文件。

状态 B：已有资料，但没有稳定入口

保留现有结构，先给出：

1. 资料领域和主要目录；
2. 候选事实源与版本冲突；
3. 建议新增或补充的入口文件；
4. INDEX.md 准备登记的快速查找项；
5. 明确不会移动的原始资料。

用户确认后补入口和导航。只有目录职责确实混乱且用户同意时才搬文件。

状态 C：已有入口和导航

直接进入自检。不要为了套模板重建一遍成熟知识库。

模式一：搭建知识库

1. 先建立最小上下文

从用户现有资料和对话中提取：

• USER.md：用户是谁、在做什么、偏好和目标；
• SOUL.md：AI 应该怎样协作和表达；
• PROCEDURES.md：反复发生的“遇到 X 就做 Y”；
• _本周.md：当前 1～3 件最重要的事。

缺什么只问什么。不要为了填满模板编造信息。

2. 再建立导航

INDEX.md 至少说明：

• 核心入口分别做什么；
• 主要目录放什么；
• 高频任务先去哪里找；
• 多个版本冲突时遵循什么规则；
• 哪些目录默认不读取。

不要逐文件登记。大量同类文件登记主目录、局部索引或命名规则即可。

3. 建立入口调用链

• AGENT.md / AGENTS.md 保持镜像一致，写启动顺序和全局红线。
• CLAUDE.md 做薄入口，导入 AGENT.md 或提供等价启动规则。
• 入口只负责“先读什么、什么时候查库”，不复制整份知识库内容。
• 修改任一入口后，检查镜像、引用路径和启动文件是否真实存在。

4. 写入前给预览

使用这个格式：

准备修改：

| 路径 | 动作 | 为什么 | 是否保留原件 |
| --- | --- | --- | --- |
| `{真实路径}` | 新建 / 补充 / 移动 | {原因} | 是 / 不涉及 |

不会做：{本轮明确排除的动作}

用户确认后再执行同一组动作。新增事实、规则或结构后，在 system/log.md 追加记录。

模式二：知识库自检

先运行只读脚本：

python3 scripts/audit_knowledge_base.py --root "<绝对路径>" --format markdown

脚本结果只是线索。对 P0、P1 项继续读取相关入口或原始文件，排除模板示例、故意保留的历史版本和合法的嵌套项目。

详细判断标准见 references/audit-rules.md。重点检查：

1. 启动入口和核心文件是否存在；
2. AGENT.md / AGENTS.md 是否一致；
3. INDEX.md 和入口中的本地路径是否有效；
4. 主要目录是否进入导航；
5. 是否出现多个“最终版 / 最新版”却没有版本规则；
6. 00.收件箱/ 是否长期积压；
7. 当前工作文件是否长期不更新；
8. 是否混入敏感文件、依赖目录、缓存或构建产物；
9. 是否存在大量根级散落文件、重复文件名或悬空引用。

巡检报告格式

# 知识库自检

## 结论
{一句话说明当前能不能稳定使用}

## 立即处理（P0）
- `{路径}`：{风险、证据、建议}

## 建议处理（P1）
- `{路径}`：{问题、影响、建议}

## 保持现状（P2）
- {哪些结构虽然不整齐，但有明确用途，不要乱动}

## 修复预览
| 路径 | 建议动作 | 是否需要用户确认 |
| --- | --- | --- |

## 本次检查范围与缺口
{检查了什么；哪些内容没有读取；哪些判断仍待确认}

没有某一优先级的问题就省略该节。不要为了显得专业硬凑问题。

模式三：修复

1. 把巡检项分成“可确定修复”和“需要业务判断”。
2. 先处理会让 Agent 读错的入口、断链和版本冲突。
3. 给出精确到路径的修改预览。
4. 用户确认后执行；不扩大到未确认的问题。
5. 修复后重新运行巡检，证明问题已经消失。
6. 在 system/log.md 记录本次修复；用户纠正了判断时，写入 system/MEMORY_LOG.md。

完成标准

搭建完成

• 根目录明确；
• Agent 有可用入口；
• 人格、用户、规则、导航和当前工作能按顺序加载；
• 导航中的路径经过存在性检查；
• 用户知道怎样放资料、怎样提问、怎样发起自检。

自检完成

• 检查范围明确；
• 每个问题都有路径和证据；
• 模板示例与真实断链已区分；
• 风险按 P0 / P1 / P2 排序；
• 未经确认没有移动、覆盖或删除文件。

首次交付后的使用引导

根据真实目录生成 3～4 个能直接复制的例子，至少覆盖“放资料、找资料、做产出、自检”中的三类：

1. 从知识库找一下与 {真实主题} 有关的资料，并告诉我依据文件。
2. 把这份 {真实资料类型} 放进知识库，先告诉我准备放哪。
3. 根据知识库里的 {真实业务资料}，帮我完成 {真实产出}。
4. 检查一下知识库有没有断链、版本冲突或长期未处理资料。

例子必须来自本次扫描到的真实内容，不写“某文件”“某业务”这类空话。

与其他任务的边界

• 普通知识库搭建与自检：留在 ysj-knowledge。
• 大规模内容原子化、主题地图和选题装配：交给内容系统 Skill。
• 多 Agent 平台迁移与桥接：交给 Agent 工作台迁移 Skill。
• 飞书、Notion、向量库或企业权限系统：作为后续独立集成，不塞进首版。

需要更完整的结构解释时读 references/architecture.md；执行巡检前读 references/audit-rules.md。