{"id":51009295,"url":"https://github.com/codingapi/pkr-marketplace","last_synced_at":"2026-06-21T00:36:13.094Z","repository":{"id":363296363,"uuid":"1262665222","full_name":"codingapi/pkr-marketplace","owner":"codingapi","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-09T06:31:38.000Z","size":154,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-21T00:36:07.575Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codingapi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-08T07:49:20.000Z","updated_at":"2026-06-09T06:31:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codingapi/pkr-marketplace","commit_stats":null,"previous_names":["codingapi/pkr-marketplace"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/codingapi/pkr-marketplace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codingapi%2Fpkr-marketplace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codingapi%2Fpkr-marketplace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codingapi%2Fpkr-marketplace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codingapi%2Fpkr-marketplace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codingapi","download_url":"https://codeload.github.com/codingapi/pkr-marketplace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codingapi%2Fpkr-marketplace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34590214,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-21T00:36:12.553Z","updated_at":"2026-06-21T00:36:13.085Z","avatar_url":"https://github.com/codingapi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pkr-marketplace\n\n面向 Claude Code 的 **项目知识注册中心（PKR）** 插件市场。扫描项目代码，自动发现并注册可复用能力（Capability）和开发规范（Convention），让 AI 在编码前知道项目已有什么、该怎么做。\n\n## 什么是 PKR？\n\n**PKR** 是 **Project Knowledge Registry**（项目知识注册中心）的缩写。\n\n它的核心理念是：**AI 编码前应该先了解项目已有什么**。\n\n传统开发中，新成员入职会先看项目文档、问老员工\"项目里有哪些工具类、用什么规范\"。但在 AI 辅助编码场景下，Claude 虽然能读代码，却不知道：\n- 项目已经有哪些可复用的能力（如 WorkflowEngine、EventBus）\n- 项目有哪些必须遵循的开发规范（如 Design Token、事件发布规则）\n\n**PKR 就是给 AI 准备的\"项目知识库\"**：\n- 通过结构化文档记录项目的 **能力（Capability）** 和 **规范（Convention）**\n- 在 AI 编码前自动注入这些知识到上下文\n- 避免重复造轮子和违反规范\n\n## 核心理念\n\n```\n代码源码 → 扫描发现 → Capability/Convention 文档 → AI 编码前查询\n```\n\n**解决两个核心问题：**\n\n1. **重复造轮子** — AI 不知道项目已有 Workflow Engine，又写了一个\n2. **违反规范** — AI 写死 `color: #1677ff` 而非使用 Design Token 变量\n\n## 前置条件\n\n- Claude Code CLI 已安装并登录\n- Git 已初始化（`git init`）\n- Python 3（用于索引重建脚本）\n\n## 推荐配置：CodeGraph\n\n**强烈推荐**安装 [CodeGraph](https://github.com/colbymchenry/codegraph)，可显著提升代码分析的速度和准确性。\n\n## 快速开始\n\n### 1. 安装插件\n\n安装插件市场，首次需要\n```bash\n/plugin marketplace add git@github.com:codingapi/pkr-marketplace.git\n```\n\n安装pkr插件\n```bash\n/plugin install pkr@pkr-marketplace\n```\n\n### 2. 创建项目结构\n\n```bash\n/pkr-create\n```\n\n创建 PKR 所需的目录结构（`docs/capabilities/`、`docs/conventions/`、`docs/agents/`）并在 CLAUDE.md 中注入知识查阅约束。\n\n### 3. 首次扫描\n\n```bash\n/pkr-init\n```\n\nClaude 会扫描项目代码、依赖和规划文档，列出候选的能力和规范，由你确认后生成文档。\n**已有文档会自动跳过**，不会重复分析（包括从外部导入的模块文档）。\n\n### 4. 日常维护\n\n```bash\n# 修改了某个能力后，立即更新对应文档\n/pkr-update workflow-engine\n\n# 带描述信息，指导更新重点\n/pkr-update workflow-engine \"新增了重试机制\"\n\n# 定期全量同步（检查所有文档与代码的一致性）\n/pkr-sync\n\n# 从代码中扫描注册（名称自动从代码提取）\n/pkr-add \"项目自有的重试引擎，支持指数退避\"\n\n# 注册计划中的能力（名称从描述提取）\n/pkr-add plan \"基于 Drools 的业务规则引擎\"\n```\n\n## 命令详解\n\n### `/pkr-create` — 创建项目结构\n\n创建 PKR 所需的目录结构和 CLAUDE.md 集成：\n\n- 创建 `docs/capabilities/`、`docs/conventions/`、`docs/agents/` 目录\n- 在 CLAUDE.md 中注入知识查阅约束（幂等）\n\n### `/pkr-export \u003cmodule\u003e ...` — 导出模块文档\n\n将指定模块的能力和协规文档导出到 `docs/agents/{module}/`，供其他项目作为外部能力导入：\n\n```bash\n/pkr-export mylib                    # 导出单个模块\n/pkr-export mylib springboot         # 导出多个模块\n```\n\n导出规则：\n- `source: 项目自有` → 转换为 `source: 框架:{module}`，移除 `symbols`/`content_hash`，补充 `framework_version`\n- `source: 框架:xxx` → 原样复制\n\n下游项目使用：将导出的文件复制到 `docs/capabilities/{module}/` 和 `docs/conventions/{module}/`，然后执行 `/pkr-init`。\n\n### `/pkr-init` — 扫描项目\n\n扫描项目代码、依赖声明和规划文档，发现候选知识：\n\n| 来源 | 发现方式 | 示例 |\n|------|----------|------|\n| **项目自有能力** | 模式匹配扫描代码 | WorkflowEngine、EventBus |\n| **三方框架能力** | 扫描依赖声明文件 | Spring Cache、Redisson Lock |\n| **计划中能力** | 扫描 PRD/ROADMAP + 手动注册 | Rule Engine（规划中） |\n\n扫描完成后会列出候选清单，由你逐个确认/排除，确认后自动生成文档。\n\n**已有文档自动跳过**：`docs/capabilities/` 和 `docs/conventions/` 中已存在的文档不会重复分析（包括从外部导入的模块文档）。同模块下的新发现仍可补充。\n\n### `/pkr-sync` — 全量同步\n\n对比所有现有文档与代码/依赖现状，**智能检测变更**后批量更新：\n\n- **项目自有**：通过内容 hash（content_hash）检测关联源码是否变化，未变化则跳过\n- **三方框架**：通过依赖版本号检测，版本未变则跳过\n- **计划中**：完全忽略（计划中的能力不参与 sync）\n- 新增的 → 提示添加\n- 消失的 → 标记为 `已废弃`（不删除）\n- 变更的 → 幂等合并（事实以代码为准，人工编辑保留）\n\n### `/pkr-update \u003cmodule\u003e/\u003cname\u003e [description]` — 单项更新\n\n针对单个已注册的能力或规范文档，重新扫描代码并更新：\n\n```bash\n# 仅更新文档\n/pkr-update myapp/workflow-engine\n\n# 带描述信息，指导更新重点\n/pkr-update myapp/workflow-engine \"新增了重试机制和超时配置\"\n/pkr-update springboot/cache \"升级到 Caffeine 3.x\"\n```\n\n**参数说明**：\n- `\u003cmodule\u003e/\u003cname\u003e`（必填）：文档名称（格式 `module/short-name`）\n- `[description]`（可选）：变更描述，用于指导 Claude 重点关注哪些变化\n\n**description 的作用**：\n- 帮助 Claude 聚焦于你关心的变更点（如新增 API、配置项）\n- 在变更记录中作为变更摘要\n- 确保文档内容体现了描述中提到的功能\n\n适用于修改了某个能力后立即更新对应文档，比全量 sync 更快。\n\n### `/pkr-add \u003cmodule\u003e/\u003cname\u003e \u003cdescription\u003e` — 从代码注册\n\n从项目代码或三方框架中扫描查找能力，生成 `已实现` 文档：\n\n```bash\n# 指定名称注册\n/pkr-add myapp/retry-engine \"项目自有的重试引擎，支持指数退避和最大重试次数\"\n/pkr-add springboot/cache \"Spring Cache 声明式缓存能力\"\n\n# 自动生成名称（从扫描到的代码类名提取，如 RetryEngine → myapp/retry-engine）\n/pkr-add \"项目自有的重试引擎，支持指数退避\"\n/pkr-add \"项目的事件总线，基于 Guava EventBus 封装\"\n```\n\n**参数说明**：\n- `\u003cmodule\u003e/\u003cname\u003e`（可选）：格式 `module/short-name`，未提供时从代码自动提取\n- `\u003cdescription\u003e`（必填）：描述能力功能，指导扫描方向\n\nClaude 会自动判断来源是项目自有还是三方框架，扫描代码后展示结果供确认。\n\n### `/pkr-add plan \u003cmodule\u003e/\u003cname\u003e \u003cdescription\u003e` — 计划注册\n\n不扫描代码，基于描述生成 `计划中` 文档：\n\n```bash\n# 指定名称\n/pkr-add plan myapp/rule-engine \"基于 Drools 的业务规则引擎，支持规则定义和条件匹配\"\n\n# 自动生成名称（从描述提取核心名词，如\"消息中间件\" → myapp/message-queue）\n/pkr-add plan \"引入 RocketMQ 作为消息中间件，支持异步解耦\"\n/pkr-add plan \"升级版 Design Token 体系，支持暗黑主题\"\n```\n\n**参数说明**：\n- `plan`（必填）：路由关键词，标识为计划注册\n- `\u003cmodule\u003e/\u003cname\u003e`（可选）：格式 `module/short-name`，未提供时从描述自动提取\n- `\u003cdescription\u003e`（必填）：描述计划中能力的核心功能和预期设计\n\n## 文档格式\n\n每个 `.md` 文件使用统一格式：\n\n```markdown\n---\nname: workflow-engine\ndescription: 通用工作流引擎，支持流程定义、节点编排、状态流转\nstatus: 已实现\nscope: 后端\nsource: 项目自有\n---\n\n## 解决什么问题\n\n该能力/规范解决的核心痛点。\n\n## 如何使用\n\nAPI 说明、配置方式、依赖说明。\n\n## 使用实例\n\n具体代码示例。\n```\n\n### 字段说明\n\n**必填字段：**\n\n| 字段 | 值 | 说明 |\n|------|-----|------|\n| `name` | `module/short-name` | 文档名称，必须包含模块前缀（如 `myapp/workflow-engine`、`springboot/cache`） |\n| `module` | 模块名（必填） | 与子目录名一致。项目自有用项目模块名，框架用框架名 |\n| `description` | 一句话 | 简要描述 |\n| `status` | `已实现` / `计划中` / `已废弃` | 当前状态 |\n| `scope` | `前端` / `后端` / `全栈` | 适用范围 |\n| `source` | `项目自有` / `框架:{名称}` / `计划` | 知识来源 |\n| `import` | Maven GAV / npm 包路径 / 模块路径 | 导入坐标（复用此能力时需要的依赖声明） |\n\n**条件字段（sync 变更检测用）：**\n\n| source 类型 | 字段 | 说明 |\n|------------|------|------|\n| `项目自有` | `symbols` | 关联的代码符号列表（类名、函数名等），用于定位源码 |\n| `项目自有` | `content_hash` | 所有关联文件按路径排序拼接后的内容 hash，用于检测代码是否变化 |\n| `框架:{名称}` | `framework_version` | 依赖版本号，用于检测依赖是否升级 |\n\n## 目录结构（安装后）\n\n执行 `/pkr-create` 后，目标项目的 docs 目录结构：\n\n```\ndocs/\n├── capabilities/\n│   ├── index.md              # 自动生成，请勿手动编辑\n│   ├── myapp/                # 项目自有模块\n│   │   └── workflow-engine.md  # name: myapp/workflow-engine\n│   └── springboot/           # 框架模块\n│       ├── cache.md          # name: springboot/cache\n│       └── ioc.md            # name: springboot/ioc\n├── conventions/\n│   ├── index.md              # 自动生成，请勿手动编辑\n│   └── myapp/\n│       └── design-token.md\n└── agents/                   # 外部模块导出文档（由 /pkr-export 生成或从外部复制）\n    └── extlib/\n        ├── manifest.json\n        ├── capabilities/\n        └── conventions/\n```\n\n`index.md` 由 Hook 在每次文档写入/编辑后自动重建。\n\n## CLAUDE.md 集成\n\n`/pkr-create` 会自动在项目的 `CLAUDE.md` 中添加以下内容：\n\n```markdown\n## PKR 知识查阅（编码前必须）\n\n进入计划模式或实现功能前，必须查阅：\n1. [docs/capabilities/index.md](./docs/capabilities/index.md) — 已有可复用能力\n2. [docs/conventions/index.md](./docs/conventions/index.md) — 开发规范\n\n已有能力必须复用，禁止重新实现。编码必须遵循已注册的规范。\n```\n\n这确保 Claude 在每次编码前都会查阅 PKR 文档，形成知识驱动的编码流程。\n\n## 工作流程\n\n```\n┌─────────────────────────────────────────────────────────┐\n│  编码前                                                  │\n│  ↓                                                      │\n│  Claude 读取 CLAUDE.md                                  │\n│  ↓                                                      │\n│  查阅 docs/capabilities/index.md → 了解已有能力         │\n│  查阅 docs/conventions/index.md → 了解开发规范          │\n│  ↓                                                      │\n│  制定方案（复用已有能力、遵循规范）                     │\n│  ↓                                                      │\n│  编码实现                                               │\n│  ↓                                                      │\n│  编码后                                                 │\n│  ↓                                                      │\n│  /pkr-update \u003cname\u003e [desc] → 更新能力文档               │\n│  /pkr-add [name] \u003cdesc\u003e → 从代码注册（名称可自动提取）  │\n│  /pkr-add plan [name] \u003cdesc\u003e → 计划注册（名称可自动生成）│\n└─────────────────────────────────────────────────────────┘\n```\n\n## 开发本项目\n\n本项目是插件市场项目，不直接使用 PKR。开发时参考 [CLAUDE.md](./CLAUDE.md)。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodingapi%2Fpkr-marketplace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodingapi%2Fpkr-marketplace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodingapi%2Fpkr-marketplace/lists"}