Knowledge-Base

结构化 Markdown 知识库管理协议。在知识库中新增、整理、搜索笔记和项目。匹配：在知识库中记笔记/归档/整理/搜索/创建项目/写日报/写周报/记录外部来源/沉淀概念或问题模型/知识库体检。当用户提到知识库操作、笔记管理、知识库健康检查时触发。默认推荐结构见正文，实际目录/命名/脚本等由 references...

Security Scan

The skill legitimately appears to implement a Markdown knowledge-base protocol, but it omits or under-specifies important runtime requirements (local filesystem paths, tools like node/git, and potential use of system credentials), so the footprint doesn’t fully match its metadata.

Purpose & Capability

Name/description and SKILL.md are coherent: instructions are a knowledge-base protocol for reading/updating Markdown notes and using a references/ configuration to adapt to a repository. However, the included reference (references/hansphere.md) defines an absolute local root (D:\HanSphere), git workflows, and a Node-based lint script — capabilities that reasonably belong to a KB skill but are not declared in the skill metadata (no required config paths, no required binaries).

Instruction Scope

SKILL.md stays on-topic (search, create, update, index, lint, archive notes). It explicitly instructs reading directory READMEs/templates, writing files (updating created/updated/front matter), running a lint script, and performing git commits/push. Those actions are within the KB purpose, but they involve filesystem modification and executing local commands; the instructions do not explicitly enumerate or constrain exactly which system paths or external endpoints will be used beyond references/, which raises scope/transparency concerns.

Install Mechanism

Instruction-only skill with no install spec or code files to execute on install — this reduces supply-chain risk. The risk surface comes from runtime actions (invoking node, git) rather than an installer.

Credentials

The skill metadata declares no required env vars or config paths, yet references/hansphere.md names an absolute local root (D:\HanSphere), a Node lint script (node D:\HanSphere\Notes\10-Operations\tools\wiki-lint.js), and git push usage. The skill therefore expects access to local filesystem paths and tools (node, git) and may use the system's git credentials or network access to push — none of which are declared. The mismatch between declared requirements (none) and actual runtime expectations is a proportionality/information problem and could lead to unintended data access or exfiltration if run without review.

Persistence & Privilege

always is false and the skill is user-invocable; it does not request persistent or system-wide privileges in metadata. It does instruct writing/updating files within the referenced KB root and performing git operations (expected for this purpose). No evidence it modifies other skills or global agent settings.

What to consider before installing

This skill appears to be a coherent protocol for managing a Markdown knowledge base, but before installing you should: (1) review references/hansphere.md (or whichever reference will be used) to confirm the exact filesystem root and paths the skill will read/write; (2) ensure you are comfortable with the agent running local commands (node, git) and potentially using your system git credentials to push; (3) verify the lint script (D:\HanSphere\Notes\10-Operations\tools\wiki-lint.js) and any templates — if present — to ensure they do not execute unexpected actions; (4) back up your knowledge repo and test the skill in an isolated environment or with a read-only copy first; and (5) if you expect the skill to run in a different environment, ask the skill author to declare required binaries (node, git), required config paths (NOTES_DIR or repo root), and any env vars so you can audit and control them. If these clarifications are provided, the concerns above should be resolved.

Knowledge-Base 知识库协议

结构化 Markdown 知识库的最小公共管理协议，通过 references/ 适配具体知识库。

本文档分为两层：

• 核心协议：所有知识库都应遵守的最小公共约定
• 推荐实践：默认最佳实现，可由 references 覆盖或替换

知识库根路径

由 references/ 配置文件定义。默认参考：references/hansphere.md

目录约定

默认推荐结构

默认推荐采用以下分层结构，具体路径和目录命名以 references 配置为准：

知识库根目录/
├── README.md              # 仓库总览
└── Notes/
    ├── 00-Inbox/          # 临时收集箱
    ├── 01-Daily/          # 日报/工作日志
    ├── 02-Sources/        # 外部来源
    │   └── Fulltext/      # 全文存档
    ├── 03-Concepts/       # 通用概念
    ├── 04-Issues/         # 问题模型
    ├── 05-Projects/       # 项目资料
    ├── 06-Architecture/   # 架构设计
    ├── 07-Patterns/       # 工作方法
    ├── 08-Reviews/        # 复盘总结
    ├── 09-Indexes/        # 索引导航
    ├── 10-Operations/     # 操作日志+体检
    ├── 98-Templates/      # 模板库
    └── 99-Archive/        # 归档区

各目录职责：

• Inbox → 临时收集，定期清理
• Daily → 当天事实记录
• Sources → 外部文章/资料（摘要+全文）
• Concepts → 可复用知识点
• Issues → 故障排查记录
• Projects → 项目资料（个人+公司统一管理）
• Architecture → 架构决策/ADR
• Patterns → 工作方法/SOP
• Reviews → 周报/月报/阶段复盘
• Indexes → 索引导航
• Operations → 操作日志+体检报告
• Templates → 笔记模板
• Archive → 长期归档

上述目录结构与职责为默认推荐映射，实际目录和职责边界以 references 配置为准。

执行流

轻量流

适用：Daily / Inbox / 已知文件更新 / 小修订

1. 判断目标文件
2. 套用已有模板/结构
3. 写入或更新
4. 回写 updated
5. 核心必检 6 项
6. 必要时补 ops

标准流

适用：新建 Issue/Concept/Pattern/Project / 归档/迁移 / 批量整理 / 建索引

1. 搜索防重复
2. 判断类型
3. 读取规则（首次进入该类型时读目录 README + 模板；同会话内沿用上下文）
4. 创建/更新
5. 补关联字段
6. 回写 updated
7. 追加 ops（按工作批次收口）
8. 判断索引更新（延迟触发）
9. 完整质量清单

规则上下文缓存

• 首次处理某类型笔记时，读取目录 README 和模板
• 同会话内同类型连续处理，沿用上下文，不重复读取

核心协议

以下规则适用于所有知识库：

1. 语义类型判定

新输入按以下语义角色判断类型（语义类型到实际目录的映射由 references 定义）：

语义角色	含义	默认目录
时序记录	当天/当期事实记录	Daily
临时收集	尚未分类的新输入	Inbox
来源资料	外部文章、书籍、课程	Sources
概念知识	可复用的原理/机制	Concepts
问题排查	具体故障的排查结论	Issues
项目资料	项目需求、设计、变更记录	Projects
决策设计	架构决策、技术选型	Architecture
方法流程	可复用的工作方法/SOP	Patterns
复盘总结	周期性归纳和回顾	Reviews
导航索引	专题汇总、快速跳转	Indexes

边界裁决：

• 问题排查 围绕"具体故障/排查结论"；概念知识 围绕"原理/机制"
• 外部文章即使和项目强相关，仍先进 Sources，再在 related 关联项目
• 临时收集 内容 7 天内必须归档或删除
• 时序记录 中出现可复用结论/排障闭环/架构决策/流程优化时，必须升格为长期笔记

2. 防重复搜索

新建长期知识类笔记前必须搜索同主题已有内容：

风险级别	语义类型	要求
长期知识类（必须搜索）	问题排查 / 概念知识 / 方法流程 / 项目正式文档	文件名 + 正文
中期资料类（推荐搜索）	来源资料 / 决策设计 / 复盘总结	文件名
临时记录类（可跳过）	时序记录 / 临时收集 / 已知更新	不强制

已有内容高度重合 → 更新旧文档，不新建。

3. 相对链接

• 知识库内部使用可点击的 Markdown 相对链接：[简短说明](相对路径)
• 禁止使用绝对本地路径

4. 更新回写

• 每次修改笔记必须回写 updated 字段为当天日期
• created 仅在首次创建时设置，后续不修改

5. 不写敏感信息

• 不写入密码、Token、API Key、基础设施私钥、客户隐私或商业机密

6. 核心必检 6 项

每次写入后检查：

• 路径符合类型判定规则
• 文件名符合命名约定（见 references）
• Front Matter 完整（id/title/type 必填）
• updated 已回写
• 不出现敏感信息
• 无明显重复（按搜索规则执行；可跳过类型无需强制搜索）

推荐实践

以下实践为默认最佳方案，可由 references 覆盖。

以下类型名（Source/Issue/Concept 等）采用默认实现命名，仅作为推荐实践示例。

命名约定

文件名应体现类型前缀 + 主题/描述 + 日期，确保可读且可排序。

具体命名格式见 references 配置。参考实现：

类型	HanSphere 格式
Daily	DAILY-YYYY-MM-DD.md
Source	SRC-Topic-YYYY-MM-DD.md
Concept	CONCEPT-Domain-Topic.md
Issue	ISSUE-System-Problem.md
Project	PRJ-Project-Name/
Pattern	PATTERN-Scenario.md
Review	YYYY-Www-WeeklyReview-MMDD-MMDD.md

Front Matter 标准字段

字段	说明
id	唯一标识，与文件名主干关联
title	与正文 H1 一致
type	笔记类型
status	当前状态
domain	领域
project	所属项目
tags	标签，推荐 3~7 个
related	关联笔记，数组格式
source	资料来源，数组格式
created	首次写入时间
updated	最后更新时间（每次修改必更新）
review_cycle	回顾周期（Source/Concept/Issue/Pattern 推荐）

原则：没有事实依据的字段宁可留空，不要猜。

related / source 默认规则：

• 默认实践中，来源资料 应提供 source 字段
• 默认实践中，问题排查 应尽量关联相关笔记；首次记录无关联对象可暂空，验证闭环前补齐
• 时序记录 / 孤立输入 允许都没有

生命周期

使用 status 字段管理笔记状态：

类型	状态流
Source	captured → processed → distilled → archived
Project	active → paused → archived
Issue	open → diagnosed → fixed → verified → archived
Concept	draft → stable

最小正文骨架

必须章节可简写，但不得省略核心信息。

类型	必须章节
Issue	现象、排查过程、根因、解决方案
Concept	定义、核心机制、相关链接
Source	来源信息、核心观点、关键事实、相关链接
Pattern	适用场景、执行步骤、参考资料
Architecture	背景、问题、方案、决策、相关链接
Review	本期目标、实际进展、关键问题、相关链接

建议章节（可选）见完整模板。

归档规则

archived 状态与物理移动到 Archive 目录是两个独立动作：

• 仅改状态：短期不再活跃
• 移动到 Archive：长期不再维护，须同时更新关联链接和索引

禁止只移动文件而不修复相关链接。归档后原路径保留简短说明 或 更新索引标注（二选一）。

索引生成

触发条件：某主题 ≥ 5 篇 / 项目跨多模块 / 问题链路涉及多类型文档。

延迟触发：仅明确新建索引/用户要求/批量操作时立即更新，其他场景延后统一处理。

操作日志

按工作批次收口，30 分钟内同主题多次修改合并为一条。仅记录有意义的知识动作（新建/结构调整/归档/体检等），不记录格式清理。

项目目录

项目目录应包含稳定入口文件（如 00-Index/INDEX.md），可按需要包含以下分层：Overview / Requirements / Architecture / Modules / Interfaces / Data / Environments / Issues / Change-Logs / Todos / Decisions / Reviews。

实际目录结构由 references 定义。

知识库体检

定期体检应覆盖：结构完整性、链接健康、命名规范、孤立页面、终端页面、报告输出。

具体评分权重和体检工具由 references 配置。

安全边界

不写入认证信息（密码、Token、API Key）、基础设施私钥、客户隐私或商业机密。敏感值使用占位符。

配置扩展机制

通过 references/<kb-name>.md 定义具体知识库的实现配置。reference 文件可定义以下维度：

维度	说明
根目录路径	知识库在文件系统中的位置
正文语言	笔记正文使用的自然语言
目录结构	实际目录路径、层级和职责映射
命名规范	各类型的具体文件名格式
字段默认值	各类型默认 status、review_cycle 等
操作日志路径和模板	ops 日志和体检日志的存储位置与格式
体检脚本路径	链接扫描等体检工具的执行命令
Git/版本控制约定	提交信息规范、同步流程
项目目录结构	项目内部的子目录层级和入口约定

当前配置：references/hansphere.md