安装：命令行或聊天，二选一¶

已经有 Python 或 Conda 环境，不需要从头再装一遍 Python。 这里只区分两种安装方式：自己在命令行完成，或交给聊天中的客户端完成。环境管理方式由你选择。

方式一：命令行安装¶

第 1 步：选好 Python 环境，不必人人新建¶

选择下面一种情况即可。要求 Python 3.11+；新建时可选 3.12。已有合适环境就复用，使用 Conda 就直接用 Conda，不用再在 Conda 里面创建 .venv。

A. 已经有日常使用的 Python / 项目环境

打开你平时使用的终端，先按自己的方式激活目标环境，再运行：

python --version
python -c "import sys; print(sys.executable)"
python -m pip --version
git --version

确认 Python 为 3.11+，sys.executable 指向你希望使用的环境，pip 也属于同一环境。Git 用于从 GitHub 安装。然后直接进入第 2 步。

不要在不清楚用途的系统 Python、Conda base 或正在运行重要实验的环境中直接安装。pip 可能调整依赖；需要保留原环境时，选择下面的独立 Conda 或 venv 环境。仅缺 Git 时可从 Git 官网安装，重新打开终端后再激活原环境。

B. 使用 Anaconda / Miniconda 管理环境

Windows 打开开始菜单中的 Anaconda Prompt 或 Miniconda Prompt；macOS / Linux 打开平时能运行 conda 的终端。不需要另装一套 Python。

先查看已有环境：

conda --version
conda env list

想单独建一个环境： 确认列表里没有名为 hyper-knowledge 的环境，再逐行执行；创建成功后再激活。Conda 提示确认软件包方案时，阅读后确认。

conda create -n hyper-knowledge python=3.12 pip git
conda activate hyper-knowledge

这里 python=3.12 是 Python 版本，pip 用于安装项目，git 用于读取 GitHub 源码。它们属于新环境，不是安装到 base。

想复用已有环境： 不执行 conda create，而是运行下方命令；将 research 换成 conda env list 中你选好的环境名。

conda activate research

如果你用完整路径创建了环境，也可以 conda activate "环境的完整路径"。确认版本和路径：

python --version
python -c "import sys; print(sys.executable)"
python -m pip --version
git --version

已有环境缺少 pip 或 Git 时，在确认可以修改该环境后先安装它们，再进行第 2 步；两者都有就跳过：

conda install pip git

先完成 Conda 依赖，再用 pip 安装本项目；不要使用 pip install --user。后面 Skill 命令里的 --scope user 只指定 Skill 的发现范围，与 pip 的 --user 不是一回事。

终端前缀通常会显示环境名；每次重新打开终端，先 conda activate hyper-knowledge（或你自己的名字），不需要重新安装。

C. 还没有可用环境：安装 Python，然后使用 venv

这一节只给需要从头准备环境的人。安装 Python 3.11+ 和 Git，Windows 安装 Python 时启用加入 PATH 的选项，然后重新打开终端。

Windows PowerShell 运行 python --version；macOS / Linux 运行 python3 --version，确认版本至少 3.11。两边都用 git --version 确认 Git 可用。已有安装不必重复装。

Windows PowerShell： 在用户目录下创建环境，并只让当前终端优先使用它。无需修改脚本执行策略。

$hkEnv = Join-Path $env:USERPROFILE ".venvs\hyper-knowledge"
if (Test-Path -LiteralPath $hkEnv) {
    throw "Environment already exists. Inspect it before continuing."
}
python -m venv "$hkEnv"
if ($LASTEXITCODE -ne 0) { throw "Environment creation failed." }
$env:PATH = "$(Join-Path $hkEnv 'Scripts');$env:PATH"
python -c "import sys; print(sys.executable)"

macOS / Linux： 先确认 ~/.venvs/hyper-knowledge 不存在；若已存在，直接激活并检查，不重建。首次创建时逐行执行：

python3 -m venv "$HOME/.venvs/hyper-knowledge"
source "$HOME/.venvs/hyper-knowledge/bin/activate"
python -c "import sys; print(sys.executable)"

环境创建失败时先处理错误，不能继续安装。缺少 venv / ensurepip 时，安装该 Python 版本对应的 venv 组件。保留环境和基础 Python；重新打开终端后需重新选择它，后文提供命令。

第 2 步：在选好的环境中安装 Hyper-Knowledge¶

下面三种环境用同一组命令。在刚才已激活或选好环境的终端里，逐行运行；前一步成功后再执行下一步：

python -m pip install "git+https://github.com/hanxiangmin/Hyper-Knowledge.git"
python -m hyperknowledge --help

第一条下载项目并安装依赖，第二条显示帮助。看到 parse、bundle、visualize、skill 等条目，即可继续。python -m pip 保证把包安装到这条 python 对应的环境，不要求终端已经认识 hk。

只使用 Python / Notebook 或命令行，到这里就装好了。要在聊天中使用，再做下一步。

第 3 步：按需安装 Codex 或 Kimi Code Skill¶

客户端应用需要提前安装并能登录。这一步安装的是 Skill，不是客户端本身；仍在第 2 步的同一个环境执行。

Codex：

python -m hyperknowledge skill install --platform codex --scope user

Kimi Code：

python -m hyperknowledge skill install --platform kimi --scope user

用哪个客户端就执行哪条，两者都用可以分别执行，不必重复安装运行程序。安装器返回状态和路径；提示本地修改或冲突时先查看，不自动加 --force。成功后在客户端新建会话。

方式二：聊天中安装¶

选择你正在使用的客户端，直接复制对应的完整文案到聊天框：

Codex

请按 https://github.com/hanxiangmin/Hyper-Knowledge 的安装说明，为 Codex 安装用户级 hyper-knowledge Skill。可使用已有 Python/Conda 环境，覆盖本地修改前先询问。

Kimi Code

请按 https://github.com/hanxiangmin/Hyper-Knowledge 的安装说明，为 Kimi Code 安装用户级 hyper-knowledge Skill。可使用已有 Python/Conda 环境，覆盖本地修改前先询问。

不需要先手动执行命令行安装。安装细节按仓库说明处理；需要登录或授权时由你确认。完成后开启新会话使用。普通网页聊天如果没有本地工具权限，不能替电脑安装程序。

安装后怎么用？¶

Codex 中输入 $hyper-knowledge，Kimi Code 中输入 /skill:hyper-knowledge，随后描述任务、提供文件即可。例如：“读取 notes.md，生成带成员角色和原文依据的高阶知识图谱工作台。”

默认由当前客户端的模型读文档，再调用本地 Python；不需要另配一份 Hyper-Knowledge 模型密钥。Python/CLI 的独立自动解析需要配置模型服务，结构化导入和渲染则不需要。

Python / Notebook · API 参考 · CLI 配方 · Skill 用法

重新打开终端后怎么办？¶

Conda 环境：打开 Anaconda Prompt 或能运行 Conda 的终端，激活安装时的环境：

conda activate hyper-knowledge
python -m hyperknowledge --help

如果用了其他环境名，就换成你的名字。也可以不手动激活，明确指定环境执行；这适合脚本调用：

conda run -n hyper-knowledge python -m hyperknowledge --help
conda run -n hyper-knowledge python -m hyperknowledge skill install --platform codex --scope user

第二条只在需要安装或更新 Skill 时执行，不是每次运行都要执行。Kimi 使用 --platform kimi。按路径创建的 Conda 环境使用 conda run -p "环境完整路径" 替换 conda run -n hyper-knowledge。

venv 环境：Windows PowerShell 可直接调用固定路径，不必激活：

& "$env:USERPROFILE\.venvs\hyper-knowledge\Scripts\python.exe" -m hyperknowledge --help

macOS / Linux：

source "$HOME/.venvs/hyper-knowledge/bin/activate"
python -m hyperknowledge --help

其他已有环境：按原来的方式激活，检查 python -c "import sys; print(sys.executable)"，再调用 python -m hyperknowledge。

hk 是运行程序安装后生成的快捷命令，不是系统内置命令。已激活环境且 hk --help 正常时可以用简写，否则继续使用上面的 python -m hyperknowledge。Conda 不要照搬 venv 的 Scripts/python.exe 路径；推荐激活或用 conda run，以保留 Conda 所需的环境设置。

Notebook 怎样使用同一个 Conda 环境？¶

先完成上面的运行程序安装。然后在终端中运行：

conda activate hyper-knowledge
python -m pip install ipykernel
python -m ipykernel install --user --name hyper-knowledge --display-name "Python (Hyper-Knowledge)"

如果复用了其他环境，第一行改成它的名字。后两行安装并注册内核，不会创建另一套 Python。已有同名内核时，先选择它检查路径；不要覆盖需要保留的内核，必要时换一个 --name。

在 Jupyter / VS Code 的 Notebook 内核菜单选择 Python (Hyper-Knowledge)，然后运行：

import sys
import hyperknowledge

print(sys.executable)
print(hyperknowledge.__version__)

解释器应指向刚才的 Conda 环境。Notebook 自己的服务器环境可以不同，但执行代码的内核必须选对。可执行 Notebook 示例与嵌入工作台

已有安装与安装中断¶

不要删除已有环境，也不要直接强制覆盖 Skill。在目标环境中先查看：

python -m pip show hyper-knowledge
python -c "import sys; print(sys.executable)"

这会显示版本、位置和解释器；它不负责判断所有本地修改。发现可编辑源码、被修改的 Skill 或冲突副本时，先看差异并询问，再决定更新。更换 Python 环境时，也应先确认是否要重新绑定已有 Skill，不能静默换掉正在使用的运行程序。

首次安装下载中断时，重新激活同一个环境，只重试第 2 步的 pip 安装；不重建环境、不再次 conda create。前一步失败就先处理，不继续执行后面的 Skill 命令。

需要排查时再看¶

问题	处理方式
Windows 找不到 `conda`	先用 Anaconda / Miniconda Prompt，不必在普通 PowerShell 里反复重装 Python
`conda activate` 在当前终端无效	换到已初始化的 Conda 终端，或使用上面的 `conda run`；不要在错误环境里继续 pip 安装
Python 太旧或 pip 不属于目标环境	重新选环境，或新建 Python 3.12 的独立环境，不强行升级原实验环境
找不到 `git`	Conda 环境可在安装本项目前用 `conda install git`；也可安装系统 Git
找不到 `hk` 或 `hyperknowledge` 模块	检查是否激活了安装时的环境，以及第 2 步是否成功
Conda 中命令正常，桌面客户端却报 DLL / 库加载错误	可能缺少激活时的环境设置；先在同一个已激活终端中启动客户端，或用 `conda run` 复现，不要重新安装到 base
Notebook 无法 import，但终端可以	查看 Notebook 的 `sys.executable`，重新选择正确内核
Skill 提示本地修改或重复副本	检查现有安装，不自行追加 `--force`

可选诊断（在安装时的环境执行）：

python -m hyperknowledge skill doctor --platform codex --scope user --deep --json

Kimi 换成 --platform kimi。这不是必须步骤，也不是 Docker；它检查本地安装和合成流程，不代表真实客户端已完整测试通过。

给代为安装的客户端¶

用户只需要上面的短安装请求。实际执行时，请阅读这份说明，确认用户要用的客户端和环境；没有指定环境时，不擅自修改 base、系统 Python 或研究环境。运行程序和 Skill 使用同一个长期保留的解释器；发现已有本地修改先询问。结束时返回安装位置和使用方式，明确未完成项，不绕过登录或权限要求。

环境说明参考 Conda 环境管理、在 Conda 中使用 pip 和 conda run。兼容性与实际测试范围单独记录；本地尚未推送的代码不包含在 GitHub 安装包中，测试它时把 pip 安装地址换成本地 wheel。