kcode-pi 0.1.2 → 0.1.5

package/knowledge/enterprise-python/python-plugin.md

@@ -0,0 +1,134 @@
+# Enterprise Python Plugin
+
+Enterprise Python plugin work is enabled only when the user explicitly asks for a Python plugin, IronPython, or a BOS/Enterprise Python script. Normal enterprise plugin requests use the C# BOS stack.
+
+## Runtime And Scope
+
+Kingdee Cloud Enterprise Python plugins run through IronPython inside BOS and call .NET assemblies such as `Kingdee.BOS`, `Kingdee.BOS.Core`, `Kingdee.BOS.App`, `Kingdee.BOS.Contracts`, and `Kingdee.BOS.ServiceHelper`.
+
+Use Python plugins for form/list/operation/report/convert scripting when BOS registration supports it. Do not use Python for server interfaces, scheduled execution plans, or scenarios that require inheriting and overriding standard C# plugins; those remain C# work.
+
+## Required Planning Facts
+
+Before coding, confirm:
+
+- The user explicitly requested a Python plugin, IronPython, or a BOS/Enterprise Python script.
+- Plugin type: bill/form, list, operation service, report service, report form, or convert plugin.
+- Target FormId, bill/entity, field keys, entity keys, operation code, and lifecycle event.
+- Whether the script will be registered in BOS and where the project stores Python scripts.
+- How to test in a BOS test data center.
+
+## Common References
+
+Typical imports:
+
+```python
+import clr
+clr.AddReference('System')
+clr.AddReference('System.Data')
+clr.AddReference('Kingdee.BOS')
+clr.AddReference('Kingdee.BOS.Core')
+clr.AddReference('Kingdee.BOS.App')
+clr.AddReference('Kingdee.BOS.Contracts')
+clr.AddReference('Kingdee.BOS.ServiceHelper')
+
+from Kingdee.BOS import *
+from Kingdee.BOS.Core import *
+from Kingdee.BOS.Core.Bill import *
+from Kingdee.BOS.Core.DynamicForm.PlugIn import *
+from Kingdee.BOS.Core.DynamicForm.PlugIn.Args import *
+from Kingdee.BOS.Core.DynamicForm.PlugIn.ControlModel import *
+from Kingdee.BOS.App.Data import *
+from Kingdee.BOS.ServiceHelper import *
+from System.Collections.Generic import List
+```
+
+Use English punctuation and strict indentation. IronPython code does not use `new`; instantiate with `TypeName()`. Generic lists use forms such as `List[object]()` or `List[DynamicObject]()`.
+
+## DynamicObject Patterns
+
+Form plugins can read the current bill data from:
+
+```python
+billObj = this.View.Model.DataObject
+```
+
+Base data fields return `DynamicObject`; read properties such as `Number`, `Name`, or `Id`. Base data ID fields often use the suffix `_Id`.
+
+Entry entities are usually `DynamicObjectCollection`:
+
+```python
+entryRows = billObj["POOrderEntry"]
+for row in entryRows:
+    materialId = row["MaterialId_Id"]
+    qty = row["Qty"]
+```
+
+When assigning base data, set both the ID and the data object when required:
+
+```python
+field = this.View.BillBusinessInfo.GetField("FMaterialId")
+material = BusinessDataServiceHelper.LoadSingle(this.Context, materialId, field.RefFormDynamicObjectType)
+row["MaterialId_Id"] = materialId
+row["MaterialId"] = material
+```
+
+Refresh only the necessary view areas with `this.View.UpdateView("FFieldKey")` or the entity key.
+
+## Form And Bill Plugin Events
+
+Common bill/form plugin events:
+
+- `AfterCreateModelData`: initialize default values after new bill data is created.
+- `AfterBindData`: UI state changes after data binding.
+- `BarItemClick`: toolbar/menu click handling.
+- `ButtonClick`: button or hyperlink handling.
+- `EntityRowClick` / `EntityRowDoubleClick`: entry row interactions.
+- `DataChanged`: field value linkage when immediate trigger is enabled in BOS.
+- `BeforeF7Select`: dynamic F7 filter.
+- `BeforeDoOperation`: validate before an operation.
+- `AfterDoOperation`: handle after an operation.
+
+For UI messages in form/list plugins, use `this.View.ShowMessage`, `ShowWarnningMessage`, or `ShowErrMessage`.
+
+## Operation Service Plugin Events
+
+Operation service plugins do not have `this.View`.
+
+Common events:
+
+- `OnPreparePropertys`: declare required fields before loading data.
+- `OnAddValidators`: register validators.
+- `BeforeExecuteOperationTransaction`: before platform transaction execution.
+- `BeginOperationTransaction`: transaction begins.
+- `EndOperationTransaction`: transaction has completed and data is updated.
+- `AfterExecuteOperationTransaction`: after transaction execution.
+
+For service/report/convert plugins, raise an exception for blocking messages:
+
+```python
+raise Exception("提示信息")
+```
+
+Avoid independent save calls inside platform transaction hooks unless the plan explicitly accepts the transaction risk. Prefer modifying the data entities passed by the platform.
+
+## Query And Save Patterns
+
+Use platform helpers:
+
+- `MetaDataServiceHelper.Load` or `GetFormMetaData` for form metadata.
+- `BusinessDataServiceHelper.LoadSingle`, `Load`, `Save`, `Submit`, `Audit`, and `DoNothing`.
+- `QueryServiceHelper.GetDynamicObjectCollection` for query builder results.
+- `DBUtils.ExecuteDataSet` or `ExecuteDynamicObject` when direct SQL is required.
+
+When writing SQL, use platform-safe patterns and avoid user-input string concatenation. Mark SQL dialect intentionally when using dialect SQL.
+
+## Verification
+
+Python plugin verification is usually BOS registration plus functional testing in a test data center. The plan and verification record should include:
+
+- Script file path.
+- Plugin type and BOS registration target.
+- FormId, field keys, entity keys, and operation code evidence.
+- Test data and operation steps.
+- Runtime error or message evidence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcode-pi",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Kingdee-specific package and harness for Pi Coding Agent",
   "type": "module",
   "private": false,
@@ -18,7 +18,7 @@
     "themes",
     "knowledge",
     "vendor",
-    "docs/KCODE_DISTRIBUTION.md",
+    "docs",
     "README.md"
   ],
   "keywords": [

package/skills/kd-cosmic-dev/SKILL.md

@@ -52,6 +52,7 @@ description: 金蝶 Cosmic 体系 Java 插件开发技能，适用于苍穹、
 
 4. 只有插件类型、生命周期方法、字段元数据和 API 签名都明确后，才生成或修改代码。
    - 遵循项目已有包名、基类、常量、日志风格和 helper 封装。
+   - 星空旗舰版项目先检查当前目录结构，再选择真实目标路径。若存在 `code/`，跟随 `code/` 下既有组织；若不存在，跟随已发现的源码根或目标文件，不要在项目根目录新建 `src/main/java`。
    - 优先使用项目本地封装和已批准的 Cosmic helper，再考虑底层 BOS API。
    - 事件处理器只做当前事件阶段该做的事。
 
@@ -64,6 +65,7 @@ description: 金蝶 Cosmic 体系 Java 插件开发技能，适用于苍穹、
 
 - 不臆造字段 key、表单 ID、操作名、枚举值、表名或 SDK 方法。
 - 不把 Enterprise C# 命名空间或生命周期假设用于 Cosmic Java。
+- 星空旗舰版不允许猜目录或写 demo/sample；如果无法判断真实代码位置，先询问或更新计划，不要直接创建新目录。
 - 不在数据绑定前的初始化阶段操作 UI 控件。
 - 不在平台期望修改入参数据实体的事务钩子里另起保存。
 - 不在循环中查询或保存，除非计划中明确说明无法批量处理并接受风险。

package/skills/kd-cosmic-unittest/SKILL.md

@@ -56,6 +56,7 @@ POJO 或简单枚举场景可以简要说明后直接实现。
 ## 测试质量规则
 
 - 使用项目已有 JUnit 和 Mockito 版本。
+- 如果项目没有既有且允许使用的单测框架，不要新增 JUnit、Mockito 或额外 jar；改用 Harness 的红绿验证门禁，例如 API/基类/方法签名、元数据、编译或最小外部接口验证。
 - import 保持显式；项目风格允许时也不要使用宽泛静态通配导入。
 - 每个测试方法必须有真实断言或交互验证。
 - 避免 `assertTrue(true)`、`assertEquals(x, x)` 或只执行不验证的测试。

package/skills/kd-enterprise-python-plugin/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: kd-enterprise-python-plugin
+description: Enterprise / Kingdee Cloud BOS Python plugin development with IronPython. Use only when the user explicitly asks for Python plugin, IronPython, or a BOS/Enterprise Python script.
+---
+
+# Enterprise Python Plugin
+
+Use this skill only when the user explicitly requests an Enterprise Python plugin, IronPython, or a BOS/Enterprise Python script. Default Enterprise plugin work is C# and must not use this skill unless Python is explicit.
+
+## Workflow
+
+- Start from `kd_plan_status`.
+- Keep the harness workflow: discuss -> spec -> plan -> execute -> verify.
+- Do not write `.py` code before execute.
+- In plan, inspect the current project and record the actual script/source path. Do not invent a demo path.
+
+## Required Facts
+
+Before coding, establish:
+
+- Plugin type: form/bill, list, operation service, report service, report form, or convert plugin.
+- Target FormId, bill/entity, field keys, entity keys, and operation code.
+- Lifecycle event such as `AfterBindData`, `DataChanged`, `BeforeF7Select`, `BeforeDoOperation`, `BeginOperationTransaction`, or `EndOperationTransaction`.
+- BOS registration location and test data center verification steps.
+
+## Coding Rules
+
+- Use IronPython syntax and .NET assembly references.
+- Use `Kingdee.BOS.*` imports and helpers; do not use Cosmic Java `kd.bos.*` APIs.
+- Form/list plugins may use `this.View`; operation service/report/convert plugins must not assume `this.View`.
+- Use `this.View.ShowMessage` or warning/error variants for form/list UI messages.
+- Use `raise Exception(...)` for service/report/convert blocking messages.
+- Do not write sample/demo code. Adapt to actual FormId, field keys, entity keys, and existing project structure.
+- Avoid independent saves inside transaction hooks unless explicitly planned.
+
+## Verification
+
+Record in `EXECUTION.md` and `VERIFY.md`:
+
+- Changed `.py` file paths.
+- BOS registration target.
+- Confirmed FormId/field/entity/operation facts.
+- Functional test steps and results.

package/skills/kd-execute/SKILL.md

@@ -11,12 +11,16 @@ Goal:
 
 - Implement only the approved plan.
 - Use `kd_search` and `kd_table` before relying on Kingdee APIs or table schemas.
-- Update `.pi/kd/runs/<run-id>/EXECUTION.md` with completed steps, changed files, and deviations.
+- Update `.pi/kd/runs/<run-id>/EXECUTION.md` with every planned `STEP-###`, changed files, and evidence files.
 
 Rules:
 
 - Do not broaden scope silently.
 - Do not rewrite unrelated modules.
+- For 星空旗舰版, edit only the real target path recorded in `PLAN.md` after inspecting the project. If `code/` exists, follow its actual layout; if it does not, follow the discovered source root or existing target file. Do not create demo/sample code or root-level `src/main/java` by guesswork.
 - Do not mark work complete until verification runs.
+- Do not skip planned steps. Every `STEP-###` in `PLAN.md` must be marked complete in `EXECUTION.md` with a real `evidence/...` file before entering verify.
+- Before writing production source files, run the planned red check and record failing output in `evidence/tdd-red.md`. This can be API/base-class/method-signature, metadata, compile/build, existing project test, or minimal external-interface evidence.
+- Before entering verify, rerun the same check and record passing output in `evidence/tdd-green.md`.
+- Do not add JUnit, Mockito, NUnit, xUnit, or any extra test jar/framework only to satisfy the gate. Use existing approved project test infrastructure if it already exists.
 - If implementation needs a plan change, update `PLAN.md` first.
-

package/skills/kd-gen/SKILL.md

@@ -19,6 +19,7 @@ Rules:
 
 - Generate code only after the active run has a `PLAN.md`.
 - Use the correct base class only when verified for the target product family.
+- For 星空旗舰版, generate or edit product code only under the real target path selected in `PLAN.md` after project inspection. Follow the existing layout, whether it uses `code/`, app modules, cloud modules, or no module split; never create demo/sample code or root-level `src/main/java` by guesswork.
 - Use `kd.bos.*` style packages for Cosmic-family Java code and `Kingdee.BOS.*` style namespaces for enterprise C# code.
 - Do not reuse Cosmic/Xinghan/Cangqiong APIs for enterprise C#.
 - Do not reuse enterprise C# namespaces or lifecycle assumptions for Java products.

package/skills/kd-plan/SKILL.md

@@ -11,14 +11,20 @@ Goal:
 
 - Produce or update `.pi/kd/runs/<run-id>/PLAN.md`.
 - List files to inspect before editing.
+- List the inspected project layout and the exact target source root or file path before editing.
 - List expected files to modify.
 - List required `kd_search` and `kd_table` lookups.
+- List `## Execution Steps` using `- [ ] STEP-001: ...` style IDs.
+- List `## TDD / Red-Green Checks` with red evidence, green evidence, and the command/tool or product-specific check.
+- Do not plan to add third-party test jars or frameworks only for red/green checks. For Kingdee plugin work, prefer API/base-class/method-signature checks, metadata checks, compile/build checks, existing project tests, or minimal external-interface tests.
 - Define validation commands and expected evidence.
 - Add rollback or containment notes for medium/high risk work.
 
 Gate:
 
 - Execution must not start without `PLAN.md`.
+- A plan for 星空旗舰版 is incomplete unless it records the existing project layout and exact target path to edit. If `code/` exists, follow its actual structure; if it does not, record the discovered source root or existing target file.
 - A plan without validation commands is incomplete.
+- A plan without structured `STEP-001` execution steps is incomplete.
+- A plan without TDD red/green checks is incomplete.
 - A plan that relies on unverified Kingdee API names is incomplete.
-

package/src/cli/kcode.ts

@@ -3,6 +3,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
+import { ensureProjectContext, writeProjectContext } from "../context/project-context.js";
 
 export interface KcodeCliResult {
 	exitCode: number;
@@ -31,6 +32,8 @@ export function runKcodeCli(args: string[], cwd = process.cwd()): KcodeCliResult
 	switch (command) {
 		case "init":
 			return initProject(cwd);
+		case "context":
+			return context(cwd, args.slice(1));
 		case "doctor":
 			return doctor(cwd);
 		case "start":
@@ -55,10 +58,20 @@ export function initProject(cwd: string): KcodeCliResult {
 	settings.packages = packages;
 	mkdirSync(dirname(settingsPath), { recursive: true });
 	writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+	const projectContext = ensureProjectContext(cwd);
 
 	return {
 		exitCode: 0,
-		output: [`已更新项目级 Pi 配置：${settingsPath}`, `已保留当前 KCode package：${kcodePackage}`].join("\n"),
+		output: [`已更新项目级 Pi 配置：${settingsPath}`, `已保留当前 KCode package：${kcodePackage}`, `项目上下文：${projectContext.path}`].join("\n"),
+	};
+}
+
+export function context(cwd: string, args: string[]): KcodeCliResult {
+	const refresh = args.includes("--refresh") || args.includes("-r");
+	const projectContext = refresh ? writeProjectContext(cwd) : ensureProjectContext(cwd);
+	return {
+		exitCode: 0,
+		output: [`项目上下文已${refresh ? "刷新" : "就绪"}：${projectContext.path}`, "", projectContext.content].join("\n"),
 	};
 }
 
@@ -73,6 +86,7 @@ export function doctor(cwd: string): KcodeCliResult {
 	lines.push(`Pi CLI：${formatPiCliStatus(piCli, pi)}`);
 	lines.push(`KCode package：${packageRoot}`);
 	lines.push(`项目配置：${existsSync(settingsPath) ? settingsPath : "未创建，请先运行 kcode init"}`);
+	lines.push(`项目上下文：${existsSync(join(cwd, ".pi", "kd", "PROJECT_CONTEXT.md")) ? join(cwd, ".pi", "kd", "PROJECT_CONTEXT.md") : "未创建，请运行 kcode context"}`);
 
 	if (existsSync(settingsPath)) {
 		const settings = readSettings(settingsPath);
@@ -213,6 +227,7 @@ function helpText(): string {
 		"",
 		"用法：",
 		"  kcode init      初始化当前项目的 .pi/settings.json",
+		"  kcode context   生成或刷新 .pi/kd/PROJECT_CONTEXT.md",
 		"  kcode doctor    检查 Node、随包 Pi CLI、KCode package 和项目级配置",
 		"  kcode start     初始化项目配置后启动 KCode 工作环境",
 	].join("\n");

package/src/context/project-context.ts

@@ -0,0 +1,215 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, extname, join, relative } from "node:path";
+
+const IGNORED_DIRS = new Set([
+	".git",
+	".idea",
+	".pi",
+	".tmp",
+	".vscode",
+	"bin",
+	"build",
+	"dist",
+	"node_modules",
+	"out",
+	"target",
+]);
+
+const SOURCE_EXTENSIONS = new Set([".java", ".kt", ".kts", ".cs", ".py", ".xml", ".properties", ".yml", ".yaml", ".sql", ".ksql"]);
+const BUILD_FILE_NAMES = new Set(["pom.xml", "build.gradle", "build.gradle.kts", "gradlew", "gradlew.bat", "mvnw", "mvnw.cmd", "package.json"]);
+const MAX_DEPTH = 5;
+const MAX_ENTRIES = 3000;
+const MAX_SOURCE_SAMPLES = 60;
+const MAX_MODULES = 80;
+
+export interface ProjectContextResult {
+	path: string;
+	content: string;
+}
+
+export function projectContextPath(cwd: string): string {
+	return join(cwd, ".pi", "kd", "PROJECT_CONTEXT.md");
+}
+
+export function readProjectContext(cwd: string): string | undefined {
+	const path = projectContextPath(cwd);
+	return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+}
+
+export function ensureProjectContext(cwd: string): ProjectContextResult {
+	const path = projectContextPath(cwd);
+	if (existsSync(path)) return { path, content: readFileSync(path, "utf8") };
+	return writeProjectContext(cwd);
+}
+
+export function writeProjectContext(cwd: string): ProjectContextResult {
+	const path = projectContextPath(cwd);
+	const content = generateProjectContext(cwd);
+	mkdirSync(join(cwd, ".pi", "kd"), { recursive: true });
+	writeFileSync(path, content, "utf8");
+	return { path, content };
+}
+
+export function generateProjectContext(cwd: string): string {
+	const scan = scanProject(cwd);
+	const codeDir = scan.directories.includes("code");
+	const likelyRoots = detectLikelySourceRoots(scan);
+	const modules = detectModules(scan);
+	const buildFiles = scan.files.filter((file) => BUILD_FILE_NAMES.has(basename(file).toLowerCase()) || isSolutionOrProject(file));
+	const sourceSamples = scan.files.filter((file) => SOURCE_EXTENSIONS.has(extname(file).toLowerCase())).slice(0, MAX_SOURCE_SAMPLES);
+
+	return [
+		"# KCode Project Context",
+		"",
+		`- Project root: ${cwd}`,
+		`- Project name: ${basename(cwd)}`,
+		`- Generated at: ${new Date().toISOString()}`,
+		"",
+		"## Persistent Rules",
+		"",
+		"- This file is project memory for KCode. Read it before planning or editing code.",
+		"- Do not create demo/sample/scaffold code for business requirements.",
+		"- Do not assume module layout. Follow the actual paths below and verify target files before editing.",
+		"- Use project-relative paths when calling file tools. On Windows, do not rewrite paths to /mnt/<drive>/... or /<drive>/...; use Windows paths only when an absolute path is necessary.",
+		"- If this file is stale, regenerate with `kcode context --refresh` before planning.",
+		"- Write product code only after the Harness reaches `execute` and PLAN.md names the real target path.",
+		"",
+		"## Layout Summary",
+		"",
+		`- Has code directory: ${codeDir ? "yes" : "no"}`,
+		`- Likely source roots: ${formatList(likelyRoots)}`,
+		`- Build files: ${formatList(buildFiles)}`,
+		`- Detected modules: ${formatList(modules)}`,
+		"",
+		"## Source Samples",
+		"",
+		formatBlockList(sourceSamples),
+		"",
+		"## Top-Level Directories",
+		"",
+		formatBlockList(scan.directories.filter((dir) => !dir.includes("/") && !dir.includes("\\")).sort()),
+		"",
+	].join("\n");
+}
+
+interface ProjectScan {
+	files: string[];
+	directories: string[];
+}
+
+function scanProject(cwd: string): ProjectScan {
+	const files: string[] = [];
+	const directories: string[] = [];
+	const queue: Array<{ path: string; depth: number }> = [{ path: cwd, depth: 0 }];
+	let entries = 0;
+
+	while (queue.length > 0 && entries < MAX_ENTRIES) {
+		const current = queue.shift();
+		if (!current) break;
+
+		let children: string[];
+		try {
+			children = readdirSync(current.path);
+		} catch {
+			continue;
+		}
+
+		for (const child of children) {
+			if (entries >= MAX_ENTRIES) break;
+			const fullPath = join(current.path, child);
+			let stat;
+			try {
+				stat = statSync(fullPath);
+			} catch {
+				continue;
+			}
+
+			const rel = normalize(relative(cwd, fullPath));
+			entries++;
+
+			if (stat.isDirectory()) {
+				if (IGNORED_DIRS.has(child)) continue;
+				directories.push(rel);
+				if (current.depth < MAX_DEPTH) queue.push({ path: fullPath, depth: current.depth + 1 });
+				continue;
+			}
+
+			if (stat.isFile()) files.push(rel);
+		}
+	}
+
+	return { files: files.sort(), directories: directories.sort() };
+}
+
+function detectLikelySourceRoots(scan: ProjectScan): string[] {
+	const roots = new Set<string>();
+	const knownRoots = [
+		"code/src/main/java",
+		"code/src/main/resources",
+		"src/main/java",
+		"src/main/resources",
+		"src",
+		"script",
+		"scripts",
+		"plugins",
+	];
+
+	for (const root of knownRoots) {
+		if (scan.directories.includes(root) || scan.files.some((file) => file.startsWith(`${root}/`))) roots.add(root);
+	}
+
+	for (const file of scan.files) {
+		if (!SOURCE_EXTENSIONS.has(extname(file).toLowerCase())) continue;
+		const marker = sourceRootFromFile(file);
+		if (marker) roots.add(marker);
+	}
+
+	return [...roots].slice(0, MAX_MODULES);
+}
+
+function detectModules(scan: ProjectScan): string[] {
+	const modules = new Set<string>();
+
+	for (const file of scan.files) {
+		const name = basename(file).toLowerCase();
+		if (!BUILD_FILE_NAMES.has(name) && !isSolutionOrProject(file)) continue;
+		const dir = normalize(file.slice(0, -basename(file).length).replace(/[\\/]$/, ""));
+		modules.add(dir || ".");
+	}
+
+	for (const sourceRoot of detectLikelySourceRoots(scan)) {
+		const parts = sourceRoot.split("/");
+		if (parts.length > 3) modules.add(parts.slice(0, -3).join("/") || ".");
+	}
+
+	return [...modules].filter(Boolean).sort().slice(0, MAX_MODULES);
+}
+
+function sourceRootFromFile(file: string): string | undefined {
+	const normalized = normalize(file);
+	const javaIndex = normalized.indexOf("/src/main/java/");
+	if (javaIndex >= 0) return normalized.slice(0, javaIndex + "/src/main/java".length);
+	const resourcesIndex = normalized.indexOf("/src/main/resources/");
+	if (resourcesIndex >= 0) return normalized.slice(0, resourcesIndex + "/src/main/resources".length);
+	const srcIndex = normalized.indexOf("/src/");
+	if (srcIndex >= 0) return normalized.slice(0, srcIndex + "/src".length);
+	const first = normalized.split("/")[0];
+	return first && SOURCE_EXTENSIONS.has(extname(normalized).toLowerCase()) ? first : undefined;
+}
+
+function isSolutionOrProject(file: string): boolean {
+	return [".sln", ".csproj"].includes(extname(file).toLowerCase());
+}
+
+function formatList(values: string[]): string {
+	return values.length > 0 ? values.join(", ") : "none detected";
+}
+
+function formatBlockList(values: string[]): string {
+	if (values.length === 0) return "- none detected";
+	return values.map((value) => `- ${value}`).join("\n");
+}
+
+function normalize(path: string): string {
+	return path.replace(/\\/g, "/");
+}

package/src/harness/artifacts.ts

@@ -73,19 +73,53 @@ export function defaultArtifactContent(phase: KdPhase, goal?: string, profile?:
 			return [
 				"# Plan",
 				"",
+				"## Project Structure Checked",
+				"",
 				"## Files to Inspect",
 				"",
+				"## Target Source Root / Path",
+				"",
 				"## Files to Edit",
 				"",
 				"## Required Kingdee Lookups",
 				"",
+				"## Execution Steps",
+				"",
+				"- [ ] STEP-001: Inspect the existing target files and confirm exact edit locations.",
+				"- [ ] STEP-002: Run a failing red check and record red evidence.",
+				"- [ ] STEP-003: Implement only the approved file changes.",
+				"- [ ] STEP-004: Run the same check again and record green evidence.",
+				"- [ ] STEP-005: Record changed files and step evidence.",
+				"",
+				"## TDD / Red-Green Checks",
+				"",
+				"- Red evidence: evidence/tdd-red.md",
+				"- Green evidence: evidence/tdd-green.md",
+				"- Red/green command or tool: unknown",
+				"- Allowed checks: official API/base-class/method lookup, metadata lookup, kd_check, build/compile output, existing project test framework, or a minimal external-interface test.",
+				"- Do not add third-party test jars or frameworks just to satisfy this gate.",
+				"- If automated tests are impossible, document the product-specific check that can fail before implementation and pass after implementation.",
+				"",
 				"## Validation Commands",
 				"",
 				"## Rollback / Containment",
 				"",
 			].join("\n");
 		case "execute":
-			return ["# Execution", "", "## Completed Steps", "", "## Changed Files", "", "## Deviations", ""].join("\n");
+			return [
+				"# Execution",
+				"",
+				"## Step Results",
+				"",
+				"Record each planned step as:",
+				"",
+				"- [x] STEP-001: completed. Evidence: evidence/step-001.md",
+				"",
+				"## Changed Files",
+				"",
+				"## Deviations",
+				"",
+			].join("\n");
 		case "verify":
 			return ["# Verify", "", "## Commands", "", "## Evidence", "", "## Residual Risk", ""].join("\n");
 		case "ship":

package/src/harness/gates.ts

@@ -2,6 +2,9 @@ import type { ActiveRun, GateResult, KdPhase } from "./types.ts";
 import { PHASE_ARTIFACTS, PHASE_ORDER } from "./types.ts";
 import { artifactExists, readArtifact } from "./artifacts.ts";
 import { isKnownProduct } from "../product/profile.ts";
+import { flagshipPlanBlockReason } from "./path-policy.ts";
+import { executionStepsBlockReason, planStepsBlockReason } from "./plan-steps.ts";
+import { tddPlanBlockReason, tddVerifyBlockReason } from "./tdd-policy.ts";
 
 const REQUIRED_MARKERS: Partial<Record<KdPhase, string[]>> = {
 	plan: ["## Validation Commands"],
@@ -25,10 +28,12 @@ export function inspectGate(cwd: string, run: ActiveRun): GateResult {
 	}
 
 	const markerProblem = inspectMarkers(cwd, run, run.phase);
+	const stepProblem = inspectStepState(cwd, run, run.phase);
 	const evidenceProblem = inspectEvidence(cwd, run, run.phase);
 	const reasonParts = [];
 	if (missing.length > 0) reasonParts.push(`缺少必需产物：${[...new Set(missing)].join(", ")}`);
 	if (markerProblem) reasonParts.push(markerProblem);
+	if (stepProblem) reasonParts.push(stepProblem);
 	if (evidenceProblem) reasonParts.push(evidenceProblem);
 
 	return {
@@ -57,6 +62,16 @@ export function canEnterPhase(cwd: string, run: ActiveRun, target: KdPhase): Gat
 		missing.push(PHASE_ARTIFACTS.plan);
 	}
 
+	const flagshipPathProblem = target === "execute" ? flagshipPlanBlockReason(cwd, run, readArtifact(cwd, run, "plan") ?? "") : undefined;
+	if (flagshipPathProblem) {
+		reasonParts.push(flagshipPathProblem);
+	}
+
+	const stepProblem = inspectStepState(cwd, run, target);
+	if (stepProblem) {
+		reasonParts.push(stepProblem);
+	}
+
 	missing.push(...missingEvidenceForPhase(cwd, run, target));
 
 	if (target === "ship" && !artifactExists(cwd, run, PHASE_ARTIFACTS.verify)) {
@@ -72,6 +87,20 @@ export function canEnterPhase(cwd: string, run: ActiveRun, target: KdPhase): Gat
 	};
 }
 
+function inspectStepState(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
+	if (phase === "execute") {
+		const plan = readArtifact(cwd, run, "plan") ?? "";
+		return planStepsBlockReason(plan) ?? tddPlanBlockReason(plan);
+	}
+	if (phase === "verify" || phase === "ship") {
+		return (
+			executionStepsBlockReason(cwd, run, readArtifact(cwd, run, "plan") ?? "", readArtifact(cwd, run, "execute") ?? "") ??
+			tddVerifyBlockReason(cwd, run)
+		);
+	}
+	return undefined;
+}
+
 function inspectMarkers(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
 	const markers = REQUIRED_MARKERS[phase];
 	if (!markers?.length) return undefined;