# KCode 发行版方案

## 目标

KCode 不 fork Pi，也不替换 Pi 生态。KCode 提供一个面向金蝶开发的入口，自动携带 Pi CLI，并把 KCode package 和经过审查的 Pi packages 以项目级配置方式组合起来。

核心目标：

- 保留原生 Pi 的安装、升级、package 管理和用户生态。
- 不修改用户全局 Pi 配置。
- 不强制安装未审查的第三方 package。
- 支持项目内复现同一套金蝶开发环境。
- 无需用户额外安装全局 `pi` 命令。

## 分发结构

```text
kcode-pi     npm 包，作为 Pi package 提供金蝶工具、skills、prompts、themes。
kcode        全局命令，负责项目初始化、环境检查和启动随包 Pi CLI。
```

`kcode` 启动器只管理当前项目的 `.pi/settings.json`，不写 `~/.pi` 或其他用户全局目录。启动时默认调用随包 `@earendil-works/pi-coding-agent` 的 `dist/cli.js`，仅在随包 CLI 缺失时回退全局 `pi`。

## 项目级配置

`kcode init` 生成或更新当前项目：

```text
.pi/settings.json
```

默认只写入当前安装的 KCode package 路径：

```json
{
  "packages": [
    "<当前 kcode-pi 安装路径>"
  ]
}
```

后续接入第三方 Pi package 时，进入 allowlist 后再固定版本写入项目配置：

```json
{
  "packages": [
    "<当前 kcode-pi 安装路径>",
    "npm:pi-subagents@1.2.3"
  ]
}
```

## 第三方 package 策略

默认不内置第三方 package。

允许接入前必须检查：

- package 来源和维护状态。
- license 是否允许随包分发和商业使用。
- 是否注册 extensions、hooks、commands、tools。
- 是否写全局配置或访问敏感路径。
- 是否与 KCode harness、权限策略、上下文策略冲突。

通过审查后有两种接入方式：

1. 项目级安装：写入 `.pi/settings.json`。
2. 离线内置：写入 `dependencies` 和 `bundledDependencies`，并在 `package.json -> pi` 中显式引用其资源。

默认使用项目级安装。只有离线交付或强依赖时，才允许考虑离线内置。

## 命令设计

```text
kcode           自动初始化、检查环境后启动 KCode 工作环境
kcode -v        显示版本
```

## 不破坏 Pi 生态的边界

- 不 fork Pi 核心。
- 不改用户全局 Pi 配置。
- 不覆盖用户已安装 package。
- 不自动安装未在 allowlist 中的 package。
- 不把第三方 package 静默 bundle 进 KCode。
- 所有新增 package 固定版本，变更必须记录。

## 当前限制

当前仓库已可作为 npm 包发布，并提供全局 `kcode` 命令。真实交互式 Pi runtime smoke 必须在具备可用模型/API 配置的环境中执行。