@huaqiu/dsh-kicad 0.4.12 → 0.4.13

package/lib/index.mjs

@@ -35,6 +35,116 @@ function hasHostConfig(input = {}) {
 	return Boolean(input.pythonPath ?? process.env["DSH_KICAD_PYTHON"] ?? input.skillsDir ?? process.env["DSH_KICAD_SKILLS_DIR"]);
 }
 //#endregion
+//#region src/paths.ts
+/**
+* Resolution of the bundled skill directories at runtime.
+*
+* Every bundled skill ships inside the installed package
+* (`<pkg>/skills/<skill-id>/`), not beside the source tree, so it is located
+* relative to the loaded module. That makes one resolver correct for every
+* install shape:
+*
+*   - built artifact:   `<pkg>/lib/index.mjs`   -> `<pkg>/skills/<skill-id>`
+*   - source (vitest):  `<pkg>/src/index.ts`    -> `<pkg>/skills/<skill-id>`
+*   - npm / git install: identical to the built artifact case
+*
+* `skills` must stay in `package.json` `files[]` or npm strips it and this
+* resolver fails loudly — which is the intended signal, because a `dsh-kicad`
+* without its skills is a broken delivery boundary.
+*
+* The override (`skillsDir` config / `DSH_KICAD_SKILLS_DIR`) is the **skills
+* root**, i.e. the directory that *contains* the skill directories — not one
+* skill's directory. One override therefore relocates the whole set, and the
+* per-skill layout below it is unchanged.
+*
+* @module
+*/
+/**
+* Absolute path of the directory holding every bundled skill.
+*
+* Resolution order: an explicit override (config / `DSH_KICAD_SKILLS_DIR`),
+* then the package-relative location.
+*
+* @param moduleUrl - `import.meta.url` of the calling module.
+* @param override - explicit skills root (plugin config or env var).
+* @returns the resolved directory, whether or not it exists yet.
+*/
+function skillsRoot(moduleUrl, override) {
+	if (override && override.trim().length > 0) return resolve(override);
+	const envOverride = process.env["DSH_KICAD_SKILLS_DIR"];
+	if (envOverride && envOverride.trim().length > 0) return resolve(envOverride);
+	const here = dirname(fileURLToPath(moduleUrl));
+	return resolve(here, "..", "skills");
+}
+/**
+* Absolute path of one bundled skill directory.
+*
+* @param moduleUrl - `import.meta.url` of the calling module.
+* @param skillId - bundled skill id; MUST equal the directory name.
+* @param override - explicit skills root (plugin config or env var).
+* @returns the resolved directory, whether or not it exists yet.
+*/
+function resolveSkillDir(moduleUrl, skillId, override) {
+	return join(skillsRoot(moduleUrl, override), skillId);
+}
+/**
+* Resolve one skill directory and assert the skill is actually present.
+*
+* @throws when `SKILL.md` is missing — this is a packaging failure, not a
+* runtime condition, so it must be loud rather than silently degraded.
+*/
+function requireSkillDir(moduleUrl, skillId, override) {
+	const dir = resolveSkillDir(moduleUrl, skillId, override);
+	const skillFile = join(dir, "SKILL.md");
+	if (!existsSync(skillFile)) throw new Error(`@huaqiu/dsh-kicad: bundled skill missing at ${skillFile}. The installed package is incomplete — reinstall @huaqiu/dsh-kicad so that its skills/ directory is present.`);
+	return dir;
+}
+/** Absolute path of the bundled Python script directory inside a skill. */
+function scriptsDir(skillDir) {
+	return join(skillDir, "scripts");
+}
+//#endregion
+//#region src/skills.ts
+/**
+* The skill that owns the script templates behind the KiCad tools.
+*
+* The tools are the *executable* half of this skill: `kicad_pcb_*` shells out
+* to `skills/kicad-ipc/scripts/*.py`. Kept as a named constant because the
+* tools must keep resolving correctly even when that particular skill fails to
+* load (they then fail per-call with a typed `FAILED_PRECONDITION` instead of
+* silently pointing at another skill's directory).
+*/
+const KICAD_SCRIPT_SKILL_ID = "kicad-ipc";
+/**
+* Every skill bundled with `@huaqiu/dsh-kicad`, keyed by id.
+*
+* Mirrors `skills/` 1:1 — the bundling test asserts that every entry exists on
+* disk with a valid SKILL.md, and that no directory is left unregistered.
+*/
+const KICAD_SKILLS = {
+	[KICAD_SCRIPT_SKILL_ID]: {
+		id: KICAD_SCRIPT_SKILL_ID,
+		summary: "Operate a KiCad PCB through the official KiCad IPC API: inspect the live board and create, modify or delete objects. Use for PCB automation and autorouter-result import — not for editing .kicad_pcb files directly.",
+		ownsScripts: true
+	},
+	"hardware-design-brief": {
+		id: "hardware-design-brief",
+		summary: "Turn a market need into verifiable hardware requirements: clarify them through staged questioning and write the market MRD, the hardware PRD and the schematic/PCB design inputs. Use when defining requirements for a new board project.",
+		ownsScripts: false
+	}
+};
+/** The bundled skill ids, in registration order. */
+const KICAD_SKILL_IDS = Object.keys(KICAD_SKILLS);
+/**
+* Look up one bundled skill by id.
+* @throws when the id is not part of the bundled set.
+*/
+function kicadSkill(id) {
+	const skill = KICAD_SKILLS[id];
+	if (!skill) throw new Error(`@huaqiu/dsh-kicad: unknown bundled skill "${id}"`);
+	return skill;
+}
+//#endregion
 //#region src/scripts.ts
 /**
 * Every bundled script, keyed by id.
@@ -126,60 +236,6 @@ function kicadScript(id) {
 	if (!script) throw new Error(`@huaqiu/dsh-kicad: unknown bundled KiCad script "${id}"`);
 	return script;
 }
-/** The canonical skill directory name shipped by this package. */
-const KICAD_SKILL_NAME = "kicad-ipc";
-//#endregion
-//#region src/paths.ts
-/**
-* Resolution of the bundled KiCad skill directory at runtime.
-*
-* The skill ships inside the installed package (`<pkg>/skills/kicad-ipc/`), not
-* beside the source tree, so it is located relative to the loaded module. That
-* makes one resolver correct for every install shape:
-*
-*   - built artifact:   `<pkg>/lib/index.mjs`   -> `<pkg>/skills/kicad-ipc`
-*   - source (vitest):  `<pkg>/src/index.ts`    -> `<pkg>/skills/kicad-ipc`
-*   - npm / git install: identical to the built artifact case
-*
-* `skills` must stay in `package.json` `files[]` or npm strips it and this
-* resolver fails loudly — which is the intended signal, because a `dsh-kicad`
-* without its skill is a broken delivery boundary.
-*
-* @module
-*/
-/**
-* Absolute path of the bundled `kicad-ipc` skill directory.
-*
-* Resolution order: an explicit override (config / `DSH_KICAD_SKILLS_DIR`),
-* then the package-relative location.
-*
-* @param moduleUrl - `import.meta.url` of the calling module.
-* @param override - explicit directory (plugin config or env var).
-* @returns the resolved directory, whether or not it exists yet.
-*/
-function resolveSkillDir(moduleUrl, override) {
-	if (override && override.trim().length > 0) return resolve(override);
-	const envOverride = process.env["DSH_KICAD_SKILLS_DIR"];
-	if (envOverride && envOverride.trim().length > 0) return resolve(envOverride);
-	const here = dirname(fileURLToPath(moduleUrl));
-	return resolve(here, "..", "skills", KICAD_SKILL_NAME);
-}
-/**
-* Resolve the skill directory and assert the skill is actually present.
-*
-* @throws when `SKILL.md` is missing — this is a packaging failure, not a
-* runtime condition, so it must be loud rather than silently degraded.
-*/
-function requireSkillDir(moduleUrl, override) {
-	const dir = resolveSkillDir(moduleUrl, override);
-	const skillFile = join(dir, "SKILL.md");
-	if (!existsSync(skillFile)) throw new Error(`@huaqiu/dsh-kicad: bundled skill missing at ${skillFile}. The installed package is incomplete — reinstall @huaqiu/dsh-kicad so that its skills/ directory is present.`);
-	return dir;
-}
-/** Absolute path of the bundled Python script directory. */
-function scriptsDir(skillDir) {
-	return join(skillDir, "scripts");
-}
 //#endregion
 //#region src/ipc.ts
 /**
@@ -851,7 +907,7 @@ const name = "@huaqiu/dsh-kicad";
 * Cordis services this half depends on.
 *
 * `skills` is REQUIRED: it is the DSH runtime's skill registry, and registering
-* the bundled `kicad-ipc` skill is this plugin's core job. Without the inject,
+* the bundled skills is this plugin's core job. Without the inject,
 * `apply()`'s `ctx.skills` access would throw
 * `cannot get property "skills" without inject`.
 *
@@ -864,16 +920,10 @@ const inject = ["skills", "tools"];
 const log = getLogger("dsh-kicad");
 log.info("dsh-kicad: module loaded (waiting for the skills + tools services)");
 /**
-* Used only when the bundled SKILL.md has no parseable `description`
-* frontmatter. The real value always comes from the shipped file, so the skill
-* catalog cannot drift away from the skill body.
-*/
-const FALLBACK_SKILL_DESCRIPTION = "Operate a KiCad PCB through the official KiCad IPC API: inspect the live board and create, modify or delete objects. Use for PCB automation and autorouter-result import — not for editing .kicad_pcb files directly.";
-/**
 * Extract the `description` field from SKILL.md YAML frontmatter.
 *
 * Only the single-line form is supported (quoted or bare), which is what the
-* migrated skill uses. Returns `undefined` when absent so the caller can fall
+* migrated skills use. Returns `undefined` when absent so the caller can fall
 * back rather than registering a skill with an empty description — DSH ignores
 * frontmatter-less skills entirely, so an empty description would silently
 * break discovery.
@@ -887,24 +937,28 @@ function skillDescription(markdown) {
 	return unquoted.length > 0 ? unquoted : void 0;
 }
 /**
-* Read the bundled `kicad-ipc` SKILL.md.
+* Read one bundled SKILL.md.
 *
-* Exposed for tests and for callers that want the skill body without loading
-* the plugin (e.g. a packaging check).
+* Exposed for tests and for callers that want a skill body without loading the
+* plugin (e.g. a packaging check).
+*
+* @param moduleUrl - `import.meta.url` of the calling module.
+* @param skillId - bundled skill id (see `./skills.ts`).
+* @param override - explicit skills root (plugin config or env var).
 */
-function readBundledSkill(moduleUrl, override) {
-	const dir = requireSkillDir(moduleUrl, override);
+function readBundledSkill(moduleUrl, skillId, override) {
+	const dir = requireSkillDir(moduleUrl, skillId, override);
 	const content = readFileSync(join(dir, "SKILL.md"), "utf8");
 	return {
 		dir,
-		name: KICAD_SKILL_NAME,
-		description: skillDescription(content) ?? FALLBACK_SKILL_DESCRIPTION,
+		name: skillId,
+		description: skillDescription(content) ?? kicadSkill(skillId).summary,
 		content
 	};
 }
 /**
-* Read the bundled skill, or `null` when the installed package does not carry
-* one.
+* Read one bundled skill, or `null` when the installed package does not carry
+* it.
 *
 * ── Why this degrades instead of throwing ──────────────────────────────────
 * A missing `skills/` tree is a PACKAGING failure, and the honest signal for a
@@ -916,51 +970,60 @@ function readBundledSkill(moduleUrl, override) {
 * That actually happened: HQ Edge's builtin-plugin staging copied only
 * `package.json` + `lib/`, so `skills/` never reached the bundle and the
 * server could not start at all. The correct blast radius for "this plugin's
-* skill is missing" is "this plugin is degraded", so we log at error level
-* with the exact path and remedy, skip skill registration, and keep the tools
-* (which fail per-call with a typed `FAILED_PRECONDITION` rather than at load).
+* skill is missing" is "this skill is unavailable", so we log at error level
+* with the exact path and remedy and skip that skill — per skill, so a broken
+* `kicad-ipc` never hides a perfectly good `hardware-design-brief`. The tools
+* are always kept (they fail per-call with a typed `FAILED_PRECONDITION`
+* rather than at load).
 *
 * @param moduleUrl - `import.meta.url` of the calling module.
-* @param override - explicit skill directory (plugin config or env var).
+* @param skillId - bundled skill id (see `./skills.ts`).
+* @param override - explicit skills root (plugin config or env var).
 */
-function tryReadBundledSkill(moduleUrl, override) {
+function tryReadBundledSkill(moduleUrl, skillId, override) {
 	try {
-		return readBundledSkill(moduleUrl, override);
+		return readBundledSkill(moduleUrl, skillId, override);
 	} catch (err) {
-		log.error("dsh-kicad: bundled skill unavailable — continuing degraded, the KiCad tools are registered but will fail until the package is reinstalled", {
-			expectedDir: resolveSkillDir(moduleUrl, override),
+		log.error(`dsh-kicad: bundled skill "${skillId}" unavailable — continuing degraded, the KiCad tools are registered but will fail until the package is reinstalled`, {
+			expectedDir: resolveSkillDir(moduleUrl, skillId, override),
 			error: String(err?.message ?? err)
 		});
 		return null;
 	}
 }
 /**
-* Host plugin body — register the `kicad-ipc` skill and the KiCad tools.
+* Host plugin body — register every bundled skill and the KiCad tools.
 *
-* Both halves are registered here so that one installation delivers both. The
-* skill's `resourceBase` points at the bundled skill directory, which is how
-* the agent reaches `references/ipc-pcb-workflows.md` and `scripts/` as
-* progressive-disclosure resources.
+* Both halves are registered here so that one installation delivers both. Each
+* skill's `resourceBase` points at its own bundled directory, which is how the
+* agent reaches `references/` and `scripts/` as progressive-disclosure
+* resources.
 *
 * @param ctx - real cordis context (node side).
 * @param config - plugin overlay config (python interpreter, timeouts).
-* @returns disposer — unregisters the skill and the tools on plugin dispose.
+* @returns disposer — unregisters every skill and tool on plugin dispose.
 */
 function apply(ctx, config = {}) {
 	if (!ctx.tools || typeof ctx.tools.register !== "function") throw new Error("@huaqiu/dsh-kicad requires the DSH `tools` service (ctx.tools.register).");
 	if (!ctx.skills || typeof ctx.skills.register !== "function") throw new Error("@huaqiu/dsh-kicad requires the DSH `skills` service (ctx.skills.register).");
 	const resolved = resolveKicadConfig(config);
-	const skill = tryReadBundledSkill(import.meta.url, config.skillsDir);
-	const skillDir = skill?.dir ?? resolveSkillDir(import.meta.url, config.skillsDir);
+	const skills = /* @__PURE__ */ new Map();
+	for (const skillId of KICAD_SKILL_IDS) {
+		const skill = tryReadBundledSkill(import.meta.url, skillId, config.skillsDir);
+		if (skill) skills.set(skillId, skill);
+	}
+	const scriptSkillDir = skills.get("kicad-ipc")?.dir ?? resolveSkillDir(import.meta.url, "kicad-ipc", config.skillsDir);
 	log.info("applying dsh-kicad node half", {
 		hasConfigHost: hasHostConfig(config),
 		pythonPath: resolved.pythonPath,
-		skillDir,
-		skillPresent: skill !== null,
+		skillsRoot: skillsRoot(import.meta.url, config.skillsDir),
+		skillsRegistered: [...skills.keys()],
+		skillsMissing: KICAD_SKILL_IDS.filter((id) => !skills.has(id)),
+		scriptSkillDir,
 		timeoutMs: resolved.timeoutMs
 	});
 	const disposers = [];
-	if (skill) disposers.push(ctx.skills.register({
+	for (const skill of skills.values()) disposers.push(ctx.skills.register({
 		name: skill.name,
 		description: skill.description,
 		content: skill.content,
@@ -971,14 +1034,14 @@ function apply(ctx, config = {}) {
 		}
 	}));
 	const tools = createKicadTools({
-		scriptsDir: scriptsDir(skillDir),
+		scriptsDir: scriptsDir(scriptSkillDir),
 		pythonPath: resolved.pythonPath,
 		config: resolved
 	});
 	for (const tool of tools) disposers.push(ctx.tools.register(tool));
 	log.info("dsh-kicad node half ready", {
-		skill: skill?.name ?? null,
-		degraded: skill === null,
+		skills: [...skills.keys()],
+		degraded: skills.size < KICAD_SKILL_IDS.length,
 		tools: tools.length,
 		expectedTools: kicadToolNames().length
 	});
@@ -991,4 +1054,4 @@ function apply(ctx, config = {}) {
 	};
 }
 //#endregion
-export { KICAD_SCRIPTS, KICAD_SCRIPT_IDS, KICAD_SKILL_NAME, apply, classifyRun, createKicadTools, inject, invokeKicadScript, kicadScript, kicadToolNames, name, readBundledSkill, requireSkillDir, resolveSkillDir, runKicadScript, scriptsDir, skillDescription, tryReadBundledSkill };
+export { KICAD_SCRIPTS, KICAD_SCRIPT_IDS, KICAD_SCRIPT_SKILL_ID, KICAD_SKILLS, KICAD_SKILL_IDS, apply, classifyRun, createKicadTools, inject, invokeKicadScript, kicadScript, kicadSkill, kicadToolNames, name, readBundledSkill, requireSkillDir, resolveSkillDir, runKicadScript, scriptsDir, skillDescription, skillsRoot, tryReadBundledSkill };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-kicad",
-  "version": "0.4.12",
+  "version": "0.4.13",
   "type": "module",
   "main": "./lib/index.mjs",
   "types": "./lib/index.d.mts",
@@ -22,7 +22,7 @@
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.0"
   },
   "dependencies": {
-    "@huaqiu/dsh-plugin-log": "0.4.12"
+    "@huaqiu/dsh-plugin-log": "0.4.13"
   },
   "files": [
     "lib",

package/skills/hardware-design-brief/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: hardware-design-brief
+description: "通过分阶段提问澄清硬件产品需求，生成市场 MRD、硬件 PRD，以及原理图和 PCB 设计输入；适用于新电路板项目的需求定义。"
+---
+
+# 硬件产品需求与设计输入
+
+帮助工程师把市场需求逐步转成可验收的产品要求，再转成原理图和 PCB 设计输入。按用户实际请求生成其中一份或整套文档，不强制补齐未请求的阶段。
+
+## 本技能与同包能力的配合
+
+安装 `@huaqiu/dsh-kicad` 后，本技能随该插件一起可用，无需单独安装技能。
+
+本技能是**知识型技能**：它不注册任何工具，只提供提问流程、文档结构和“已确认 / 有来源 / 建议 / 假设 / 待确认”的区分口径。同包内的 `kicad-ipc` 技能负责把本技能产出的设计输入落到实际 PCB 上，并提供一组 `kicad_pcb_*` 工具（新建走线、过孔、铜区、移动/旋转封装、删除选中对象等）。
+
+两者的分工是：
+
+| 阶段 | 归属 | 产出 |
+| --- | --- | --- |
+| 市场需求、产品要求、设计输入 | 本技能 | `docs/01-MRD.md`、`docs/02-hardware-PRD.md`、`docs/03-design-brief.md`、`docs/decisions.md` |
+| 把设计输入落到 PCB（读取、修改、验证、保存） | `kicad-ipc` 技能 + `kicad_pcb_*` 工具 | 实际板卡改动 |
+
+当讨论进入“具体要在板上做什么”时，参照 `kicad-ipc` 技能：任何改动前先用 `kicad_ipc_diagnose` 确认 KiCad 可连接，改动后重新读取受影响的状态确认，保存由 `save` 参数显式控制。
+
+`references/` 下的三份指南按需读取（见下文），它们是本技能的一部分，不会自动全部加载。
+
+## 文档位置与关系
+
+把生成的项目文档放在**项目根目录的 `docs/`**，与本 skill 的 `references/` 分开。整套文档使用以下文件名；用户已有命名约定时沿用其约定，不另建重复文件。
+
+```text
+docs/
+├─ 01-MRD.md                 市场需求：目标客户、场景、机会与商业边界
+├─ 02-hardware-PRD.md        硬件产品需求：产品必须达到什么、如何验收
+├─ 03-design-brief.md        原理图和 PCB 设计输入：如何落实已确认要求
+└─ decisions.md              假设、未决问题、决策及变更依据
+```
+
+MRD 说明“谁需要、为何需要”；PRD 定义“产品必须达到什么”；design brief 将已确认的 PRD 要求转成可供原理图和 PCB 开工的约束与选择。使用稳定编号串联：MRD 为 `M-001`，PRD 为 `H-001`，PRD 标注来源的 MRD 编号，design brief 引用相关 PRD 编号。只给可追溯的需求编号，避免给普通叙述逐句编号。
+
+## 对话与生成
+
+1. 先阅读用户提供的背景和已有文档，确认项目根目录、目标交付物及已知约束。若项目位置明确，直接使用；不要重复询问已给出的信息。
+2. 按影响决策的程度分批提问，每轮只问少量相关问题，允许部分回答或填写“暂不确定”。先解决会改变目标市场、产品范围、核心功能、供电、接口、尺寸、层数或成本的问题。
+3. 区分**已确认**、**有来源的事实**、**建议**、**假设**和**待确认**。市场数据、竞品参数和器件能力若未核实，不写成事实；关键未知不能用臆测填满。遇到互相冲突的要求，指出冲突并请求取舍。
+4. 生成用户要求的文档；若用户要求整套文档，按 MRD → PRD → design brief 的依赖关系编写，并在 `docs/decisions.md` 记录会影响后续设计的假设和未决事项。缺少上游文档时，也可先做下游草案，但应标注其市场或产品前提。
+5. 检查各文档中数值、单位、状态和编号是否一致。下游文档不能把上游的假设或待确认事项升级为已批准要求。对更新过的要求，指出受影响的后续条目。
+
+按当前任务读取对应指南，不必一次加载全部：
+
+- 创建或更新 MRD：阅读 [references/mrd-guide.md](references/mrd-guide.md)。
+- 创建或更新硬件 PRD：阅读 [references/hardware-prd-guide.md](references/hardware-prd-guide.md)。
+- 创建或更新原理图与 PCB 设计输入：阅读 [references/design-brief-guide.md](references/design-brief-guide.md)。
+
+用户只想讨论方向时先讨论；用户只要求一份文件时仅创建或修改该文件，必要的未决问题可直接列在该文件末尾。

package/skills/hardware-design-brief/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "硬件需求与设计输入"
+  short_description: "通过提问生成市场 MRD、硬件 PRD 与电路板设计输入"
+  default_prompt: "使用 $hardware-design-brief 帮我梳理市场需求、硬件产品需求和电路板设计输入。"

package/skills/hardware-design-brief/references/design-brief-guide.md

@@ -0,0 +1,16 @@
+# 原理图与 PCB 设计输入
+
+本文件将已确认的产品需求转成开工约束，保持简练。先从 PRD 和已有设计资料提取信息，再追问会影响电路架构和 PCB 实现的事项：
+
+- 电源输入、各电源轨、电流/功率预算、负载、时序和保护。
+- 核心器件及所需计算、存储、外设、封装、供货和软件/工具链条件。
+- 有线/无线接口、连接器、电平、速率、线缆长度、隔离、调试与测试接口。
+- 板外形、板厚、安装孔、禁布区、器件高度、连接器位置和方向。
+- 层数、叠层、铜厚、阻抗、高速/模拟/大电流/天线区域、散热和 EMI 约束。
+- 制造、装配、检测、维修、环境及适用标准的设计输入。
+
+建议将 `docs/03-design-brief.md` 组织为：项目目标与适用 PRD 编号、原理图设计要求、PCB 设计要求、关键器件表、待确认与验证。原理图部分说明功能分区、核心器件、电源、接口、保护和测试点；PCB 部分说明尺寸、层数、机械、布局与工艺约束。每项关键设计要求引用相关 `H-` 编号；若是工程建议而非 PRD 硬性约束，标明“建议”。
+
+区分**指定器件**、**候选器件**和**待选**。具体候选需有足够的功能、电气、封装和供应信息支撑，并说明选择依据与待核实项；未经核对的候选不可写成批准选型。PCB 尺寸、层数、板厚、铜厚和阻抗优先记录明确边界；若用户需要建议，可基于密度、速率、阻抗、电流、散热、EMI、成本及制造能力提出建议值。未知参数写“待确认”，不虚构精度。
+
+对安规、EMC、热、信号完整性及可制造性，列明需要计算、仿真、打样或测试的验证事项。design brief 是设计输入，不代表这些项目已经满足要求。

package/skills/hardware-design-brief/references/hardware-prd-guide.md

@@ -0,0 +1,14 @@
+# 硬件产品需求文档（PRD）
+
+PRD 定义产品可交付和可验收的结果。先从 MRD 场景或用户直接给出的产品目标出发，追问决定产品架构和可测试性的缺口：
+
+- 功能边界、典型/异常使用流程、模式、通道数、响应时间、精度、速率和容量。
+- 输入电源范围、功耗与续航目标、输出负载、上电/掉电行为及故障状态。
+- 外部接口、协议、连接器、线缆、兼容对象，以及固件/软件对硬件的要求。
+- 外形和安装边界、环境条件、寿命、可靠性、维护与升级方式。
+- 安全、EMC/ESD、无线和目标市场的适用要求；认证目标与验证状态分开。
+- 成本目标、生产批量、制造/测试/维修要求和上市时间。
+
+建议将 `docs/02-hardware-PRD.md` 组织为：产品概述与范围、用户场景、系统边界、需求表、接口定义、机械与环境边界、成本/制造约束、验收与验证、待确认事项。需求表的每一项尽量包含：编号 `H-001`、来源 MRD 编号（若存在）、要求、优先级、状态、验收条件/方法。要求应可测量，并写明单位、工作条件和必要的容差；例如电源范围应区分正常工作、极限和故障条件。
+
+PRD 可记录用户指定的核心器件或不可更改的实现约束，并说明来源；未指定时优先写功能、电气和接口要求，让具体器件选择留到 design brief。目标尚不明确时标记待确认，不用任意数值凑齐表格。涉及测试或认证的条目写为目标和验收方法，不宣称已经通过。

package/skills/hardware-design-brief/references/mrd-guide.md

@@ -0,0 +1,14 @@
+# 市场需求文档（MRD）
+
+MRD 为产品取舍提供市场依据，不预先指定电路方案。采访式提问按项目选择，不要照表逐项盘问：
+
+- 目标客户和购买者是谁？谁实际使用、安装或维护？目标地区与行业是什么？
+- 客户在什么场景遇到什么问题？现有替代方案是什么，痛点有多频繁或昂贵？
+- 必须解决的场景、差异化价值与明确不覆盖的场景是什么？
+- 竞品或替代方案的价格、能力、限制与渠道是什么？哪些结论有证据，哪些只是判断？
+- 预期售价、目标销量/批量、上市窗口、销售渠道和商业约束是什么？
+- 哪些法规、采购门槛、使用环境或服务要求会影响产品定义？
+
+建议将 `docs/01-MRD.md` 组织为：概要、目标客户与使用场景、问题和现有方案、市场与竞品证据、价值主张、商业目标及边界、市场需求条目、假设与待验证事项。市场需求条目用 `M-001` 等编号，写清对象、场景、需求及优先级；尽量给出支撑证据或验证方式。
+
+涉及现时市场规模、竞品规格、价格、法规或供应状况时，核对可靠来源并记录来源链接和查询日期。用户提供的估计注明“用户估计”，缺证据的判断注明“假设”；不要编造市场规模、销量或竞品数据。MRD 中可以给出目标区间，但不把尚未论证的商业目标写成已验证结果。

package/src/config.ts

@@ -18,7 +18,12 @@ export interface KicadConfig {
    * official `kicad-python` package (`kipy`) installed.
    */
   pythonPath: string
-  /** Scripts directory override (defaults to the bundled skill's `scripts/`). */
+  /**
+   * Skills root override — the directory that CONTAINS the bundled skill
+   * directories (`<root>/kicad-ipc`, `<root>/hardware-design-brief`). Defaults
+   * to the package's own `skills/`. Relocates the whole skill set at once; the
+   * per-skill layout below it never changes.
+   */
   skillsDir?: string
   /** Per-script timeout in milliseconds. */
   timeoutMs: number