Shengjiang Knowledge

shengjiang-knowledge：系统知识库搭建、资料接入与健康检查

一句话定义

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

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

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

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

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

任务路由

用户同时提出搭建、导入资料和检查时，先审计现状，再初始化或补入口，然后接资料，最后保存一次健康状态。

工作边界

默认可以直接做

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

必须先让用户确认

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

默认不做

• 不安装向量数据库、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.资料库/
│   └── _资料索引.md
├── 02.输出区/
├── 03.项目档案/
├── skills/
└── system/
    ├── SOUL.md
    ├── USER.md
    ├── PROCEDURES.md
    ├── HEALTH.md
    ├── MEMORY_LOG.md
    ├── log.md
    └── state/

先运行预览：

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

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

如果用户明确要做自媒体、个人 IP 或内容生产，改用自媒体模板：

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

用户确认后再加 --apply。该模式在通用 Harness 上增加账号定位、对标调研、用户洞察、素材库、选题池、草稿、审核、定稿、待发布和发布复盘；完整路由见 references/creator-mode.md。

状态 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 追加记录。

自媒体工作台模式

完整规则见 references/creator-mode.md。

1. 先确认账号方向、目标人群、内容平台和主要产出形式；未知项标“待确认”，不编造定位。
2. 新库使用 --profile creator 预览；已有库不重建，先给目录映射和写入预览。
3. 对标原文、评论和逐字稿保留平台、作者、链接、抓取日期和原始路径。
4. 选题、草稿、定稿和已发布内容按状态流转，不复制多个“最终版”。
5. 发布后把平台、发布时间、标题、链接和真实数据写回发布复盘；没有数据就留空。
6. 批量导入对标资料、调整内容流程或积累一轮发布数据后，重新运行健康检查。

模式二：资料接入与结构化

完整规则见 references/material-intake.md。

1. 先建立只读资料清单

python3 scripts/scan_materials.py --source "<资料文件或目录>" --format markdown

脚本只登记路径、格式、大小和敏感文件风险，不复制、移动或修改文件。

2. 再读取代表内容

• 先读来源说明、目录、索引和少量代表文件，不把全部正文一次塞进上下文。
• PDF、Word、Excel、图片、录音和视频调用当前 Agent 已有的对应读取或转写能力。
• 敏感文件只登记路径和风险，禁止读取内容。
• 无法读取的格式标记“待转换”，不根据文件名编造摘要。

3. 区分四类知识

1. 原始事实：保留来源、日期和原始路径。
2. 外部观点：可以研究和引用，但不写成用户立场。
3. 用户判断：必须有用户明确表达或真实业务验证。
4. 程序经验：反复发生且可验收后，升级到 PROCEDURES.md 或 Skill。

4. 生成接入预览

| 原始资料 | 来源 / 所有者 | 建议归属 | 准备新建或更新 | 原件处理 | 依据 |
| --- | --- | --- | --- | --- | --- |

默认落位：

• 待判断输入 → 00.收件箱/
• 可长期复用的原始资料、案例和参考 → 01.资料库/
• 文案、报告、方案和交付物 → 02.输出区/
• 真实项目的输入、决策、交付和复盘 → 03.项目档案/
• 可重复流程 → skills/ 或 system/PROCEDURES.md

用户确认后再写入。完成后更新 01.资料库/_资料索引.md、相关局部索引和 system/log.md；只有新增高频入口时才改根 INDEX.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. 是否存在大量根级散落文件、重复文件名或悬空引用；
10. system/MEMORY_LOG.md 中是否有同类纠正已达 3 次却还没升级为固定规则。

用户确认保存本次状态后运行：

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

这会写入：

• system/state/YYYY-MM-DD-知识库健康检查.md
• system/state/latest-health.json

每次会话读取最近状态；超过 7 天未检查时提醒一次。批量接入资料、修改入口或搬迁主要目录后立即复查。完整周期见 references/health-cycle.md。

巡检报告格式

# 知识库自检

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

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

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

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

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

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

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

模式四：修复

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

内置能力：自我纠错循环

这套知识库自带“从纠正中学习”的机制，不需要额外安装记忆或自我改进 Skill。它不是让模型凭空拥有永久记忆，而是把教训写进每次都会读取的文件。

1. 用户纠正输出或判断，或明确说“记住这个教训”“别再犯”时，立刻按 system/MEMORY_LOG.md 的格式追加一条。
2. 写清场景、用户纠正、后续行动，并标注“该类纠正第 N 次”。判断同类看错误模式，不看字面是否相同。
3. 同类纠正达到 3 次，主动提议升级到 system/PROCEDURES.md。升级必须让用户确认，不能自动改长期规则。
4. 重要任务开始前，先读取 MEMORY_LOG.md 最近的纠正；升级后的 PROCEDURES.md 随入口加载。
5. 不记录密钥、隐私和敏感内容，只记录错误模式与正确做法；记录默认只增不改。

完成标准

搭建完成

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

资料接入完成

• 每批资料有来源、所有权、日期、状态和原始路径；
• 外部观点、用户判断和业务事实没有混写；
• 原件只有一个事实源；
• 01.资料库/_资料索引.md 与局部导航已更新；
• 无法读取和待确认项明确保留。

健康检查完成

• 检查范围明确；
• 每个问题都有路径和证据；
• 模板示例与真实断链已区分；
• 风险按 P0 / P1 / P2 排序；
• 最新状态保存到 system/state/（用户要求保存时）；
• 未经确认没有移动、覆盖或删除文件。

首次交付后的使用引导

根据真实目录生成 4 个能直接复制的例子，覆盖“接资料、找资料、做产出、健康检查”：

1. 从知识库找一下与 {真实主题} 有关的资料，并告诉我依据文件。
2. 读取这批 {真实资料类型}，区分外部观点和我的判断，先给接入预览。
3. 根据知识库里的 {真实业务资料}，帮我完成 {真实产出}。
4. 检查知识库健康状态，保存报告但不要自动修复。

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

与其他任务的边界

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

需要更完整的结构解释时读 references/architecture.md；接入资料前读 references/material-intake.md；执行巡检前读 references/audit-rules.md 和 references/health-cycle.md。 搭建或维护自媒体知识库时必须读 references/creator-mode.md。