内容
="center">
<img width="1280" height="640" alt="py" src="https://github.com/user-attachments/assets821b6-f392-4a89-b6-256b356af405" />
</p>
> **确保你的代码库经受住时间的考验，就像吉金字塔一样。**
# Pyra
ra 是一个可强制执行的 AI 编程代理权限层 它是一个单一的 Go 二进制文件，它将团队决策、需求和设计转化为 **'Canon'**，即化的 Markdown 工件，针对真实标准进行验证，与阻塞 **gate** 系统相连，并通过 **MCP代理提供服务。没有决策是不记录的，也没有无声地违反决策。
Pyra 解决的问题很简单，但却很难忽视：AI 代理的唯一真正约束上下文窗口，而大多数“内存”工具混淆非常不同的属性。 **权限** 询问某件事情是否是的规范。**可发现性** 询问的时间是否能找到正确的内容。向量存储优化了可发现性，但没有权限的概念。Pyra 使权限成为一等公民，*强制执行* 属性：Canon 工件是，其关系是完整性检查的，并且在落地之前，确定性的 gate 会拒绝格式错误或冲突的权限，而 和网络。
Py为 **规范驱动开发**。你工作流中已经产生的规范（`requirements.md`、`design.md`）通过一个命令变成类型化的 Canon，读取它们的代理会自动受到该 Canon 的约束，无论你在 Claude Code 或 Kiro 中驱动 `/spec → /dev → /code-review` 技能，还是任何 MCP 客户端。
**内存是 Canon是 Canon 的 *预算投影*（以及可选的引用）。AI 只投影中。底层是**
Canon 权限模型符合 **需求即代码C）** 的概念。
Pyra 还支持 **。同一个二进制文件 MCP 服务器公开 **结构** — 基于itter 的精确字节搜索（`outline`、`symbols`、`go-to-definitioncallers` 等），以便一个代理使用一个服务器 *团队决定了什么*（Canon）和 *执行什么*。：一个 Canon 工 **基于** 真实代码，解析一个权威决策到它所管辖的精确符号，并且一个符号可以返回它的决策。权威决策和真实代码搜索集中在一个 服务器中。
---
## 为什么选择 Pyra？ - 一个常见用例
你做出一个架构决策 — “ve 进行搜索 同时通过 `/spec`一个功能。你不会手动将它记录在任何地方你批准设计时，技能会将其记录 并为你管理。
/spec → approve design.md (选择 Bleve)
→ 技能将其类型化的 Canon 并运行 gate → 决策作为
```
两周后，在一个全新的会话中，没有，代理提出删除 Bleve 以换成向量数据库。因为 Pyra 通过相同的技能连接到工作流中：
- `/dev` **基于 MCP 上的 Canon**。_decisions` 表面具有 **已接受** 状态的“使用 Bleve 进行搜索”工件及其后果，因此代理根据决策进行论证，而不是绕过它。
- 如果仍然发生与已接受的 Canon 相矛盾的更改，**gate 会在提交时阻止它**（git 钩子），在 `/code-review` 和 CI 中（`gate --sarif`），引用确切的工件和规则。
- 当决策真正 *应该* 更改时，你会创建一个继承者，它会 `## Supersedes` 旧的。Pyra 跟随继承链，以便代理始终看到当前真相，而不是过时的真相。
这就是全部：一旦记录，就会受到尊重**，无论是人还是代理，都无需记住它。
---
## 核心模型
为代理提供两种知识，基于一个底层，即纯 Markdown 加 YAML 前置信息，在 Git 中版本控制：
| | **Canon**（权限） | **Reference**（回忆，可选） |
|---|---|---|
| 答案 | **什么是真实的**：团队决定了什么，必须坚持什么 | **事情如何运作**：支持文档 |
| 内容 | 需求，决策，设计，路线图，提示 | 抓取的文档（爬取的网站，导入的 |
| 创建者 | `pyra new` /ra project` / `pyra promote` |ra crawl` / `pyra import` |
| 验证 | 类型检查，标准检查，关系完整性检查， CI 中 gate** | 允许的，丰富的，可 |
| 确定性 | 仓库状态的，**无 LLM，无网络** | AI 可以层中总结和排名 |
一个 **存储** 是 Git 中的一个目录，包含两个层。它们之间的唯一区别okf/config.yaml` 中的 `canon_ro：在这些根目录下的文件是 Canon，其他一切。Canon 是 Pyra 的核心。引用是可选的便利功能，适用于还需要大量文档库作为代理内存的参见 [附录](#appendix-reference-tier-and-okf-format)）。
### 五种 Canon 工件类型
每种类型都是类型化的 Markdown，具有必填部分，生成的唯一 ID（`<repository-key>-<12-char Crockford base32>`，例如 `OKF-KTQ63DPSMF19`），生命周期状态和类型化关系（`## Related <Type>`、`## Supersedes`）。
| 类型 | 捕获 | 关键必填部分 |
---|
| `requirement` | 必须坚持什么 | `## 问题`，`## 需求`（ `[REQ-NNN] … SHALL …`） |
| `decision` | 选择及其理由（ADR） | `## 上下文`，`## 决策`，`## 后果` |
| `design` | 某物如何构建 | `## 上下文`，`## 用户需求`，`## 设计`，`## 约束` |
| `roadmap` | 随时间变化的预期结果 | `## 结果`，`## 计划` |
| `prompt` | 可重复使用的，已版本化的提示 | `## 目标`，`## 输入`，`## 指令`，`## 输出` |
### gate
`pyra gate` 是强制执行机制和权限模型的核心。它加载语料库，验证每个工件，检查关系完整性，应用强制执行策略，并在任何阻塞性发现时退出，发出 SARIF 进行必填检查。它是 **确定性和离线的**（构建失败的测试禁止 `net/http` 或任何 LLM 依赖项在），因此在提交钩子和 CI 中是安全的。验证包括：
> **变更感知模式（`--diff`）。** 默认情况下，gate 检查 *Canon* 是否格式良好。添加 `--diff`（暂存区差异）、`--since <ref>` 或 `--changed <files>`，gate 还会报告哪些 **已接受的 Canon 工件管理每个更改文件** — 工件管理文件时，它会引用该文件路径或其中的符号 ID — 因此，如果更改影响受管理的代码，则会引用的更改，并且会标记漂移（引用的解析）。这些发现默认是 **建议**强制执行规则代码 `canon-governed-change` 和 `governed-symbol-unresolved` 将其升级为模式重用相同的策略、退出代码和 SARIF 输出，并且保持确定性和离线（映射纯粹是结构性的 — 它存在于 `internal/changegate` 中，不在权限路径中）。
> **变更风险（`--risk`）。** 添加 `--risk`（或运行 `pyra risk`），gate 还会为变更本身评分 **缺陷风险**，根据 diff 的形状（Kamei 实时指标：行 ±、目录、子系统、扩散熵经验）。标题是 **相对于仓库的** —典型` / `典型` / `升高`相对于仓库 **自身** 最近提交的百分比（可移植信号；仅显示原始 0-10 作为次要的、未校准的数字）。它发出 PR **指令** 作为建议性发现：`risk-missing-tests`（更改的源代码中没有测试），`risk-missing-cochanges`（通常一起更改的文件，但被省略 — 隐藏耦合，减去结构导入`risk-will-break更改符号的结构依赖以及 `risk-go`（更改会影响已 Canon）。所有合并到相同的结果、退出代码、JSON 和 SARIF 中。确定性和离线 — 无 LLM，无网络 — 在 `internal/ch 中（在 `internal/gitint` 中具有 git 历史记录底层）。
- **B / RFC 8174**：只有全部大写的 `MUST`/`SHALL`/`SHOULD` 具有规范权重。
- **ISO/IEC/IEEE 29148**：需求应该是单一的和可测试的。
- **EARS**：Easy Approach to Requirements Syntax 一致性。
- **关系完整性**：无悬空、模糊、错误类型或循环引用，并且实时工件不依赖于已废弃的工件（除非通过 `## Supersedes`）。
---
## 代码智能
除了内存之外，Pyra 还可以读取代码。相同的 `pyra` 二进制文件和 MCP 服务器公开了七种 **只读化** 操作，基于纯 Go tree-sitter 运行时 — 无 cgo，嵌入式语法，完全离线：
| 操作 | 答案 |
|---|---|
outline <file>` | 文件的定义作为紧凑的骨架（类型、名称、父级、签名、ID）— 读取此内容而不是整个文件| `symbols <dir>` | 树中的定义位置（gitignore 感知）；精确字符串。 |
| <symbol-id>`某个符号的确切源 — 每次一个符号，按字节。 |
| `check>` | 语法错误（ERROR/MISSING 节点）；如果存在则退出非零。 |
| `callers <name 每个引用的名称，标记为 **结构化**（解析）或 **文本**（整个单词）。 `map <dir>` | 目录的依赖图定义及其输出引用，无正文。 |
definition <name> \| --at file:line:col` | 转到定义；`--at` 作用域感知的，并遵循导入到其他文件。 |
每个结果都带有稳定的 **symbol-id** — `<lang>:<rel<name>@>`（1 为基数）— 代理调用时都会传递这个 ID。这是刻意为之 *不是* LSP：它是纯粹语法分析的，便宜且离线，并且它取代了代理习惯于 grep 和读取整个文件，而是每次一个符号切字节。 它从不改变源代码，遵循 `.gitignore`，并将遍历限制在工作根目录内。
默认支持的语言：**GoJavaScript、TypeScript/TSX、Java、Rust**，以保持二进制文件大小小。
可以通过源代码构建添加其他语言（请参见下面的安装）。
### Canon 如何映射到代码（接地）
权限和代码通过 symbol-id 相遇。 **一个 Canon 工件通过在其正文中提及 symbol-id 来命名它所管理的代码** — 与工件之间的关系通过字面上的 `OKF-…` ID 推断，而非模糊匹配。两个只读工具（pyra ground`）在两个方向上这座桥梁：
- **工件 → 代码**（`code_for_artifact`）：给定一个 Canon 工件 ID，将其主体中的每个 symbol-id当前源，并报告任何不再解析的符号（重命名、移动），而不是返回不。
- **代码 → 工件**（`artifacts_for_symbol`）：给定一个 symbol-id 或文件路径，找到引用它的 Canon 决策、需求和设计。
```text
决策 OKF-… "缓存文档在内存中" ──引用──► go:internal/cache/store.go#Put@42 (真实源代码)
符号 go:internal/cache/store.go#Put@42 ──哪个？──► OKF-… 管理它的决策和需求
```
因此，决策可以指向实现它的确切函数可以询问 *哪些这个符号？* 在更改它之前；审阅者可以看到工件引用的代码是否已经偏离了它。权限始终保持在一起 — **Canon 是内存，symbol-id 是到实时代码的锚点，两者都存在于一个二进制文件中。## 安装
### 下载二进制文件
从 [发布页面](github.com/chasedputnam/pyra/releases) 下载您平台的最新二进制文件。
### 从源代码构建
```bash
go install github.com/chasedputnam/pyra/cmd/pyra@latest
```
或克隆并构建（1.25+）：
```bash
git clone https://github.com/chasedputnam/py
cd pyra
make build
```
###语言语法包含
二进制文件是 **纯 cgo**，并且可以跨编译到每个目标，普通的 `go build` 即可；代码 Go tree-sitter 运行时保持一致make build` 仅嵌入支持语言的语法（通过 `grammar_subset` 构建标签）以保持二进制文件精简；普通的 `go install`/`go build` 不带这些标签，嵌入运行时的完整语法集，生成更大的二进制文件。
> **Apple Intelligence（可选，仅限 Reference 摘要）：** 在 macOS 26搭配 Apple SiliconPyra可选的 `` 构建标签，通过设备的 Foundation Reference 文档。参见 [docs/APPLE_INTELLIGENCE.md](docs/APPLE_INTELLIGENCE.md)。这永远不会触及 Canon 权限路径。
---
## 快速入门
Pyra 旨在通过你的代理的 **技能** 来驱动，而不是手动输入 `pyra` 命令。Claude Code 和 Kiro 的三个捆绑技能 —`、`/dev`、`/code — 在生命周期中的正确时刻运行正确的 Pyra 命令存储后，从技能开始。
### 一设置
```bash
# 1. 搭建存储（写入 .okf/config.yaml + canon 根目录）
pyra init my-store && cd my-store
git init
# 2. 将捆绑的技能和 gate 钩子安装到有的工具中。
# 安装程序会自动检测 Claude Code 和 Kiro 并连接它们。
_skills.sh . # 从此仓库的中运行
# 3. 通过 MCP 将 Canon（和任何引用）提供给您的代理
pyra serve . --mcp
```
`install_skills.sh` 通过其文件夹检测每个支持的工具链（`~/.claude`、`~/.kiro`、`<store>/.git`），并为找到的工具链复制技能目录（`~/.claude/skills` 和/或 `~/.kiro/skills`）并运行 `pyra hooks install`。将存储目录作为其参数传递（默认为 `.`）。如果您想手动执行：
```bash
cp -R .claude/skills/spec .claude/skills/dev .claude/skills/code-review ~/.claude/skills/
pyra hooks install # git + 检测到的代理工具链（Claude Code / Kiro）
```
> **仅安装二进制文件（`go install`）？** 捆绑的技能和 `install_skills.sh` 存在于此仓库中，而不在于二进制文件中。克隆它以获取它们：`git clone https://github.com/chasedputnam/pyra.git`，然后从克隆 `./install.sh`。您也可以在 GitHub 上浏览技能，位于 [aude/skills/`](.claude/skills/) 下。
### 每日循环（由技能驱动）
```text
/spec 计划功能 → requirements.md / design.md （技能运行：pyra project + gate)
/dev 实现它，基于 MCP 上的 Canon （技能运行：find_decisions / get_context，然后重建-review 在提交前根据权限审查 （技能运行：pyra gate --sarif +）
```
每个技能都会检测到 Pyra 存储（一个 `.okf/config.yaml`）并、门控、重建 — 因此，作为您已经在做的工作的副产品，权限被捕获和强制执行。原始命令在 [ra 进行规范驱动开发](#spec-driven-developmentra) 中记录，当您希望直接运行将它们连接到另一个工具链时。
### Canon（可选）
当您想在规范之外记录决策时，请手动创建并门控它：
```bash
pyra new decision canon/adr-001-use-bleve.md --title "使用 Bleve 进行搜索"
$EDITOR canon/adr-001leve.md # 填写 ## 状态（已接受）、## 决策、## 后果
pyra gate . # 在结构、标准或完整性失败时```
然后将你的 MCP 客户端存储根目录**：
```json
{
mcpServers": {
"my-store": {
"command":ra",
"args": ["serve", "/abs/path/to/my-storemcp"]
}
}
}
```
生成的 `.okf/config.yaml`文档化的：
```yaml
仓库密钥：Canon 工件 ID（例如 OKF-3F8A...）。
repository_key: OKF
# Canon 根目录：保存权威层的文件夹。存储中的其他所有内容
# 都被视为引用。gate 通过 `pyra gate` 验证这些文件。
canots:
- canon
# 规范根目录：扫描规范文档（requirements.md、
# design.md）的目录，`pyra project` 将其转换为类型。默认情况下
# 覆盖/ 布局和 Kiro 的 .kiro/specs/ 布局。
ots:
- specs
kipecs
# 代码根目录：结构化代码智能操作
# （大纲、符号、映射...）在未给出路径时默认搜索的目录。
code_roots:
- .
# 工单提供商：格式化外部“## 相关工单”链接。
# 可选值：github、jira、linear、azure-devops、servicenow、none。
ticketing:
provider: github
# 强制执行：按规则代码重新分类 gate 发现。空值 = 每个
# 其默认严重性。取消注释并列出规则代码以覆盖。
enforcement: {}
```
---
## 使用 Pyra 进行规范驱动开发
Py您工作流中基于规范的底层内存。您代理已经编写的 Canon，gate 保持 Canon 的正确性，MCP 将其反馈给代理以完成每个任务。相同的流程适用于 **Claude Code** 或 **Kiro** — 两者都运行 `/spec → /devcode-review` 技能并发出相同的 `requirements.md` / `design.md` 合同，因此一个投影器为两者服务。
推荐的运行循环方式是通过捆绑的技能（参见 [快速入门](#快速入门) 它们为您调用以下命令：命令在此记录，以便您可以直接运行它们或将它们适配到另一个工具链。
### 作者：[未翻译]
### 生命周期，端到端
以下是 `/spec`、` /dev` 和 `/code-review` 技能代表您运行的命令：
```bash
# 0. 每个仓库一次
pyra init . && pyra hooks install # 自动在写入、提交和合并时设置门控
# 1. 需求：/spec 编写 specs/<feature>/requirements.md，然后将其投影到
# 类型化的 Canon（创建稳定 ID，填写章节，推断关系）：
pyra project specs/<feature>/requirements.md
# 或者一次性投影整个 spec 目录（跳过 tasks.md）：
pyra project specs/<feature>/
# 2. 设计：/spec 生成 design.md；它将设计产物投影到：
pyra project specs/<feature>/design.md
# 3. 开发：/dev 在 MCP 上基于 Canon 进行准备。
# find_decisions / get_artifact / get_context 返回必须遵守的权威需求
# 和决策（优先使用 Canon，并带有引用和实时状态）。
# 4. 代码审查：/code-review 运行门控作为必填检查并引用更改内容：
pyra gate . --sarif > pyra.sarif
pyra gate . --diff # 感知变化：哪个 Accepted Canon 控制暂存 diff
pyra relationships . --summary
```
`pyra project` 是 **ratify-or-correct**：它从不重写您的文本或静默覆盖。会创建新产物，仅当使用 `--write`（或交互式确认）时才更改现有产物，而 `--dry-run` 预览差异。重新投影重用产物的 ID，因此身份在迭代过程中保持稳定。仅从文本中的 **literal** `OKF-…` 和别名引用中推断关系，以实现高精度且避免模糊匹配。
### 从现有文档引导
如果决策已经存在于已摄入的 Reference 中，请将其升级到 Canon 而不是重新输入：
```bash
pyra promote <concept-id-or-path> --type decision
```
### 与您的代理技能集成
Pyra 设计为融入您的工作流程中。 每个规范驱动的开发阶段都会在代理已经完成的工作过程中自然产生权威内存：需求在批准后立即成为 Canon，决策在做出时被捕获，门控始终强制执行。 将这些命令放入您已经使用的技能定义中，循环即可自运行。 每个 spec 都能加强内存，每个任务都基于它进行准备，每个审查都根据它进行检查。
**此仓库中提供现成的技能示例。** 您不必手动编写以下命令 - [.claude/skills/](.claude/skills/) 包含三个工作技能（Claude Code 和 Kiro 共享相同的 `SKILL.md` 格式），它们已经将 Pyra 集成到生命周期的每个阶段：
| 技能 | 阶段 | Pyra 集成 |
|---|---|---|
| [`spec`](.claude/skills/spec/SKILL.md) | 需求 → 设计 → 任务 | 将每个已批准的 `requirements.md` / `design.md` 投影到类型化的 Canon 并门控。 |
| [`dev`](.claude/skills/dev/SKILL.md) | 实现 | 在 MCP 上基于 Canon 准备工作（`find_decisions` / `get_artifact` / `get_context`）然后编写代码；在状态更改后重建索引。 |
| [`code-review`](.claude/skills/code-review/SKILL.md) | 审查 | 运行 `pyra gate --sarif` 作为必填权限检查，并通过 `pyra relationships --summary` 引用触摸的产物。 |
这些技能中的每个 Pyra 步骤都受到“如果是 Pyra 存储”的检查保护，因此它们也可以在不使用 Pyra 的仓库中不变地工作。 最快安装它们的方法是使用捆绑的安装程序，它可以自动检测并配置所有工具链：
```bash
./install_skills.sh . # 自动检测 Claude Code / Kiro / git 并配置每个工具链
```
或者手动复制到您的个人技能目录以在任何地方使用：
```bash
cp -R .claude/skills/spec .claude/skills/dev .claude/skills/code-review ~/.claude/skills/
```
或者保留在 `.claude/skills/` 下，以将它们限定在此仓库中。 有关详细信息，请参见 [.claude/skills/README.md](.claude/skills/README.md)。 每个技能运行的命令在下面总结。
**Claude Code** (`~/.claude/skills/`):
```bash
# /spec：在每个批准关口，将刚刚批准的文档投影到 Canon 并强制执行
pyra project "specs/${FEATURE}/requirements.md"
pyra gate . # 在失败的门控上阻止批准
# /dev：在编写代码之前，在 MCP 上准备工作（已经运行）：
# find_decisions("<area>"), get_artifact("OKF-..."), get_context("<task>")
pyra rebuild . # 在状态更改后刷新派生索引
# /code-review：使门控成为必填检查并引用触摸的权限
pyra gate . --sarif > pyra.sarif
pyra relationships . --summary
```
安装写入钩子，以便在代理循环中运行门控：
```bash
pyra hooks install --claude # PostToolUse 钩子 → 在写入/编辑后执行 pyra gate
```
**Kiro** （技能位于 `~/.kiro/skills/`，规范位于 `.kiro/specs/`，钩子位于 `.kiro/hooks/` 用于 IDE 和 `.kiro/agents/*.json` 用于 CLI）：
Kiro 读取相同的 `SKILL.md` 格式，因此上述三个技能安装并运行方式相同 - 只需复制它们到 `~/.kiro/skills/`（安装程序在检测到 Kiro 时会执行此操作）。 投影仪和钩子使用 Kiro 的布局：
```bash
pyra project .kiro/specs/${FEATURE}/ # 相同的投影仪，Kiro 布局
pyra hooks install --kiro # 编写 Kiro IDE + CLI 门控钩子
```
**任意 MCP 客户端** （不需要技能）：运行 `pyra serve . --mcp`，将客户端指向存储根目录，代理可以直接获取权限工具 (`find_decisions`, `get_artifact`, `get_context` 等)。
结果是一个复合系统。 您的团队规范、决策和交付的产品越多，代理的内存就越丰富、越权威，而门控保证它永远不会偏离团队实际同意的内容。
---
## 命令
大致按照使用顺序排列。 存储范围命令默认为当前目录（`.`）。
### 存储设置
| 命令 | 目的 |
|---|---|
| `pyra init [path]` | 脚手架存储：写入 `.okf/config.yaml` 并创建 canon 根目录。 标志： `--repository-key`， `--canon-root` （可重复）， `--ticketing`， `--force`， `--quiet`。 |
### 编写 Canon
| 命令 | 目的 |
|---|---|
| `pyra new <type> <path>` | 脚手架具有已铸造 ID 和类型章节的 typed 产物。 标志： `--store`， `--title`。 |
| `pyra project <spec-doc-or-dir>` | 将已批准的 `requirements.md` / `design.md` （本地 `specs/` 或 Kiro `.kiro/specs/`）投影到类型化的 Canon 中：重用或铸造稳定 ID，从文本中填写章节，推断字面关系，验证。 标志： `--store`， `--type`， `--dry-run`， `--write` / `--force`， `--kiro-agent`， `--json`， `--quiet`。 |
| `pyra promote <concept-id-or-path>` | 将已摄入的 Reference 概念升级为 typed Canon 草稿。 标志： `--store`， `--type`， `--out`。 |
### 权限
| 命令 | 目的 |
|---|---|
| `pyra gate [store]` | 运行统一的权限门控（验证 + 关系 + 策略）。 如果有任何阻止性发现，则退出非零。 标志： `--json`， `--sarif`； 感知变化： `--diff` （暂存）， `--since <ref>`， `--changed <a,b>`； 变更风险： `--risk`。 |
| `pyra risk [commit \| base..head]` | 为缺陷风险评分变更（仓库相对排名 + PR 指令）。 无参数则对暂存 diff 进行评分。 标志： `--store`， `--baseline`， `--ext`， `--json`。 |
| `pyra relationships [store]` | 报告和验证类型化的关系图。 标志： `--validate`， `--summary`， `--json`。 |
### 代码智能
读取源代码的结构化搜索和导航。 每个命令都接受 `--json`； 结果携带稳定的 symbol-id。
| 命令 | 目的 |
|---|---|
| `pyra outline <file>` | 列出文件的定义为骨架。 标志： `--kind`， `--detail` （0/1/2）， `--json`。 |
| `pyra symbols <dir>` | 在目录中查找符号。 标志： `--name`， `--name-contains`， `--kind`， `--refs`， `--json`。 |
| `pyra source <symbol-id>` | 打印一个符号的源代码（或 `--file` + `--name`）。 标志： `--json`。 |
| `pyra check <file>` | 报告语法错误； 如果有任何错误则退出非零。 标志： `--json`。 |
| `pyra callers <name>` | 查找引用，标记为 `[S]` 结构化 / `[T]` 文本。 标志： `--dir`， `--json`。 |
| `pyra map <dir>` | 目录依赖图。 标志： `--kind`， `--name`， `--name-contains`， `--json`。 |
| `pyra definition [name]` | 通过名称或 `--at file:line:col` 跳转到定义。 标志： `--at`， `--dir`， `--json`。 |
| `pyra ground <artifact-id \| symbol-id>` | 桥接 Canon 和代码：解析产物的引用符号，或查找引用符号的产物。 标志： `--store`， `--json`。 |
### Git 智能
从 git 历史记录中挖掘行为信号 - 确定性，离线，无 LLM，锚定在 HEAD 的提交时间，因此相同的存储库状态产生相同的结果。
| 命令 | 目的 |
|---|---|
| `pyra hotspots [store]` | 按时间衰减的 churn 排名文件（顶部四分位数热点清除活动地板），并附有 churn %，提交次数，所有者和总线因子。 标志： `--limit`， `--window`， `--json`。 |
| `pyra ownership [path]` | 文件的所有权 %，最近的所有者，贡献者数量和总线因子； 模块（顶级目录）汇总目录或无路径。 标志： `--store`， `--window`， `--json`。 |
指标：每个文件的提交窗口，行 churn，年龄，时间热点得分（180天半衰期），主要/最近所有者，贡献者数量，总线因子（达到 80% 提交的最小作者数量），变更合作伙伴； 存储库级别的热点排名； 和每个模块的汇总。 所有权按提交者分布（`git blame` 行所有权和 churn×complexity 热点改进与代码健康度相同）。 请参阅 [`docs/REPOWISE_PARITY.md`](docs/REPOWISE_PARITY.md)。
### 代码图
一个持久的双层（文件 + 符号）依赖图，构建自代码智能 - 确定性，离线，无 LLM，无外部图库。
| 命令 | 目的 |
|---|---|
| `pyra graph [store]` | 查询代码依赖图。 子视图： `--centrality` （PageRank 中心）， `--communities` （通过标签传播的逻辑模块）， `--cycles` （依赖循环 / 强连通组件）， `--reachability` （从入口点可达 vs. 不可达）。 标志： `--limit`， `--scope`， `--node-cap`， `--json`。 |
符号节点（按 symbol-id 键入）+ 文件节点； 引用边通过与 `callers` 相同的诚实名称匹配解决（边到每个名称冲突上的匹配定义，绝不猜测目标）。 分析是标准且自成体系的 - PageRank，确定性标签传播，Tarjan 强连通组件和入口点可达性（其不可达集支持死代码检测）。 介数中心性和莱顿（Leiden）有意推迟。
| 命令 | 目的 |
|---|---|
| `pyra dead-code [store]` | 报告可能无法访问的定义（从入口点在图中无路径），按清理影响排名，每个都有置信度层级 - **高** （无文本引用，安全删除）， **medium** （有文本/可能动态引用）， **low** （测试文件助手） - 以及 `[governed]` 标记，当 Accepted Canon 仍引用现在无法访问的代码（漂移）。 标志： `--tier`， `--limit`， `--json`。 |
死代码 **消耗** 图的可达性（无需新分析）； 它排除 `Test*` / `main` 入口点，因为 pyra 没有框架路由→处理程序边，因此使用保守的高层级以避免标记仅路由的处理器（它们通常被导出，因此可达）。 自动移除。
### 代码健康度
每个文件的 **健康度评分** 跨三个信号 - **缺陷风险 · 可维护性 · 性能** - 来自代码结构，git 历史记录，依赖图和 Canon 治理的确定性生物标志物组。 无 LLM，离线。
| 命令 | 目的 |
|---|---|
| `pyra health [store]` | 仓库 KPI（NLOC 加权平均值 + 热点健康度，最差执行者）和最低评分文件及其三个维度得分和顶级标记。 标志： `--file <path>` （每个文件发现 + 影响 + 重构建议）， `--coverage <report>` （导入 LCOV/Cobertura）， `--limit`， `--json`。 |
生物标志物组（~28 个标记）涵盖 **结构化** （圈复杂度，嵌套，`god_class` / `god_file`，LCOM4 凝聚力，...）， **组织化** （churn，变更熵，共变散射，所有权风险，先前缺陷，...）， **重复** （Rabin-Karp 克隆检测）， **覆盖率** （当提供报告时）和 Pyra 独有的 **治理** 标记 - `ungoverned_hotspot` （具有 churn 热点的无治理 Canon）， `stale_governance` 和 `contradictory_decision`。 每个文件从 10 开始，生物标志物在每个类别下扣除； 评分内核是 [repowise](https://github.com/repowise-dev/repowise) 的 **忠实移植** （AGPL-3.0），通过 parity 测试隔离到一个可交换的文件，并通过 parity 测试固定。 **性能维度随附但为空** （其循环/数据流检测器是后续跟进）； 请参阅 [`docs/REPOWISE_PARITY.md`](docs/REPOWISE_PARITY.md)。
### 自动化（事件钩子）
| 命令 | 目的 |
|---|---|
| `pyra hooks install` | 安装自动运行门控的钩子。 git 总是安装（`pre-commit` 运行阻止门控，`post-merge` 运行完整性守护），并自动检测目标。 目标标志： `--git`， `--claude`， `--kiro-ide`， `--kiro-cli`， `--kiro`， `--all`，以及 `--kiro-agent`， `--store`。 |
| `pyra hooks uninstall` | 仅删除 Pyra 管理的钩子内容，保留其他钩子完整。 |
| `pyra hooks status` | 显示每个目标的 Pyra 钩子安装情况。 |
表面：git（`.git/hooks/`），Claude Code（`.claude/settings.json` PostToolUse），Kiro IDE（`.kiro/hooks/pyra-gate.json`）和 Kiro CLI（`.kiro/agents/<agent>.json` 下 `hooks.postToolUse`）。 每次安装都是标记分隔且幂等。
### 操作存储库
| 命令 | 目的 |
|---|---|
| `pyra rebuild [store]` | 从 Markdown 源代码重新生成派生索引（全文搜索 + 关系图）。 |
| `pyra serve <store>` | 在 MCP 上提供存储服务。 标志： `--mcp` （默认）， `--name`， `--max-result-chars`。 |
| `pyra export [store]` | 为扩展导出 Reference 知识（文档/图）。 |
| `pyra demo` | 使用捆绑的示例运行离线演示。 |
### 可选：Reference 引入（次级）
对于也希望将大量文档库作为代理内存的团队。这些 populate Reference 层并且永远不会触及 Canon。
| 命令 | 目的 |
|---|---|
| `pyra crawl <url>` | 将文档网站爬取到 OKF 捆绑。 |
| `pyra import <path>` | 导入本地 Markdown 到 OKF 捆绑。 |
| `pyra update <bundle>` | 从其源更新现有捆绑。 |
| `pyra validate <bundle>` | 验证 OKF 捆绑。 |
| `pyra inspect <bundle>` | 检查捆绑并显示统计信息。 |
---
## MCP 工具
`pyra serve <store> --mcp` 将存储暴露给任何 MCP 客户端。 工具按作业分组。
### 权限（Canon）
| 工具 | 返回 |
|---|---|
| `find_decisions` | 匹配查询的 Canon 工件，按权限优先顺序，附带引用和生命周期状态。 |
| `get_artifact` | 通过 ID 获取特定工件（解决 `## Supersedes` 到当前继任者）。 |
| `get_context` | 任务的预算化、以 Canon 为优先的上下文包，保留规范文本原样。 |
| `get_related` | 工件的类型化关系（相关需求、决策等）。 |
| `get_neighbors` | 工件 N 跳范围内的关系。 |
### 代码智能
| 工具 | 返回 |
|---|---|
| `outline` | 文件的定义骨架，附带稳定的 symbol-id。 |
| `symbols` | 按名称/种类在目录中匹配的符号（gitignore 感知）。 |
| `source` | 一个符号的精确来源（按 ID 或文件 + 名称）。 |
| `check` | 文件中的语法错误（ERROR/MISSING 节点）。 |
| `callers` | 引用，标记结构化与文本。 |
| `map` | 目录的依赖图（定义 + 发出引用）。 |
| `definition` | 通过名称或位置范围查找定义。 |
### 准备（Canon ↔ 代码）
| 工具 | 返回 |
|---|---|
| `code_for_artifact` | Canon 工件引用的每个 symbol-id 的当前源代码；列出任何不再解析的代码。 |
| `artifacts_for_symbol` | 引用给定 symbol-id 或文件的 Canon 工件。 |
### Git 智能
| 工具 | 返回 |
|---|---|
| `get_hotspots` | 仓库的 churn 热点，按 churn %、提交次数、所有者和总线因子排名。 |
| `get_ownership` | 文件的所有权 / 总线因子，或顶级模块的汇总目录或空路径。 |
### 代码图
| 工具 | 返回 |
|---|---|
| `get_graph_centrality` | 依赖图上的符号按 PageRank 排名（中心）。 |
| `get_communities` | 图分区为社区（逻辑模块）。 |
| `get_cycles` | 依赖循环（强连通组件）。 |
| `get_dead_code` | 可能无法访问的定义按清理影响排名，附有置信度层级和受管辖标志。 |
### 代码健康度
| 工具 | 返回 |
|---|---|
| `get_health` | 仓库 KPI 和最低评分文件（缺陷/可维护性/性能）附带顶级标记和重构建议。 |
### 回忆（Reference）
| 工具 | 返回 |
|---|---|
| `search_concepts` | Reference 层级的全文搜索。 |
| `read_concept` | 单个概念的全文内容。 |
| `get_summary` | 概念的摘要。 |
| `list_types` / `list_tags` | 存储中存在的词汇。 |
### 实时更新与实用工具
`check_updates`，`apply_updates`（使用 `dry_run: true` 预览），`bundle_health`，`bundle_summary`，`compression_stats`。
## 配置：`.okf/config.yaml`
| 键 | 含义 |
|---|---|
| `repository_key` | 生成的 Canon ID 前缀（例如 `OKF`）。 |
| `canon_roots` | 存放权威层级的目录；其他均为参考层级。 |
| `spec_roots` | `pyra project` 扫描规范文档的目录。默认值：`["specs", ".kiro/specs"]`。 |
| `code_roots` | 代码智能操作在未指定路径时搜索的目录。默认值：`["."]`。 |
| `ticketing.provider` | 格式化 `## 相关工单` 链接的格式。支持 `github`、`jira`、`linear`、`azure-devops`、`servicenow`、`none`。 |
| `enforcement` | 根据规则代码将门控发现重新分类为 `blocking` / `advisory` / `disabled`。为空时，每个规则保持其默认严重性。 |
`config.yaml` 是区分层级的唯一文件，渲染输出通过加载循环，因此您可以手动编辑或使用 `pyra init --force` 重新生成。
---
## 附录：参考层级和 OKF 格式
参考层级是可选的支持材料（丰富、总结、可搜索），渲染为 **开放知识格式（OKF）** 包：人类和代理可读的 Markdown，带有 YAML 前置信息，可在无需中心注册表的情况下交换（[什么是 OKF？](https://openknowledgeformat.com/what-is-okf)）。当您想要一个大型文档库可用作代理内存而无需建立向量存储时，它是合适的工具。
### 改造现有仓库（仅参考）
```bash
# 将仓库的 Markdown 导入自成一体的包并直接提供服务
pyra import ~/repo/my-project --out ~/repo/my-project/.okf --source-name "我的项目"
pyra serve ~/repo/my-project/.okf --mcp
```
如果没有填充 `canon_roots`，包将保持纯参考层级，并表现为独立的可搜索知识库。`pyra promote` 是当参考概念成熟为值得强制执行的 Canon 时的桥梁。
### 概念格式
每个参考概念都是一个带有前置信息的 Markdown 文件：
```yaml
---
type: "指南"
title: "快速入门"
description: "如何快速入门"
resource: "https://example.com/docs/getting-started"
tags: ["设置", " onboarding"]
timestamp: "2024-01-01T00:00:00.000Z"
---
```
`type` 和 `title` 是必填项；`description`、`resource`、`tags` 和 `timestamp` 是可选的。`index.md` 提供摘要优先的导航和 bundle 间的反向链接。
### 总结
参考总结可以通过快速的 **提取** 算法（离线、确定性）或可选的 **LLM** 模式通过外部 OpenAI 兼容端点或本地 Ollama 回退生成。总结仅适用于参考层级，从不参与 Canon 权威路径。
### 规模上限
摘要优先的导航适用于大约 **100 个概念 / ~400K tokens**。超过此限制，可使用 `pyra export` 将模糊部分升级到外部 RAG 系统，而 Canon 始终在仓库中保持权威。
## 许可证
Pyra 在 [商业源许可证 1.1](https://github.com/pyra-team/pyra/blob/main/LICENSE) (`BUSL-1.1`) 下发布，四年后转换为 **Apache License, Version 2.0**。BSL 是源代码可用的，**不是** OSI 批准的“开源”许可证；请将其描述为 *源代码可用*，直到变更日期。
> **分发说明：** Pyra 的变更风险常数当前从 [repowise](https://github.com/repowise-dev/repowise) （AGPL-3.0）移植而来。参见 [`NOTICE`](https://github.com/pyra-team/pyra/blob/main/NOTICE) — 在 Pyra 可以在 BSL 下分发之前，必须用独立实现替换该移植材料。LICENSE 声明了预期条款；它不授权分发当前树。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器