# kb

**Repository Path**: suveng/kb

## Basic Information

- **Project Name**: kb
- **Description**: kbasdfasdf
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-06-09
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# kb-workflow — Claude Code 插件

知识库驱动开发工作流：`/kb-propose` → `/kb-design` → `/kb-plan` → `/kb-apply` → `/kb-review` → `/kb-test` → `/kb-archive`（标准流 apply 后强制 review+可执行 test；`/kb-test` 验收分层 **Playwright UI > 契约 > 既有 unit**；lite 豁免）；归档默认可保留，可选运维 `/kb-archive-purge`（retention 批清 + `归档/.tombstones/`）。外部登记/通知为**可选**，通过 `kb.project.json` → `integrations` + 扩展 provider 插件实现。

通过 `.claude-plugin/` 市场清单分发；Cursor 会通过 `cc-marketplace-import` 自动导入同一市场。

**版本与升级**：[CHANGELOG.md](CHANGELOG.md)（摘要 / 影响范围 / 业务仓动作）· [SOP §八](plugin/skills/kb-workflow/SOP.md) · [发布清单](docs/RELEASE.md)

## 安装

**推荐项目级**（仅当前业务仓生效，声明写入 `.claude/settings.json`）：

```bash
claude plugin marketplace add https://gitee.com/suveng/kb.git --scope project
claude plugin install kb-workflow@doger-kb-plugins --scope project
```

本地开发调试 marketplace 源仓时，将上述 URL 换为本地路径 `/path/to/kb`，同样加 `--scope project`。

重启 Cursor 后，Marketplace 面板会出现 **doger-kb-plugins**。详见：[docs/CLAUDE_MARKETPLACE.md](docs/CLAUDE_MARKETPLACE.md)

> **不推荐**用户级（`--scope user`）安装：全局生效易与多项目混淆；卸载用 `claude plugin uninstall kb-workflow@doger-kb-plugins --scope user -y`。

## 开发者速览

1. 完成上述 `marketplace add` 与 `plugin install`
2. 在业务项目执行 bootstrap（安装插件后 `${CLAUDE_PLUGIN_ROOT}` 可用）：

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/kb-bootstrap.mjs" --target "$(pwd)"
```

或直接使用 `/kb-init` 命令。

3. 编辑 `kb.project.json` 的 `codeRoots`；若需外部登记/通知，安装对应 integration 插件并配置 `integrations.*.handler`
4. 按当前宿主复制一份 MCP 示例、建立 CodeGraph 索引并 Reload / 重启会话（见下文「CodeGraph MCP」）

## CodeGraph MCP

KB 工作流依赖 CodeGraph 作为代码事实入口（`/kb-design`、`/kb-explore` 等）。插件**不再**通过 `plugin/.mcp.json` 或 `plugin.json` 的 `mcpServers` 强制注入 MCP；业务仓须自行配置**项目级 MCP**，再建立索引并通过门禁。

1. **按当前宿主复制 MCP 示例**（bootstrap **不**自动写入；**禁止**无脑双写；双 IDE 须用户明示）：

| IDE / 宿主 | 示例 | 复制到 |
|-----|------|--------|
| Claude Code / 其他 | `${CLAUDE_PLUGIN_ROOT}/bootstrap/examples/mcp/claude.mcp.json` | 业务仓根 `.mcp.json` |
| Cursor | `${CLAUDE_PLUGIN_ROOT}/bootstrap/examples/mcp/cursor.mcp.json` | `.cursor/mcp.json` |

可选：将示例中的 npx 直连改为 `${CLAUDE_PLUGIN_ROOT}/scripts/codegraph-mcp.cjs` launcher（见 `bootstrap/examples/mcp/README.md`）。细则：`plugin/skills/kb-workflow/references/kb-codegraph.md` §一。

2. **索引**（业务仓根目录）：

```bash
npx -y @colbymchenry/codegraph@0.9.3 init
npx -y @colbymchenry/codegraph@0.9.3 index
```

将 `.codegraph/` 加入 `.gitignore`。Cursor Reload Window / Claude 重启会话后确认 `codegraph_*` 工具可用。

3. **门禁**：

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/kb-codegraph-check.mjs" --target "$(pwd)"
```

硬门禁：`design` / `plan` / `apply` / `revise-apply` / `review` / `archive` / `explore` / `query` / `sync` / `verify-issue`；`check` / `health` 警告；`propose` 禁止。

细则见 `plugin/skills/kb-workflow/references/kb-codegraph.md`。

## 插件内容（`plugin/`）

| 组件 | 说明 |
|------|------|
| `skills/kb-workflow/` | 流程规范（SKILL + references） |
| `commands/kb-*.md` | 斜杠命令（Claude 中带命名空间，如 `/kb-workflow:kb-propose`） |
| `agents/kb-*.md` | 8 个工种 Agent（kb-admin 调度 + scribe/builder/reviewer 等） |
| `scripts/` | bootstrap、OKF/图谱 migrate/check、可选 CodeGraph launcher `codegraph-mcp.cjs`、门禁 `kb-codegraph-check.mjs`、external-sync dispatcher、归档批清 `kb-archive-purge.mjs`（`${CLAUDE_PLUGIN_ROOT}/scripts/`） |
| `bootstrap/`、`schema/` | bootstrap 写入业务仓的骨架与 manifest schema |
| `bootstrap/examples/mcp/` | 项目级 CodeGraph MCP 可复制示例（Claude / Cursor）；bootstrap **不**自动写入业务仓 |

**不在插件包内、由 bootstrap 写入业务仓：**

| 路径 | 说明 |
|------|------|
| `knowledge/**` | 业务知识正文 |
| `kb.project.json` | 路径与 integrations 约定 |
| `.kb/kb-manifest.schema.json` | manifest JSON Schema |
| `.kb/kb-concept-frontmatter.schema.json` | 概念文件 `related` / `depends_on` 校验 |

**外部 provider** 不在本 marketplace 内置；由扩展插件写入 `.kb/providers/` 并在 `kb.project.json` 的 `integrations.*.handler` 登记。

## 迭代与发布

在 `plugin/` 直接改命令、Agent、Skill、scripts 等，然后按 **正常版本迭代**（详见 [docs/RELEASE.md](docs/RELEASE.md)）：

1. **写更新日志**：在 [CHANGELOG.md](CHANGELOG.md) **最上方**追加版本节——变更摘要、影响范围、业务仓动作、相关文档链接；更旧版本按 [docs/RELEASE.md](docs/RELEASE.md) §2.1 归档。
2. **同步手册**：按影响更新 [SOP.md](plugin/skills/kb-workflow/SOP.md)、相关 commands/references、本 README、[docs/CLAUDE_MARKETPLACE.md](docs/CLAUDE_MARKETPLACE.md)。
3. **bump 版本号**（两处保持一致）：
   - `.claude-plugin/marketplace.json` → `plugins[].version`
   - `plugin/.claude-plugin/plugin.json` → `version`
4. commit → push Gitee
5. 本机 / 团队执行：

```bash
claude plugin marketplace update doger-kb-plugins
claude plugin update kb-workflow@doger-kb-plugins --scope project
```

6. Cursor：**Developer: Reload Window**
7. 团队按 CHANGELOG 该节的「业务仓动作」执行（若有迁移/配置）。

详见 [docs/CLAUDE_MARKETPLACE.md](docs/CLAUDE_MARKETPLACE.md) §五。

## 本地开发

```bash
claude plugin marketplace add /path/to/kb --scope project
claude plugin install kb-workflow@doger-kb-plugins --scope project
```

本地开发勿同时 `marketplace add` Gitee 源与上述本地路径 add，否则会重复显示插件。本 marketplace **源仓**的 `.claude/settings.json` 已在 `.gitignore` 中，不入库；业务仓若用 Gitee URL 做 `--scope project`，可将 `.claude/settings.json` 提交给团队。

**不要**在 Cursor Dashboard → Settings → Plugins 再导入同一 Gitee 仓库，否则会出现两个 kb-workflow。

若出现两个 kb-workflow 或命令无法识别：

```bash
rm -rf ~/.cursor/plugins/local/kb-workflow
rm -rf ~/.cursor/plugins/marketplaces/gitee.com/suveng/kb
claude plugin marketplace update doger-kb-plugins
```

然后在 Cursor Dashboard 删除 Team Marketplace 中的重复源，Reload Window，在面板只保留一个 kb-workflow。

## 升级说明

升级说明与影响范围以根目录 [CHANGELOG.md](CHANGELOG.md) 为唯一入口；团队日常操作见 [SOP §八](plugin/skills/kb-workflow/SOP.md)。

### 破坏性升级（以 CHANGELOG 最新一节为准）

始终以根 [CHANGELOG.md](CHANGELOG.md) **最新一节**为准：若「影响范围」中标注 `是否 breaking = 是`，按该节「业务仓动作」执行。历史示例见 [docs/changelog/](docs/changelog/)（如 [0.4.0 OKF](docs/changelog/2026.md#040--2026-07-12)、[0.5.0 知识图谱](CHANGELOG.md#050--2026-07-12)）。

**常见 OKF/图谱迁移**（仅当 CHANGELOG 或 SOP 指向时执行；插件 update + Reload 后）：

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/kb-okf-migrate.mjs" --target "$(pwd)" --dry-run
node "${CLAUDE_PLUGIN_ROOT}/scripts/kb-okf-migrate.mjs" --target "$(pwd)" --apply
node "${CLAUDE_PLUGIN_ROOT}/scripts/kb-okf-check.mjs" --target "$(pwd)"
```

migrate 将 `[text](path.md)` 转为 `[[wikilink]]` 并补空关系字段与 `## 相关`；check 校验 OKF 布局与图谱一致性。亦可 `/kb-okf-migrate`、`/kb-check`、`/kb-health`，按需 `/kb-index`。完整条目见 [CHANGELOG 0.4.0](docs/changelog/2026.md#040--2026-07-12)；最新版见 [CHANGELOG.md](CHANGELOG.md)。