# KCode 开发与发布说明

本文档面向 KCode 维护者。用户安装和使用说明见根目录 `README.md`。

## 源码开发

克隆仓库并安装依赖：

```powershell
git clone https://github.com/wangneal/kcode-pi.git
cd KCodeV2
npm install
```

源码仓库内可用 npm script 调试同一个入口：

```powershell
npm run kcode -- doctor
npm run kcode -- init
npm run kcode -- start
```

## 本地验证

常用检查：

```powershell
npm run check
npm run build:cli
npm run smoke:knowledge
npm run smoke:checker
npm run smoke:harness
npm run smoke:official
npm run smoke:build-debug
npm run smoke:sdk-signature
npm run smoke:package
npm run smoke:kcode-command
npm run release:check
```

这些 smoke 分别验证：

- TypeScript 类型检查。
- CLI 构建产物。
- 金蝶知识库搜索。
- `kd_check` 静态规则。
- Harness 阶段和门禁。
- 官方能力 Node 适配器。
- 构建/调试诊断。
- 当前项目 SDK jar/dll 签名读取。
- package manifest、skills、vendor 文件完整性。
- `kcode` 项目级入口逻辑。

## CLI 构建

全局 `kcode` 命令来自：

```text
src/cli/main.ts
```

构建输出：

```text
dist/cli/main.js
dist/cli/kcode.js
```

构建命令：

```powershell
npm run build:cli
```

`package.json` 中的关键发布字段：

```json
{
  "bin": {
    "kcode": "./dist/cli/main.js"
  },
  "files": [
    "dist",
    "src",
    "extensions",
    "skills",
    "prompts",
    "themes",
    "knowledge",
    "vendor",
    "docs/KCODE_DISTRIBUTION.md",
    "README.md"
  ]
}
```

注意：`extensions/*.ts` 运行时会引用 `../src/**`，因此发布包必须包含 `src`。

## 发布 npm 包

发布前确认：

- `package.json.name` 是预期包名。
- `package.json.version` 已递增。
- npm registry 指向正确位置。
- `npm pack --dry-run` 包含 `dist`、`src`、`extensions`、`skills`、`prompts`、`themes`、`knowledge`、`vendor`。

发布检查：

```powershell
npm run release:check
```

发布：

```powershell
npm publish
```

使用 scoped 包并发布到公网 npm 时：

```powershell
npm publish --access public
```

`prepack` 会自动执行：

```powershell
npm run build:cli
npm run smoke:package
```

## 发行策略

KCode 不 fork Pi，也不替换 Pi 生态。KCode 作为 Pi package 提供金蝶工具、skills、prompts、themes 和知识库；`kcode` 启动器负责项目初始化、环境检查和启动随包 Pi CLI。

详细发行边界见：

```text
docs/KCODE_DISTRIBUTION.md
```

## 第三方 Pi package 策略

默认不内置第三方 Pi packages。

允许接入前必须检查：

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

通过审查后默认使用项目级安装，写入 `.pi/settings.json`。只有离线交付或强依赖时，才允许考虑 `dependencies` + `bundledDependencies` 内置。

## 当前维护事项

- 当前包名是 `kcode-pi`，全局命令是 `kcode`。
- 更深层的 reviewer 语义规则、HTML 审查报告、自动 SQL 产物生成仍在后续计划中。
- 集成进度见根目录 `OFFICIAL_SKILLS_STATUS.md`。