By name: knowledgeguard description: | PROJECT KNOWLEDGE GOVERNANCE. Coordinates long-term project assets (Product, Architecture, Modules, Glossary, Patterns) using JIT (Just-In-Time) reading and progressive disclosure. Activates on slash commands (/knowledge-scan, /knowledge-refresh) or when the user discusses architectural constraints, codebase topology, business rules, or obscure project terms. license: MIT compatibility: opencode metadata: version: "1.0.0" author: "Lhy" tags: "knowledge-base, incremental-maintenance, architecture-topology, progressive-disclosure"
KnowledgeGuard v1.0.0 — 运行规范 (SOP)
1. 核心治理理念
- 渐进式披露 (Progressive Disclosure)：严禁贪婪地全量读取项目
knowledge/下的所有资产。必须根据当前任务的“物理边界”和“概念边界”，执行**即时（Just-In-Time）**的按需读取。 - 事实驱动 (Facts-Driven)：
knowledge/资产目录是项目现状的绝对现实镜像。它不记录“推测性方案”或“未落地的 ADR 提案”。代码变更完成，知识库即刻同步。 - 增量修补 (Incremental Patch)：严禁全量重写知识文件，所有自动化或隐式更新必须以
Markdown Patch（追加、定向修改节段）的形式进行，保护人类开发者手动沉淀的内容。
2. 知识库物理布局 (Project Knowledge Storage)
在执行任何知识写入时，必须在项目根目录的 knowledge/ 下维护以下 5 个事实资产文件：
knowledge/product.md— 解决“业务认知”：系统定位，核心业务领域规则。knowledge/architecture.md— 解决“技术约束”：当前真实采用的技术栈与组件通信。knowledge/modules.md— 解决“结构边界”：物理目录拓扑（最大细化到二级目录）。knowledge/glossary.md— 解决“消除歧义”：项目专属领域黑话与统一术语表。knowledge/patterns.md— 解决“代码方言”：团队固化的编码范式与设计模式。
3. L3 资产层调配规则：JIT 渐进式读取护栏
当本 Skill 被 L1 触发层激活后，你必须遵守以下最少必要读取原则，拒绝上下文过载：
| 当前任务场景 | 允许且仅允许加载的资产文件 | 读取深度与边界 |
|---|---|---|
| 执行编码/重构代码 | knowledge/modules.mdknowledge/patterns.md |
只读取与当前修改目录相关的上下级节点；只看当前语言的编码方言。 |
| 评审需求/设计业务逻辑 | knowledge/product.mdknowledge/glossary.md |
定向检索对应限界上下文（Bounded Context）的规则；通过关键词检索术语。 |
| 接入中间件/更换三方库 | knowledge/architecture.md |
只加载技术拓扑和全局约束部分。 |
🚫 硬性红线：禁止在单次会话启动时执行
cat knowledge/*.md。
4. 显式指令集工作流 (Command Specifications)
🔍 /knowledge-scan (全量认知基线构建)
- 评估项目根目录结构（过滤
target/,node_modules/,.git/）。 - 从本 Skill 挂载的本地资产路径（当前目录下的
assets/*_tpl.md，或系统缓存路径~/.cache/opencode/skills/knowledgeguard/assets/*_tpl.md）读取模板。 - 在项目根目录创建并初始化
knowledge/目录下的 5 个资产文件。 - 🚫 硬熔断红线 (Halt Rule)：一旦五个文件的物理写入（Write）完成，必须立刻终止 Thought 链条，向用户输出最终成果摘要。严禁使用任何
read、glob、ls或grep工具对刚刚写入的文件进行二次验证。本步骤豁免第 5 节的隐式自检流程。
🔄 /knowledge-refresh (显式物理结构同步)
- 针对
src/或物理核心目录执行文件树扫描。 - 比对当前的物理结构与
knowledge/modules.md中的旧描述。 - 发现新增目录或失效目录时，执行局部 Patch，并在回复中给出明细摘要。
5. 隐式增量更新与任务结束自检 (Session Self-Check)
⚠️ 绝对豁免条件：如果当前 Session 显式执行了 /knowledge-scan 指令，直接跳过本节所有自检项，执行第 4 节的硬熔断输出。
在日常的编码（Implement）与验证（Verify）阶段，你必须在回答结束或关闭 Session 的最后一个回合，强制执行以下自检。只有当你在本 Session 中使用过 bash/write/patch 工具对代码产生过物理位移时，才允许调阅 knowledge/ 文件进行增量修补：
- 物理目录发生涌现或消亡？ ➡️ 仅在发生了物理
mkdir/rmdir时，更新knowledge/modules.md。 - 涌现了新的项目专属黑话？ ➡️ 仅在代码/注释中出现新缩写时，Append 至
knowledge/glossary.md。 - 引入了新核心第三方库？ ➡️ 仅在修改了包管理配置文件（如 Cargo.toml/package.json）时，更新
knowledge/architecture.md。
6. 与运行状态库 (MemGuard) 的交互边界
- 涉及到“什么时候做”、“怎么分工”、“为什么放弃旧方案” ➡️ 移交
MemGuard的 ADR 与 Task 状态机。 - 涉及到“这是什么”、“目前物理代码在哪”、“业务规则怎么写” ➡️ 留存在
KnowledgeGuard资产库。