# Knowledge Workflow 安装使用

本文对应 **0.2.0 试用版，Windows + Codex**。这套工作流负责把指定材料保存为可查询的知识，并在新证据出现后维护相关说明。

[下载工作流 ZIP](https://yzh0013.cloud/downloads/knowledge-workflow/knowledge-workflow-0.2.0.zip) · [文件校验](https://yzh0013.cloud/downloads/knowledge-workflow/knowledge-workflow-0.2.0.sha256.txt)

## 安装

需要 Codex、PowerShell 7.2 或更新版本、Git。Codex 必须能执行命令并写入你选择的目录。工作流不自动安装这些依赖。

1. 下载 ZIP，自己解压。
2. 在解压目录运行 `codex`，或用 Codex 桌面端打开该目录。
3. 告诉 Codex：

```text
安装这个知识库工作流。
```

首次安装会在你发起安装的当前目录创建 `Knowledge`，注册当前用户的调用入口，并记住这个目录。应收到实际知识库位置、版本和检查结果；只看到“准备安装”还不算完成。

已有默认库时，重复安装会复用它。未指定其他位置时，换一个代码项目不会新建第二个 Knowledge。

安装后可以在自己的工作项目中继续使用。若当前会话还没有识别新入口，新开会话即可，不必切到 Knowledge，也不必手工修改每个项目的 AGENTS.md。目录绑定负责定位，实际读写仍按当前 Codex 会话的权限执行。

需要明确指定初始位置，可以说：

```text
把这个知识库工作流安装到 D:\TeamKnowledge，保留已有笔记和个人配置。
```

第一次安装时该位置会成为默认库。已有默认库时，另装一个库不会自动取代原默认；如果要长期换用，请明确说“以后默认使用”。

## 第一次体验

建议直接拿一段最近做完的工作材料。安装后新开会话，像平时说话一样提出请求：

```text
把这次工作结果保存到知识库，项目是 MyApp，留给以后查询。
下面是现象、关键材料、已经做的处理和实际验证结果：
……替换成你的材料……
只记录这些材料能支持的结论，不补写没有做过的测试。
```

不用先学习目录结构，也不用填写整份模板。完成后看三件事：结论是否符合材料、原始依据是否保留、下次从哪里查得到。

再开一个会话试着查询：

```text
从知识库查一下 MyApp：以前有没有类似的问题？当时怎样处理，适用于什么条件？
给出用到的笔记和依据，这次只查询，不修改文件。
```

还没有合适材料时，可以先看[平时怎么用](https://yzh0013.cloud/projects/knowledge-workflow/usage/)中的短例子。技术教学案例和验证原稿是可选资料；首次安装和日常整理不需要 Python。

## 日常用法

### 保存排查或开发结果

> 把这次排查保存到知识库。项目是 PAY-API，下面是现象、关键日志、实际修改和测试结果：……

提供真实做过的事情即可。材料不齐时可以保存分析，Codex 应注明未知，不能补齐不存在的源码、实验或交付结果。

### 保存学习笔记

> 把这份资料整理成可查询的学习笔记，主题是……。来源和版本是……。以下是原文摘记和我的理解，没有本地实验。

学习笔记可以独立存在，不需要制造一条故障记录。资料给出的解释与自己设备上的验证应分清。

### 查询以前的经验

> 从知识库查一下，以前这个问题怎样处理？给出当时的版本、条件和依据，不修改文件。

不用每次输入 `$knowledge-workflow`；明确表达查知识、保存或修订的意图即可，显式调用仍可使用。普通聊天和开发任务不会因此自动写入知识库。

历史记录说明当时保存过什么。它是否适用于现在的源码、设备和版本，仍需核对当前对象。

### 新材料出现后修订

> 这份新资料改变了之前的判断。更新相关笔记，并检查直接依赖它的操作说明；只处理这次资料影响的内容。

旧记录保留当时的日期和适用范围。独立问题另记，相关说明指向当前结论，避免多个入口重复维护同一事实。

## 默认目录与临时指定

初次安装记录的位置会跨会话复用，也可从其他代码项目调用。安装目录、知识库目录和代码目录可以不同，笔记统一写到当前选定的知识库。

仅本次使用另一个已安装的库：

```text
这次使用 D:\OtherKnowledge 查询以前的记录，不改变默认知识库。
```

长期更换：

```text
以后默认使用 D:\OtherKnowledge 作为知识库。
```

目录搬走后，也明确给出新位置。旧路径失效时，工作流应报出原位置，不能把新建的空库当成原来的知识库。更改默认绑定不会自动搬运或合并两套笔记。

## 知识库怎样组织

`Knowledge` 是日常知识库；解压目录的安装器、测试和发行文档用于维护这套工作流。

- `Projects` 保存具体项目的证据、方法和当前状态。
- `Domains` 保存有来源的理论解释，或确有跨项目依据的共同经验。
- `Archive` 保存停止维护但仍有参考价值的项目。

项目首页负责指路，STATUS 保存当前状态，Review 保存有日期的任务依据，Guide 支持重新执行，故障模式从现象提供排查入口，机制与概念笔记解释原因。这些职责沿用自用 Note Base，按实际内容逐步增加，不预建空文件。

用户级入口只负责定位默认库，完整规则在库内；不同位置共享同一套规则源。首次使用不需要理解这些实现细节。完整分工见[架构说明](https://yzh0013.cloud/projects/knowledge-workflow/architecture/)。

## 更新与卸载

更新时解压新版，在新版目录说“更新我的知识库工作流”。没有指定其他库时复用当前默认位置，保留个人文档。已有首页和 AGENTS.md 不会被整份替换。

从 0.1.x 升级时，旧版尚未登记默认位置。如果新会话无法确定旧库，请提供旧知识库目录一次；更新后便会记住它。不要把安装一个新空库当作旧库已更新。

卸载时在发行目录说“卸载这个知识库工作流”。默认定位到已绑定的库；个人笔记、索引和用户配置保留。卸载默认库时移除本包自己的用户入口和绑定，卸载另一个库时保留当前默认。

受管理文件有本地修改时，工具会完整保留并报告冲突。先将唯一副本备份到知识库外，再按实际需要处理；库内备份使用 `.txt` 或 `.bak`，避免被当成另一份活动笔记或 Skill。

## 常见问题

| 情况 | 处理 |
| --- | --- |
| 找不到 pwsh 或 Git | 先安装缺少的依赖，不把未完成的安装当成功 |
| 新会话没有识别工作流 | 核对实际安装结果和当前 Codex 用户；尝试显式调用，必要时重启 Codex |
| 默认路径找不到 | 给出搬移后的真实目录并更改默认；不要另建空库替代 |
| 想临时用另一个库 | 明确说“这次使用”，不改长期默认 |
| 已有其他来源的同名用户 Skill | 保留原文件；可以只安装库内规则，或自行决定保留哪套入口 |
| 会话无法写入库目录 | 按 Codex 的权限提示处理；默认绑定不会绕过读写权限 |
| 检查通过但内容不对 | 更正具体事实并补充依据；结构检查不判断技术结论真假 |

只安装库内规则的手动入口为 `Install.ps1 -VaultPath <目录> -LocalOnly`。这种方式不登记用户默认，日常从库内调用，或在请求中明确给出库和 Skill 路径。

[本版验证范围](https://yzh0013.cloud/projects/knowledge-workflow/verification/)保留已执行项目与剩余边界。Windows CLI 的结果不自动代表其他宿主版本和多人同时写入的效果。
