kcode-pi 0.1.0

package/README.md

@@ -0,0 +1,358 @@
+# KCodeV2
+
+KCodeV2 是面向金蝶开发的 Pi package 和企业启动器原型。
+
+它不 fork Pi，也不替换 Pi 生态。当前仓库主要提供：
+
+- 金蝶专属 tools、skills、prompts、themes。
+- 金蝶 Harness Engineering 工作流。
+- 官方金蝶 skills 的 vendor 资源和 Pi 适配器。
+- `kcode` 企业入口，用项目级 `.pi/settings.json` 加载 KCode package，并通过随包 Pi CLI 启动工作环境。
+
+## 当前定位
+
+当前仓库是：
+
+```text
+kcode-pi
+```
+
+也就是金蝶 Pi package，同时包含 `kcode-cli` 的仓库内原型。
+
+仓库内的 `npm run kcode -- ...` 是启动器原型，用于验证 `kcode-cli` 的设计。企业入口由两部分组成：
+
+```text
+kcode-pi   金蝶 Pi package，本仓库
+kcode-cli  企业启动器，自动携带 Pi CLI，并启动 KCode 工作环境
+```
+
+## 环境要求
+
+- Node.js `>=22.19.0`
+- npm
+- Pi CLI 由 KCode 运行依赖自动携带
+
+当前机器如果没有全局 `pi` 命令，`kcode start` 会优先使用随包的 Pi CLI。
+
+检查 KCode 能否找到 Pi CLI：
+
+```powershell
+npm run kcode -- doctor
+```
+
+## 快速开始
+
+发布到 npm 后，开发者可以直接全局安装：
+
+```powershell
+npm install -g kcode-pi
+```
+
+安装后会得到全局 `kcode` 命令。进入业务项目根目录，初始化 KCode 工作环境：
+
+```powershell
+kcode init
+```
+
+检查 Node、随包 Pi CLI 和项目级配置：
+
+```powershell
+kcode doctor
+```
+
+启动 KCode 工作环境：
+
+```powershell
+kcode start
+```
+
+如果发布时改用 `kcode-cli` 或 `@kingdee/kcode-cli` 包名，把安装命令中的 `kcode-pi` 替换为实际包名即可；全局命令仍是 `kcode`。
+
+## 源码开发
+
+需要修改 KCodeV2 本身时，再 clone 仓库并安装依赖：
+
+```powershell
+git clone <KCodeV2仓库地址>
+cd KCodeV2
+npm install
+```
+
+源码仓库内可以用 npm script 调试同一个入口：
+
+```powershell
+npm run kcode -- doctor
+npm run kcode -- init
+npm run kcode -- start
+```
+
+## 安装依赖
+
+在仓库根目录执行：
+
+```powershell
+npm install
+```
+
+## 本地验证
+
+常用检查：
+
+```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:package
+npm run smoke:kcode-cli
+```
+
+这些 smoke 分别验证：
+
+- TypeScript 类型检查。
+- 金蝶知识库搜索。
+- `kd_check` 静态规则。
+- Harness 阶段和门禁。
+- 官方脚本适配器。
+- 构建/调试诊断。
+- package manifest、skills、vendor 文件完整性。
+- `kcode` 项目级入口逻辑。
+
+## KCode 企业入口原型
+
+当前仓库提供 `kcode` 命令。发布后可直接运行全局命令；源码调试时使用 `npm run kcode -- ...`。它不会写用户全局 Pi 配置，只管理当前项目的 `.pi/settings.json`：
+
+```powershell
+kcode init
+kcode doctor
+kcode start
+```
+
+### `kcode init`
+
+初始化当前项目的 Pi 配置：
+
+```powershell
+kcode init
+```
+
+它只写当前项目：
+
+```text
+.pi/settings.json
+```
+
+不会修改用户全局 Pi 配置。
+
+生成内容会把当前 KCodeV2 package 加入项目级 packages，例如：
+
+```json
+{
+  "packages": [
+    "E:\\projects\\kingdee\\KCodeV2"
+  ]
+}
+```
+
+### `kcode doctor`
+
+检查当前环境：
+
+```powershell
+kcode doctor
+```
+
+它会检查：
+
+- Node 版本。
+- 是否能找到随包 Pi CLI。
+- KCode package 路径。
+- 当前项目 `.pi/settings.json` 是否存在。
+- KCode package 是否已写入项目级配置。
+
+### `kcode start`
+
+初始化项目配置后启动 KCode 工作环境：
+
+```powershell
+kcode start
+```
+
+`kcode start` 会先写入项目级 `.pi/settings.json`，再优先通过随包 `@earendil-works/pi-coding-agent` 的 CLI 启动 Pi；只有随包 CLI 不存在时才回退全局 `pi`。传给 `start` 的后续参数会原样透传给 Pi CLI。
+
+## Pi 内使用方式
+
+安装到 Pi 后，KCodeV2 提供以下命令：
+
+```text
+/kd-start [--product product] [--version version] <goal>
+/kd-product <product> [--version version]
+/kd-status
+/kd-gate
+/kd-advance [phase]
+/kd-artifact [phase] [content]
+```
+
+工作流阶段：
+
+```text
+discuss -> spec -> plan -> execute -> verify -> ship
+```
+
+运行状态保存在：
+
+```text
+.pi/kd/active-run.json
+.pi/kd/runs/<run-id>/
+```
+
+## 金蝶工具
+
+当前注册的主要工具：
+
+```text
+kd_plan_status      查看当前 Harness run、阶段、产物和门禁
+kd_search           搜索内置金蝶 SDK 知识和代码模式
+kd_table            查询内置金蝶表结构
+kd_check            检查金蝶 Java/C# 插件代码
+kd_cosmic_config    运行官方 ok-cosmic 配置预检
+kd_cosmic_metadata  查询官方 Cosmic 表单/单据元数据
+kd_cosmic_api       查询官方 Cosmic API 签名和方法
+kd_ksql_lint        运行官方 ok-ksql SQL/KSQL lint
+kd_build            按产品画像执行或 dry-run 构建
+kd_debug            分析金蝶日志和堆栈
+```
+
+## 产品画像
+
+KCodeV2 会区分金蝶产品和技术栈：
+
+```text
+cosmic     -> Cosmic 平台底座
+cangqiong  -> Cosmic / Java
+xinghan    -> Cosmic / Java
+flagship   -> Cosmic / Java
+enterprise -> Enterprise / C#
+```
+
+未知产品不能离开 `discuss` 阶段。不要把 Cosmic Java API 和 Enterprise C# API 混用。
+
+## 官方 skills 资源
+
+官方金蝶 skills 以 vendor 形式保存在：
+
+```text
+vendor/kingdee-skills
+```
+
+包含：
+
+```text
+ok-cosmic
+ok-ksql
+kingdee-cosmic-reviewer
+cosmic-unittest
+```
+
+运行时默认使用包内 vendor 目录。本地开发可通过环境变量覆盖：
+
+```powershell
+$env:KCODE_KINGDEE_SKILLS_ROOT="E:\projects\kingdee\skills"
+```
+
+## 官方证据与门禁
+
+官方工具在存在 active run 时会写入证据：
+
+```text
+.pi/kd/runs/<run-id>/evidence/cosmic-config.txt
+.pi/kd/runs/<run-id>/evidence/cosmic-metadata.json
+.pi/kd/runs/<run-id>/evidence/cosmic-api.txt
+.pi/kd/runs/<run-id>/evidence/ksql-lint.txt
+```
+
+当前门禁规则：
+
+- Cosmic 体系进入 `execute` 前必须有配置证据。
+- `PLAN.md` 声明字段/元数据验证时，进入 `execute` 前必须有 metadata 证据。
+- `PLAN.md` 声明 API/方法签名验证时，进入 `execute` 前必须有 API 证据。
+- KSQL/数据修复交付进入 `ship` 前必须有 metadata 和 lint 证据。
+
+## Skills
+
+Pi-native skills 位于：
+
+```text
+skills/
+```
+
+核心金蝶 skills：
+
+```text
+kd-cosmic-dev
+kd-cosmic-review
+kd-cosmic-unittest
+kd-ksql
+kd-gen
+kd-check
+kd-plan
+kd-execute
+kd-verify
+kd-ship
+```
+
+新增和维护文档、注释时，默认使用中文。
+
+## 打包策略
+
+当前不内置第三方 Pi packages。
+
+推荐策略：
+
+- 不 fork Pi。
+- 不改用户全局 Pi 配置。
+- 第三方 Pi package 先进入 allowlist，再写入项目级 `.pi/settings.json`。
+- 只有离线交付或强依赖时，才考虑 `dependencies` + `bundledDependencies` 内置。
+
+详细方案见：
+
+```text
+docs/KCODE_DISTRIBUTION.md
+```
+
+## 发布 npm 包
+
+发布前确认 `package.json` 中的包名、版本和 npm registry。当前包名是 `kcode-pi`，也可以发布前改成企业内约定的 `kcode-cli` 或 `@kingdee/kcode-cli`。
+
+发布检查：
+
+```powershell
+npm run check
+npm run build:cli
+npm run smoke:package
+npm pack --dry-run
+```
+
+发布：
+
+```powershell
+npm publish
+```
+
+`prepack` 会自动执行 `build:cli` 和 `smoke:package`，确保发布包里有全局 `kcode` 入口和随包 Pi CLI 运行依赖。
+
+## 当前限制
+
+- 当前仓库可以直接发布为 npm 包，但包名仍是 `kcode-pi`；如果企业侧要叫 `kcode-cli`，发布前需要调整 `package.json.name`。
+- 更深层的 reviewer 语义规则、HTML 审查报告、自动 SQL 产物生成仍在后续计划中。
+
+## 状态文档
+
+集成进度见：
+
+```text
+OFFICIAL_SKILLS_STATUS.md
+```

package/dist/cli/kcode.d.ts

@@ -0,0 +1,15 @@
+export interface KcodeCliResult {
+    exitCode: number;
+    output: string;
+}
+export interface PiCliCommand {
+    command: string;
+    args: string[];
+    source: "bundled" | "global";
+    displayPath: string;
+}
+export declare function runKcodeCli(args: string[], cwd?: string): KcodeCliResult;
+export declare function initProject(cwd: string): KcodeCliResult;
+export declare function doctor(cwd: string): KcodeCliResult;
+export declare function start(cwd: string, piArgs: string[]): KcodeCliResult;
+export declare function resolvePiCliCommand(piArgs?: string[]): PiCliCommand | undefined;

package/dist/cli/kcode.js

@@ -0,0 +1,153 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+const packageRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const require = createRequire(import.meta.url);
+export function runKcodeCli(args, cwd = process.cwd()) {
+    const command = args[0] ?? "help";
+    switch (command) {
+        case "init":
+            return initProject(cwd);
+        case "doctor":
+            return doctor(cwd);
+        case "start":
+            return start(cwd, args.slice(1));
+        case "help":
+        case "--help":
+        case "-h":
+            return { exitCode: 0, output: helpText() };
+        default:
+            return { exitCode: 1, output: `未知命令：${command}\n\n${helpText()}` };
+    }
+}
+export function initProject(cwd) {
+    const settingsPath = projectSettingsPath(cwd);
+    const settings = readSettings(settingsPath);
+    const kcodePackage = normalizePath(packageRoot);
+    const packages = settings.packages ?? [];
+    if (!packages.includes(kcodePackage)) {
+        packages.unshift(kcodePackage);
+    }
+    settings.packages = packages;
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+    return {
+        exitCode: 0,
+        output: [`已更新项目级 Pi 配置：${settingsPath}`, `已加入 KCode package：${kcodePackage}`].join("\n"),
+    };
+}
+export function doctor(cwd) {
+    const lines = [];
+    const node = spawnSync("node", ["--version"], { encoding: "utf8" });
+    const piCli = resolvePiCliCommand(["--version"]);
+    const pi = piCli ? spawnSync(piCli.command, piCli.args, { encoding: "utf8" }) : undefined;
+    const settingsPath = projectSettingsPath(cwd);
+    lines.push(`Node：${node.status === 0 ? node.stdout.trim() : "未找到"}`);
+    lines.push(`Pi CLI：${formatPiCliStatus(piCli, pi)}`);
+    lines.push(`KCode package：${packageRoot}`);
+    lines.push(`项目配置：${existsSync(settingsPath) ? settingsPath : "未创建，请先运行 kcode init"}`);
+    if (existsSync(settingsPath)) {
+        const settings = readSettings(settingsPath);
+        const hasKcode = (settings.packages ?? []).includes(normalizePath(packageRoot));
+        lines.push(`KCode package 已登记：${hasKcode ? "是" : "否"}`);
+    }
+    return {
+        exitCode: pi?.status === 0 ? 0 : 1,
+        output: lines.join("\n"),
+    };
+}
+export function start(cwd, piArgs) {
+    const init = initProject(cwd);
+    const piCli = resolvePiCliCommand(piArgs);
+    if (!piCli) {
+        return {
+            exitCode: 1,
+            output: `${init.output}\n未找到随包 Pi CLI 或全局 pi 命令。请重新安装 kcode-cli 后再运行 kcode start。`,
+        };
+    }
+    const pi = spawnSync(piCli.command, piCli.args, { cwd, stdio: "inherit", shell: false });
+    if (pi.error || pi.status === null) {
+        return {
+            exitCode: 1,
+            output: `${init.output}\nPi CLI 启动失败：${pi.error?.message ?? piCli.displayPath}`,
+        };
+    }
+    return {
+        exitCode: pi.status,
+        output: init.output,
+    };
+}
+export function resolvePiCliCommand(piArgs = []) {
+    const bundledPi = bundledPiCliPath();
+    if (bundledPi) {
+        return {
+            command: process.execPath,
+            args: [bundledPi, ...piArgs],
+            source: "bundled",
+            displayPath: bundledPi,
+        };
+    }
+    return {
+        command: "pi",
+        args: piArgs,
+        source: "global",
+        displayPath: "pi",
+    };
+}
+function projectSettingsPath(cwd) {
+    return join(cwd, ".pi", "settings.json");
+}
+function readSettings(path) {
+    if (!existsSync(path))
+        return {};
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function normalizePath(path) {
+    return resolve(path);
+}
+function bundledPiCliPath() {
+    const directPath = join(packageRoot, "node_modules", "@earendil-works", "pi-coding-agent", "dist", "cli.js");
+    if (existsSync(directPath))
+        return directPath;
+    try {
+        const mainPath = require.resolve("@earendil-works/pi-coding-agent");
+        const packageDir = dirname(dirname(mainPath));
+        const cliPath = join(packageDir, "dist", "cli.js");
+        return existsSync(cliPath) ? cliPath : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function formatPiCliStatus(piCli, result) {
+    if (!piCli || result?.status !== 0) {
+        return "未找到";
+    }
+    const version = result.stdout?.toString().trim() || result.stderr?.toString().trim() || piCliPackageVersion(piCli) || "可用";
+    const source = piCli.source === "bundled" ? "随包" : "全局";
+    return `${version}（${source}：${piCli.displayPath}）`;
+}
+function piCliPackageVersion(piCli) {
+    if (piCli.source !== "bundled")
+        return undefined;
+    try {
+        const packageJsonPath = join(dirname(dirname(piCli.displayPath)), "package.json");
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        return packageJson.version;
+    }
+    catch {
+        return undefined;
+    }
+}
+function helpText() {
+    return [
+        "KCode 企业入口",
+        "",
+        "用法：",
+        "  kcode init      初始化当前项目的 .pi/settings.json",
+        "  kcode doctor    检查 Node、随包 Pi CLI、KCode package 和项目级配置",
+        "  kcode start     初始化项目配置后启动 KCode 工作环境",
+    ].join("\n");
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/main.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runKcodeCli } from "./kcode.js";
+const result = runKcodeCli(process.argv.slice(2));
+if (result.output) {
+    console.log(result.output);
+}
+process.exitCode = result.exitCode;

package/docs/KCODE_DISTRIBUTION.md

@@ -0,0 +1,91 @@
+# KCode 发行版方案
+
+## 目标
+
+KCode 不 fork Pi，也不替换 Pi 生态。KCode 提供一个企业入口，自动携带 Pi CLI，并把 KCodeV2 和经过审查的 Pi packages 以项目级配置方式组合起来。
+
+核心目标：
+
+- 保留原生 Pi 的安装、升级、package 管理和用户生态。
+- 不修改用户全局 Pi 配置。
+- 不强制安装未审查的第三方 package。
+- 支持项目内复现同一套金蝶开发环境。
+- 不要求用户额外安装全局 `pi` 命令。
+
+## 推荐结构
+
+```text
+kcode-pi     当前仓库，作为 Pi package 提供金蝶工具、skills、prompts、themes。
+kcode cli    启动器，负责项目初始化、环境检查和启动随包 Pi CLI。
+```
+
+`kcode` 启动器只管理当前项目的 `.pi/settings.json`，不写 `~/.pi` 或其他用户全局目录。启动时优先调用随包 `@earendil-works/pi-coding-agent` 的 `dist/cli.js`，仅在随包 CLI 缺失时回退全局 `pi`。
+
+## 项目级配置
+
+`kcode init` 生成或更新当前项目：
+
+```text
+.pi/settings.json
+```
+
+默认只写入当前 KCodeV2 package：
+
+```json
+{
+  "packages": [
+    "E:\\projects\\kingdee\\KCodeV2"
+  ]
+}
+```
+
+后续如需接入第三方 Pi package，先进入 allowlist，再固定版本写入项目配置：
+
+```json
+{
+  "packages": [
+    "E:\\projects\\kingdee\\KCodeV2",
+    "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 init      初始化当前项目的 .pi/settings.json
+kcode doctor    检查 Node、随包 Pi CLI、KCode package、项目级 settings
+kcode start     初始化后启动 KCode 工作环境
+```
+
+## 不破坏 Pi 生态的边界
+
+- 不 fork Pi 核心。
+- 不改用户全局 Pi 配置。
+- 不覆盖用户已安装 package。
+- 不自动安装未在 allowlist 中的 package。
+- 不把第三方 package 静默 bundle 进 KCodeV2。
+- 所有新增 package 固定版本，变更必须记录。
+
+## 当前限制
+
+当前仍是仓库内启动器原型，尚未拆成独立 npm 全局包。真实交互式 Pi runtime smoke 需要在具备可用模型/API 配置的环境中执行。