svharness 0.13.2 → 0.13.5

package/README.md

@@ -119,7 +119,7 @@ Harness 是一个 **项目本地的知识层**，由两大部分组成：
     └── wiki/                       #   架构 wiki
 │
 ├── agent-env/                    # Agent 运行期环境
-│   ├── rules/                    #   编码规则（.mdc，always_on 加载）
+│   ├── rules/                    #   编码规则（.mdc，`alwaysApply: true` 为硬约束）
 │   ├── skills/                   #   运行期技能（SKILL.md + references/ + scripts/）
 │   ├── tools/                    #   项目本地脚本
 │   └── memory/                   #   Agent 长期记忆
@@ -276,7 +276,7 @@ svharness build \
 | `--convert-max-file-mb <n>` | 可选 | build 自动 convert 单文件大小上限（MB） | `50` |
 | `--convert-timeout-sec <n>` | 可选 | build 自动 convert 请求超时秒数 | `120` |
 | `--convert-force` | 可选 flag | build 自动 convert 覆盖同名 `.md`（否则按 `-1/-2` 追加） | `false` |
-| `--force` | 可选 flag | 覆写已存在的 harness 目录；同时覆写项目根 `AGENTS.md` / `CLAUDE.md`（若存在） | `false` |
+| `--force` | 可选 flag | 覆写已存在的 harness 目录；同时允许覆盖已注入的 build skills/rules 与项目根 `AGENTS.md` / `CLAUDE.md`（默认遇到已存在文件会跳过） | `false` |
 | `-y, --yes` | 可选 flag | 跳过所有提示，采用默认值 | `false` |
 | `--verbose` | 可选 flag | 打印每个生成文件 | `false` |
 
@@ -333,8 +333,10 @@ svharness apply --harness ../my-app-harness --target ./to-apply-project --clone
 此外，`apply` 会同步注入运行期资产：
 
 - `<harness>/agent-env/rules/` → `<target>/<adapter.rulesDir>/`（若该 agent 声明了 `rulesDir`）
-- `<harness>/agent-env/skills/` → `<target>/<adapter.skillsDir>/`（全量注入；`harness-apply-skills-main` 由模板写入为薄入口）
-- 目标 `.gitignore` 会追加注入路径（幂等去重）
+- `<harness>/agent-env/skills/` → `<target>/<adapter.skillsDir>/`（默认跳过同名已存在文件；`--force` 才覆盖。`harness-apply-skills-main` 由模板写入为薄入口）
+- `--include-build-assets` 开启时：同步生成 `<target>/build-agent-env/skills` 与 `<target>/build-agent-env/rules`，用于二次 agent 驱动修改
+- `--inject-build-main-bridge` 开启时：在 `<target>/<adapter.skillsDir>/harness-build-skills-bridge/` 写入桥接 skill（仅用于构建流二次改造）
+- 目标 `.gitignore` 会在文件尾部 append 注入路径（幂等去重）
 
 #### references 内容引用 → apply_skill_registry（S60，由 Agent 写入）
 
@@ -348,7 +350,7 @@ S60（`harness-build-skill-references-intake`）属于 **build 阶段**。若某
 #### build / apply 分工
 
 - **build 阶段**：生成 harness 本体资产（`AGENTS_APPLY.md`、`agent-env/skills`、`agent-env/rules`、`specs`、`baseline` 等）
-- **apply 阶段**：复制 harness 到目标项目、注入 skills/rules、生成入口文件、写 `.gitignore`、校验注入文件引用关系
+- **apply 阶段**：复制 harness 到目标项目、注入 skills/rules、（可选）拷贝构建期 assets、生成入口文件、写 `.gitignore`、输出一致性检查报告
 
 #### 全部参数
 
@@ -356,8 +358,11 @@ S60（`harness-build-skill-references-intake`）属于 **build 阶段**。若某
 |------|----------|------|--------|
 | `--harness <path>` | ✅ 必填 | 已构建好的 harness 目录（形如 `./my-app-harness`） | — |
 | `--target <path>` | 可选 | 目标项目根目录 | **当前工作目录（cwd）** |
-| `--agent <agent>` | 可选 | 目标 Agent：`codechat` / `qoder` / `cursor` / `claude-code` / `opencode` / `generic` | **从 `<harness>/.harness-build-state.yaml` 读取**；缺失则报错 |
+| `--agent <agent>` | 可选 | 目标 Agent：`codechat` / `qoder` / `cursor` / `claude-code` / `opencode` / `generic` | `codechat` |
 | `--clone` | 可选 flag | 兼容参数；当前实现下行为与默认一致（都会拷贝 harness） | `false` |
+| `--include-build-assets` | 可选 flag | 显式拷贝构建期 skills/rules 到 `build-agent-env/`（用于二次改造） | `false` |
+| `--inject-build-main-bridge` | 可选 flag | 向运行期 skills 注入 `harness-build-skills-bridge`（需 `--include-build-assets`） | `false` |
+| `--consistency <mode>` | 可选 | 一致性检查级别：`basic` / `strict`（`strict` 当前为预留模式） | `basic` |
 | `--force` | 可选 flag | 覆盖已存在注入目录与入口文件；同时允许重拷贝 harness | `false` |
 | `-y, --yes` | 可选 flag | 跳过交互确认 | `false` |
 | `--verbose` | 可选 flag | 显示详细日志 | `false` |
@@ -371,10 +376,20 @@ S60（`harness-build-skill-references-intake`）属于 **build 阶段**。若某
 ├── <adapter.skillsDir>/<runtime-skill>/SKILL.{md|mdc}  # 运行期 skills 注入
 ├── <adapter.skillsDir>/harness-apply-skills-main/
 │   └── SKILL.{md|mdc}              # 薄入口 skill（仅提示/索引，不做二级调度）
+├── <adapter.skillsDir>/harness-build-skills-bridge/
+│   └── SKILL.{md|mdc}              # 可选：--inject-build-main-bridge（build 流桥接，不是默认入口）
+├── build-agent-env/                # 可选：--include-build-assets 时生成
+│   ├── skills/                     # 构建期 skills 镜像（可二次改造）
+│   └── rules/                      # 构建期 rules 镜像（可二次改造）
 └── <name>-harness/                 # apply 默认复制后的 harness
 ```
 
-> 注入完成后，CLI 会校验入口文件、薄入口 skill、注入 skills/rules 内的路径引用是否可达；失败会报错中止。
+> 注入完成后，CLI 会输出一致性检查摘要（目录/文件存在性、frontmatter 关键字段、引用可达性），发现问题会给出警告或错误明细供修复。
+
+#### 回滚（bridge 最小清理）
+
+- 软回滚：后续 `apply` 不再传 `--inject-build-main-bridge`。
+- 硬回滚：删除 `<adapter.skillsDir>/harness-build-skills-bridge/` 即可；`build-agent-env/` 可保留用于后续构建流改造。
 
 ### `convert` —— 文档 → Markdown 预处理（对接 S20_collect_inputs）
 
@@ -742,7 +757,7 @@ svharness build --harness-name demo-unknown --arch python --agent codechat `
 - [x] `build` —— 骨架 + 元文件 + 状态文件 + skill 注入
 - [x] 多架构模板（`android-compose` / `android-xml` / `cpp` / `web-react` / `python`）
 - [x] `_shared/` + `<arch>/` 两层叠拷合并
-- [x] 每个架构自带 3-5 条规则文件（`.mdc` 格式，`always_on` 加载）
+- [x] 每个架构自带 3-5 条规则文件（`.mdc` 格式，`alwaysApply: true` 默认启用）
 - [x] `apply` —— 把已构建好的 harness 绑定到目标项目（默认复制模式，`--clone` 兼容保留）
 - [x] 构建辅助资源统一命名（`build-skills/harness-build-skill-*`、`build-rules/harness-build-rule-*`）
 - [ ] `detach` —— 从目标项目解绑并清理 dispatcher skill

package/dist/commands/apply.js

@@ -14,6 +14,7 @@ const validate_args_1 = require("../utils/validate-args");
 const logger_1 = require("../utils/logger");
 const version_1 = require("../utils/version");
 const DISPATCHER_SKILL_NAME = 'harness-apply-skills-main';
+const BUILD_MAIN_BRIDGE_SKILL_NAME = 'harness-build-skills-bridge';
 const BUILD_SKILL_TEMPLATE_FILES = [
     'harness-build-skills-main.md',
     'harness-build-skill-orchestrator.md',
@@ -23,6 +24,16 @@ const BUILD_SKILL_TEMPLATE_FILES = [
     'harness-build-skill-knowledge-builder.md',
     'harness-build-skill-wiki-writer.md',
 ];
+const BUILD_RULE_TEMPLATE_FILES = [
+    'harness-build-rule-agent-agnostic.md',
+    'harness-build-rule-chinese-only.md',
+    'harness-build-rule-convert-check.md',
+    'harness-build-rule-memory-write.md',
+    'harness-build-rule-orchestrator-flow.md',
+    'harness-build-rule-skills-tasks-output.md',
+    'harness-build-rule-specs-schema.md',
+    'harness-build-rule-user-interaction.md',
+];
 const PATH_KEYS = [
     'agent-env/',
     'baseline/',
@@ -278,6 +289,10 @@ async function copyRuntimeSkills(input) {
         const content = input.adapter.transform
             ? input.adapter.transform(rewritten, node_path_1.default.basename(srcSkillFile))
             : rewritten;
+        const syncResult = syncSkillFrontmatterName(content, skillName);
+        if (syncResult.warning) {
+            logger_1.logger.warn(`运行期 skill frontmatter.name 同步失败（保留原文）：${skillName} - ${syncResult.warning}`);
+        }
         const dstSkillDir = node_path_1.default.join(dstDir, skillName);
         const dstSkillFile = node_path_1.default.join(dstSkillDir, 'SKILL' + input.adapter.skillExt);
         if ((await fs_extra_1.default.pathExists(dstSkillFile)) && !input.force) {
@@ -285,7 +300,7 @@ async function copyRuntimeSkills(input) {
             continue;
         }
         await fs_extra_1.default.ensureDir(dstSkillDir);
-        await fs_extra_1.default.outputFile(dstSkillFile, content, 'utf8');
+        await fs_extra_1.default.outputFile(dstSkillFile, syncResult.content, 'utf8');
         written.push(node_path_1.default.relative(input.targetRoot, dstSkillFile));
     }
     return written;
@@ -314,6 +329,32 @@ async function injectThinMainSkill(input) {
     await fs_extra_1.default.outputFile(dstFile, content, 'utf8');
     return dstFile;
 }
+async function injectBuildMainBridgeSkill(input) {
+    const templatePath = node_path_1.default.join(input.templatesRoot, '_shared', 'apply-skills', `${BUILD_MAIN_BRIDGE_SKILL_NAME}.md`);
+    if (!(await fs_extra_1.default.pathExists(templatePath))) {
+        throw new Error(`build-main bridge 模板缺失：${templatePath}`);
+    }
+    const dstDir = node_path_1.default.join(input.targetRoot, input.adapter.skillsDir, BUILD_MAIN_BRIDGE_SKILL_NAME);
+    const dstFile = node_path_1.default.join(dstDir, 'SKILL' + input.adapter.skillExt);
+    if (await fs_extra_1.default.pathExists(dstDir)) {
+        if (!input.force) {
+            throw new Error(`目标 bridge skill 目录已存在：${dstDir}\n  使用 --force 覆盖，或先清理目标目录。`);
+        }
+        await fs_extra_1.default.remove(dstDir);
+    }
+    const raw = await fs_extra_1.default.readFile(templatePath, 'utf8');
+    const rendered = raw
+        .replace(/__HARNESS_ROOT_REL__/g, `./${input.harnessDirName}`)
+        .replace(/__BUILD_SKILLS_DIR__/g, './build-agent-env/skills')
+        .replace(/__BUILD_RULES_DIR__/g, './build-agent-env/rules')
+        .replace(/__APPLY_MAIN_SKILL__/g, DISPATCHER_SKILL_NAME);
+    const content = input.adapter.transform
+        ? input.adapter.transform(rendered, `${BUILD_MAIN_BRIDGE_SKILL_NAME}.md`)
+        : rendered;
+    await fs_extra_1.default.ensureDir(dstDir);
+    await fs_extra_1.default.outputFile(dstFile, content, 'utf8');
+    return dstFile;
+}
 async function updateGitIgnore(input) {
     const gitignorePath = node_path_1.default.join(input.targetRoot, '.gitignore');
     const raw = (await fs_extra_1.default.pathExists(gitignorePath))
@@ -338,9 +379,10 @@ async function updateGitIgnore(input) {
     }
     if (added.length === 0)
         return [];
-    const appendix = '\n# svharness apply injected assets\n' + added.map((line) => `${line}\n`).join('');
-    const next = raw.endsWith('\n') || raw.length === 0 ? raw + appendix : raw + '\n' + appendix;
-    await fs_extra_1.default.outputFile(gitignorePath, next, 'utf8');
+    const prefix = raw.length === 0 ? '' : raw.endsWith('\n') ? '\n' : '\n\n';
+    const appendix = `${prefix}# svharness apply injected assets\n` + added.map((line) => `${line}\n`).join('');
+    await fs_extra_1.default.ensureDir(node_path_1.default.dirname(gitignorePath));
+    await fs_extra_1.default.appendFile(gitignorePath, appendix, 'utf8');
     return added;
 }
 async function validateInjectedReferences(input) {
@@ -365,6 +407,107 @@ async function validateInjectedReferences(input) {
     }
     return failures;
 }
+function extractFrontmatter(content) {
+    const normalized = content.replace(/\r\n/g, '\n');
+    if (!normalized.startsWith('---\n'))
+        return undefined;
+    const endIdx = normalized.indexOf('\n---\n', 4);
+    if (endIdx < 0)
+        return undefined;
+    return {
+        block: normalized.slice(4, endIdx),
+        normalized,
+        endIdx,
+    };
+}
+function extractFrontmatterBlock(content) {
+    return extractFrontmatter(content)?.block;
+}
+function syncSkillFrontmatterName(content, expectedName) {
+    const frontmatter = extractFrontmatter(content);
+    if (!frontmatter) {
+        return { content, changed: false, warning: '缺少 frontmatter' };
+    }
+    let parsed;
+    try {
+        parsed = js_yaml_1.default.load(frontmatter.block);
+    }
+    catch (err) {
+        return { content, changed: false, warning: `frontmatter 解析失败：${err.message}` };
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return { content, changed: false, warning: 'frontmatter 解析为空' };
+    }
+    const currentName = typeof parsed.name === 'string' ? parsed.name.trim() : '';
+    if (currentName === expectedName) {
+        return { content, changed: false };
+    }
+    parsed.name = expectedName;
+    const dumped = js_yaml_1.default.dump(parsed, { lineWidth: 120, noRefs: true }).trimEnd();
+    const rewrittenNormalized = `---\n${dumped}\n---\n` + frontmatter.normalized.slice(frontmatter.endIdx + 5);
+    const hasCrlf = content.includes('\r\n');
+    return {
+        content: hasCrlf ? rewrittenNormalized.replace(/\n/g, '\r\n') : rewrittenNormalized,
+        changed: true,
+    };
+}
+async function validateFrontmatterFields(input) {
+    const warnings = [];
+    if (!(await fs_extra_1.default.pathExists(input.file))) {
+        warnings.push(`${node_path_1.default.relative(input.targetRoot, input.file)} 缺失，无法校验 frontmatter`);
+        return warnings;
+    }
+    const content = await fs_extra_1.default.readFile(input.file, 'utf8');
+    const block = extractFrontmatterBlock(content);
+    if (!block) {
+        warnings.push(`${node_path_1.default.relative(input.targetRoot, input.file)} 缺少 frontmatter`);
+        return warnings;
+    }
+    try {
+        const parsed = js_yaml_1.default.load(block);
+        if (!parsed || typeof parsed !== 'object') {
+            warnings.push(`${node_path_1.default.relative(input.targetRoot, input.file)} frontmatter 解析为空`);
+            return warnings;
+        }
+        for (const key of input.requiredKeys) {
+            if (!(key in parsed)) {
+                warnings.push(`${node_path_1.default.relative(input.targetRoot, input.file)} frontmatter 缺少字段：${key}`);
+            }
+        }
+        if ('alwaysApply' in parsed && typeof parsed.alwaysApply !== 'boolean') {
+            warnings.push(`${node_path_1.default.relative(input.targetRoot, input.file)} frontmatter alwaysApply 应为 boolean`);
+        }
+    }
+    catch (err) {
+        warnings.push(`${node_path_1.default.relative(input.targetRoot, input.file)} frontmatter 解析失败：${err.message}`);
+    }
+    return warnings;
+}
+async function validateSkillNameMatchesDir(input) {
+    const warnings = [];
+    if (!(await fs_extra_1.default.pathExists(input.file)))
+        return warnings;
+    const content = await fs_extra_1.default.readFile(input.file, 'utf8');
+    const block = extractFrontmatterBlock(content);
+    if (!block)
+        return warnings;
+    try {
+        const parsed = js_yaml_1.default.load(block);
+        if (!parsed || typeof parsed !== 'object')
+            return warnings;
+        if (typeof parsed.name !== 'string')
+            return warnings;
+        const expected = node_path_1.default.basename(node_path_1.default.dirname(input.file));
+        const actual = parsed.name.trim();
+        if (actual && actual !== expected) {
+            warnings.push(`${node_path_1.default.relative(input.targetRoot, input.file)} frontmatter.name(${actual}) 与目录名(${expected}) 不一致`);
+        }
+    }
+    catch {
+        // parse failures are already reported by validateFrontmatterFields
+    }
+    return warnings;
+}
 async function saveBuildSkillsToBuildAgentEnv(input) {
     const destRoot = node_path_1.default.join(input.targetRoot, 'build-agent-env', 'skills');
     await fs_extra_1.default.ensureDir(destRoot);
@@ -424,19 +567,70 @@ async function saveBuildSkillsToBuildAgentEnv(input) {
     }
     return written;
 }
+async function resolveRuleSourceFile(rulesRoot, ruleName, ruleExt) {
+    const candidates = [
+        node_path_1.default.join(rulesRoot, `${ruleName}${ruleExt}`),
+        node_path_1.default.join(rulesRoot, `${ruleName}.md`),
+        node_path_1.default.join(rulesRoot, `${ruleName}.mdc`),
+    ];
+    for (const candidate of candidates) {
+        if (await fs_extra_1.default.pathExists(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+async function saveBuildRulesToBuildAgentEnv(input) {
+    if (!input.adapter.rulesDir) {
+        logger_1.logger.info(`agent ${input.adapter.name} 未声明 rulesDir，跳过 build-agent-env/rules 生成`);
+        return [];
+    }
+    const destRoot = node_path_1.default.join(input.targetRoot, 'build-agent-env', 'rules');
+    await fs_extra_1.default.ensureDir(destRoot);
+    const sourceRulesRoot = node_path_1.default.join(node_path_1.default.dirname(input.harnessRoot), input.adapter.rulesDir);
+    const ruleExt = input.adapter.ruleExt ?? '.md';
+    const written = [];
+    for (const templateName of BUILD_RULE_TEMPLATE_FILES) {
+        const ruleName = templateName.replace(/\.md$/i, '');
+        const dstRuleFile = node_path_1.default.join(destRoot, `${ruleName}${ruleExt}`);
+        if ((await fs_extra_1.default.pathExists(dstRuleFile)) && !input.force) {
+            logger_1.logger.warn(`build rule 已存在，跳过：${node_path_1.default.relative(input.targetRoot, dstRuleFile)}`);
+            continue;
+        }
+        let raw;
+        if (await fs_extra_1.default.pathExists(sourceRulesRoot)) {
+            const sourceRuleFile = await resolveRuleSourceFile(sourceRulesRoot, ruleName, ruleExt);
+            if (sourceRuleFile) {
+                raw = await fs_extra_1.default.readFile(sourceRuleFile, 'utf8');
+            }
+        }
+        if (!raw) {
+            const templatePath = node_path_1.default.join(input.templatesRoot, '_shared', 'build-rules', templateName);
+            if (!(await fs_extra_1.default.pathExists(templatePath))) {
+                logger_1.logger.warn(`build rule 模板缺失，跳过：${templateName}`);
+                continue;
+            }
+            raw = await fs_extra_1.default.readFile(templatePath, 'utf8');
+        }
+        const rewritten = rewriteHarnessReferences(raw, input.harnessDirName);
+        const content = input.adapter.ruleTransform
+            ? input.adapter.ruleTransform(rewritten, templateName)
+            : rewritten;
+        await fs_extra_1.default.outputFile(dstRuleFile, content, 'utf8');
+        written.push(node_path_1.default.relative(input.targetRoot, dstRuleFile));
+    }
+    return written;
+}
 /**
  * Entry point for `svharnessbuild apply`.
  *
  * Minimum-invasion binding: copies a single dispatcher skill
  * (`harness-apply-skills-main/SKILL.{md|mdc}`) into the target project's
- * agent-native skills directory. The skill carries the harness binding
- * metadata **inlined into its own body** (`## 绑定元数据` section), so any
- * agent can resolve `harness_root` purely from the skill's loaded content
- * without depending on CWD or "same-directory" heuristics (scheme B).
+ * agent-native skills directory as a thin entry. Runtime rules/skills are
+ * copied into adapter directories, and the project-root AI entry file
+ * (`AGENTS.md` / `CLAUDE.md`) is generated from `<harness>/AGENTS_APPLY.md`.
  *
- * `references/binding.yaml` is still written as a redundant copy for
- * `svharnessbuild`'s own tooling (status / detach / re-apply detection) —
- * it is NOT the runtime source of truth.
+ * Runtime behavior is path-rewrite based (`./<name>-harness/...`), not
+ * dispatcher-embedded binding metadata parsing.
  */
 async function runApply(opts) {
     (0, logger_1.setVerbose)(!!opts.verbose);
@@ -479,7 +673,8 @@ async function runApply(opts) {
     else {
         effectiveHarnessRoot = cloneDest;
     }
-    // 3. Resolve agent (explicit > state file).
+    // 3. Resolve agent (explicit > state file > codechat default).
+    const DEFAULT_AGENT = 'codechat';
     let agent = opts.agent;
     if (!agent) {
         agent = await readAgentFromState(harnessRoot);
@@ -488,16 +683,14 @@ async function runApply(opts) {
         }
     }
     if (!agent) {
-        throw new Error('无法推断目标 agent。请显式传入 --agent <' +
-            (0, validate_args_1.listSupportedAgents)().join('|') +
-            '>，或确认 harness 下存在 .harness-build-state.yaml。');
+        agent = DEFAULT_AGENT;
+        logger_1.logger.info(`未指定 agent，使用默认值：${agent}`);
     }
     const adapter = (0, adapters_1.getAdapter)(agent);
     // 4. Compute injection target.
     const skillsBaseDir = node_path_1.default.join(targetRoot, adapter.skillsDir);
     const dispatcherDir = node_path_1.default.join(skillsBaseDir, DISPATCHER_SKILL_NAME);
     const skillFile = node_path_1.default.join(dispatcherDir, 'SKILL' + adapter.skillExt);
-    const bindingFile = node_path_1.default.join(dispatcherDir, 'references', 'binding.yaml');
     // 5. Load dispatcher skill template.
     const templatePath = node_path_1.default.join(resolveTemplatesRoot(), '_shared', 'apply-skills', `${DISPATCHER_SKILL_NAME}.md`);
     if (!(await fs_extra_1.default.pathExists(templatePath))) {
@@ -513,6 +706,10 @@ async function runApply(opts) {
     const harnessRootRel = node_path_1.default.relative(targetRoot, effectiveHarnessRoot).replace(/\\/g, '/') || '.';
     const cliVersion = (0, version_1.getCliVersion)();
     const appliedAt = new Date().toISOString();
+    const includeBuildAssets = !!opts.includeBuildAssets;
+    const requestedBuildBridge = !!opts.injectBuildMainBridge;
+    const injectBuildMainBridge = includeBuildAssets && requestedBuildBridge;
+    const consistencyMode = opts.consistency === 'strict' ? 'strict' : 'basic';
     // 6. Confirm (unless --yes).
     const configRows = [
         { label: 'harness 源路径', value: harnessRoot },
@@ -525,7 +722,7 @@ async function runApply(opts) {
     if (cloneMode && effectiveHarnessRoot !== harnessRoot) {
         configRows.push({ label: '克隆目标', value: effectiveHarnessRoot });
     }
-    configRows.push({ label: '注入 skill', value: node_path_1.default.relative(targetRoot, skillFile) }, { label: '运行期 skills 注入', value: adapter.skillsDir }, { label: '运行期 rules 注入', value: adapter.rulesDir ?? '（agent 未声明 rulesDir）' }, { label: '.gitignore', value: '将追加注入路径（幂等）' }, { label: '项目根 AI 入口', value: `${adapter.projectEntryFile}（由 AGENTS_APPLY.md 重命名）` }, { label: '工具版本', value: `svharness@${cliVersion}` });
+    configRows.push({ label: '注入 skill', value: node_path_1.default.relative(targetRoot, skillFile) }, { label: '运行期 skills 注入', value: adapter.skillsDir }, { label: '运行期 rules 注入', value: adapter.rulesDir ?? '（agent 未声明 rulesDir）' }, { label: '构建期 assets 拷贝', value: includeBuildAssets ? '开启（build-agent-env）' : '关闭' }, { label: 'build-main 桥接', value: injectBuildMainBridge ? '开启' : '关闭' }, { label: '一致性检查级别', value: consistencyMode }, { label: '.gitignore', value: '将追加注入路径（幂等）' }, { label: '项目根 AI 入口', value: `${adapter.projectEntryFile}（由 AGENTS_APPLY.md 重命名）` }, { label: '工具版本', value: `svharness@${cliVersion}` });
     logger_1.logger.configBox('apply 配置确认', configRows);
     if (!opts.yes) {
         const { ok } = await (0, prompts_1.default)({
@@ -539,6 +736,12 @@ async function runApply(opts) {
             return;
         }
     }
+    if (consistencyMode === 'strict') {
+        logger_1.logger.warn('strict 一致性检查尚在规划中，当前先执行 basic 检查。');
+    }
+    if (requestedBuildBridge && !includeBuildAssets) {
+        logger_1.logger.warn('`--inject-build-main-bridge` 依赖 `--include-build-assets`；当前跳过 bridge 注入。');
+    }
     // 7. Guard against overwrite.
     if (await fs_extra_1.default.pathExists(dispatcherDir)) {
         if (!opts.force) {
@@ -549,8 +752,11 @@ async function runApply(opts) {
     }
     // 7b. Clone step — copy the whole harness into the target project first,
     //     so subsequent injections resolve to the local copy.
-    const totalSteps = 5;
+    const totalSteps = includeBuildAssets ? 6 : 5;
     let stepNo = 1;
+    let buildSkills = [];
+    let buildRules = [];
+    let bridgeSkillPath;
     if (cloneMode && effectiveHarnessRoot !== harnessRoot) {
         logger_1.logger.section(`步骤 ${stepNo}/${totalSteps} - 拷贝 harness 到目标项目`);
         if (await fs_extra_1.default.pathExists(cloneDest)) {
@@ -594,12 +800,53 @@ async function runApply(opts) {
     logger_1.logger.success(`已注入运行期 rules ${runtimeRules.length} 条`);
     logger_1.logger.success(`已注入运行期 skills ${runtimeSkills.length} 条`);
     stepNo++;
+    if (includeBuildAssets) {
+        logger_1.logger.section(`步骤 ${stepNo}/${totalSteps} - 拷贝构建期 skills/rules`);
+        buildSkills = await saveBuildSkillsToBuildAgentEnv({
+            harnessRoot: effectiveHarnessRoot,
+            targetRoot,
+            adapter,
+            harnessRootRel,
+            harnessName,
+            harnessVersion,
+            harnessArch,
+            agent,
+            force: !!opts.force,
+            cliVersion,
+            generatedAt: appliedAt,
+            templatesRoot,
+        });
+        buildRules = await saveBuildRulesToBuildAgentEnv({
+            harnessRoot: effectiveHarnessRoot,
+            targetRoot,
+            adapter,
+            harnessDirName,
+            force: !!opts.force,
+            templatesRoot,
+        });
+        logger_1.logger.success(`已注入构建期 skills ${buildSkills.length} 条`);
+        logger_1.logger.success(`已注入构建期 rules ${buildRules.length} 条`);
+        if (injectBuildMainBridge) {
+            logger_1.logger.info(`build-main bridge 已启用，目标目录：${adapter.skillsDir}/${BUILD_MAIN_BRIDGE_SKILL_NAME}`);
+            bridgeSkillPath = await injectBuildMainBridgeSkill({
+                templatesRoot,
+                targetRoot,
+                adapter,
+                harnessDirName,
+                force: !!opts.force,
+            });
+            logger_1.logger.success(`已写入 build-main bridge：${node_path_1.default.relative(targetRoot, bridgeSkillPath)}`);
+        }
+        stepNo++;
+    }
     logger_1.logger.section(`步骤 ${stepNo}/${totalSteps} - 写入项目根 AI 入口`);
     await (0, apply_project_entry_1.writeApplyProjectEntry)({
         projectRoot: targetRoot,
         harnessRoot: effectiveHarnessRoot,
         harnessDirName,
         adapter,
+        includeBuildBridge: injectBuildMainBridge,
+        buildBridgeSkillName: BUILD_MAIN_BRIDGE_SKILL_NAME,
         force: !!opts.force,
     });
     const entryFile = node_path_1.default.join(targetRoot, adapter.projectEntryFile);
@@ -614,25 +861,84 @@ async function runApply(opts) {
         logger_1.logger.info('.gitignore 无新增条目（已是最新）');
     }
     else {
-        logger_1.logger.success(`.gitignore 已新增 ${ignoreAdded.length} 条注入路径`);
+        logger_1.logger.success(`.gitignore 已 append ${ignoreAdded.length} 条注入路径`);
     }
     stepNo++;
     logger_1.logger.section(`步骤 ${stepNo}/${totalSteps} - 校验注入文件引用关系`);
+    const runtimeRuleFiles = runtimeRules.map((rel) => node_path_1.default.join(targetRoot, rel));
+    const runtimeSkillFiles = runtimeSkills.map((rel) => node_path_1.default.join(targetRoot, rel));
+    const buildRuleFiles = buildRules.map((rel) => node_path_1.default.join(targetRoot, rel));
+    const buildSkillFiles = buildSkills.map((rel) => node_path_1.default.join(targetRoot, rel));
     const filesToCheck = [
         entryFile,
         thinMainPath,
-        ...runtimeRules.map((rel) => node_path_1.default.join(targetRoot, rel)),
-        ...runtimeSkills.map((rel) => node_path_1.default.join(targetRoot, rel)),
+        ...(bridgeSkillPath ? [bridgeSkillPath] : []),
+        ...runtimeRuleFiles,
+        ...runtimeSkillFiles,
+        ...buildRuleFiles,
+        ...buildSkillFiles,
+    ];
+    const consistencyErrors = [];
+    const consistencyWarnings = [];
+    const requiredDirs = [
+        node_path_1.default.join(targetRoot, adapter.skillsDir),
+        ...(adapter.rulesDir ? [node_path_1.default.join(targetRoot, adapter.rulesDir)] : []),
+        ...(includeBuildAssets
+            ? [node_path_1.default.join(targetRoot, 'build-agent-env', 'skills'), node_path_1.default.join(targetRoot, 'build-agent-env', 'rules')]
+            : []),
     ];
+    for (const dir of requiredDirs) {
+        if (!(await fs_extra_1.default.pathExists(dir))) {
+            consistencyErrors.push(`目录缺失：${node_path_1.default.relative(targetRoot, dir)}`);
+        }
+    }
+    for (const file of filesToCheck) {
+        if (!(await fs_extra_1.default.pathExists(file))) {
+            consistencyErrors.push(`文件缺失：${node_path_1.default.relative(targetRoot, file)}`);
+        }
+    }
+    const skillFrontmatterChecks = [...runtimeSkillFiles, ...buildSkillFiles];
+    if (bridgeSkillPath)
+        skillFrontmatterChecks.push(bridgeSkillPath);
+    for (const file of skillFrontmatterChecks) {
+        consistencyWarnings.push(...(await validateFrontmatterFields({
+            targetRoot,
+            file,
+            requiredKeys: ['name', 'description'],
+        })));
+        consistencyWarnings.push(...(await validateSkillNameMatchesDir({
+            targetRoot,
+            file,
+        })));
+    }
+    const ruleFrontmatterChecks = [...runtimeRuleFiles, ...buildRuleFiles];
+    for (const file of ruleFrontmatterChecks) {
+        consistencyWarnings.push(...(await validateFrontmatterFields({
+            targetRoot,
+            file,
+            requiredKeys: ['description'],
+        })));
+    }
     const refFailures = await validateInjectedReferences({
         targetRoot,
         harnessDirName,
         files: filesToCheck,
     });
+    consistencyWarnings.push(...refFailures.map((line) => `引用缺失：${line}`));
+    const okCount = filesToCheck.length + requiredDirs.length - consistencyErrors.length;
+    logger_1.logger.info(`一致性检查（basic）结果：通过 ${Math.max(okCount, 0)} 项，警告 ${consistencyWarnings.length} 项，错误 ${consistencyErrors.length} 项`);
+    if (consistencyErrors.length > 0) {
+        const preview = consistencyErrors.slice(0, 20).join('\n');
+        logger_1.logger.warn(`一致性检查发现 ${consistencyErrors.length} 条错误（请先修复）：\n${preview}\n` +
+            (consistencyErrors.length > 20 ? '...（其余省略）' : ''));
+    }
+    if (consistencyWarnings.length > 0) {
+        const preview = consistencyWarnings.slice(0, 20).join('\n');
+        logger_1.logger.warn(`一致性检查发现 ${consistencyWarnings.length} 条警告：\n${preview}\n` +
+            (consistencyWarnings.length > 20 ? '...（其余省略）' : ''));
+    }
     if (refFailures.length > 0) {
-        const preview = refFailures.slice(0, 20).join('\n');
-        logger_1.logger.warn(`引用校验发现 ${refFailures.length} 条潜在问题（请人工复核）：\n${preview}\n` +
-            (refFailures.length > 20 ? '...（其余省略）' : ''));
+        logger_1.logger.warn(`引用校验发现 ${refFailures.length} 条潜在问题（已并入一致性警告）`);
     }
     else {
         logger_1.logger.success('引用关系校验通过');
@@ -642,8 +948,14 @@ async function runApply(opts) {
     logger_1.logger.plain('✨ harness 已绑定到当前项目');
     logger_1.logger.plain('');
     logger_1.logger.plain('  下一步：在 agent 中输入');
-    logger_1.logger.plain(`    应用 ${DISPATCHER_SKILL_NAME} 完成 <你的功能> 功能开发`);
-    logger_1.logger.plain(`  或阅读 ${adapter.projectEntryFile} 了解完整的 harness 应用工作流`);
+    logger_1.logger.plain(`    应用 ${DISPATCHER_SKILL_NAME} 完成 <你的功能> 功能开发（薄入口）`);
+    logger_1.logger.plain(`  或阅读 ${adapter.projectEntryFile}（项目根入口）了解完整的 harness 应用工作流`);
+    if (includeBuildAssets) {
+        logger_1.logger.plain('  构建期二次改造入口：build-agent-env/skills + build-agent-env/rules');
+        if (injectBuildMainBridge) {
+            logger_1.logger.plain(`  可选桥接入口：${adapter.skillsDir}/${BUILD_MAIN_BRIDGE_SKILL_NAME}/SKILL${adapter.skillExt}`);
+        }
+    }
     logger_1.logger.plain('');
     if (effectiveHarnessRoot !== harnessRoot) {
         logger_1.logger.plain(`  harness 内容已拷贝至：${node_path_1.default.relative(targetRoot, effectiveHarnessRoot)}/（已纳入目标项目）`);

package/dist/commands/init.js

@@ -286,10 +286,10 @@ async function runInit(opts) {
             cliVersion,
             generatedAt: createdAt,
         };
-        const injected = await (0, agent_injector_1.injectSkillsLayered)(buildSkillsSrcs, targetRoot, adapter, cwd, buildSkillsBinding);
+        const injected = await (0, agent_injector_1.injectSkillsLayered)(buildSkillsSrcs, targetRoot, adapter, cwd, buildSkillsBinding, !!opts.force);
         logger_1.logger.success(`已向 ${node_path_1.default.join(cwd, adapter.skillsDir)}/ 注入 skill ${injected.length} 个`);
         logger_1.logger.section(`步骤 4/${totalSteps} - 注入 harness 构建规则`);
-        const rules = await (0, agent_injector_1.injectRulesLayered)(buildRulesSrcs, adapter, cwd);
+        const rules = await (0, agent_injector_1.injectRulesLayered)(buildRulesSrcs, adapter, cwd, !!opts.force);
         if (adapter.rulesDir) {
             logger_1.logger.success(`已向 ${node_path_1.default.join(cwd, adapter.rulesDir)}/ 注入 rule ${rules.length} 个`);
         }

package/dist/config/merge-options.js

@@ -93,6 +93,9 @@ function mergeApplyOptions(cli, configSection, defaults, cmd) {
         agent: pickString('agent', cli.agent, cfg.agent, cmd),
         force: pickBool('force', cli.force, cfg.force, defaults?.force, cmd),
         clone: pickBool('clone', cli.clone, cfg.clone, undefined, cmd),
+        includeBuildAssets: pickBool('includeBuildAssets', cli.includeBuildAssets, cfg.includeBuildAssets, undefined, cmd),
+        injectBuildMainBridge: pickBool('injectBuildMainBridge', cli.injectBuildMainBridge, cfg.injectBuildMainBridge, undefined, cmd),
+        consistency: pickString('consistency', cli.consistency, cfg.consistency, cmd),
         yes: pickBool('yes', cli.yes, cfg.yes, defaults?.yes, cmd),
         verbose: pickBool('verbose', cli.verbose, cfg.verbose, defaults?.verbose, cmd),
     };

package/dist/core/agent-injector.js

@@ -20,6 +20,19 @@ const BUILD_SKILLS = [
     'harness-build-skill-knowledge-builder.md',
     'harness-build-skill-wiki-writer.md',
 ];
+async function writeInjectedFile(input) {
+    const exists = await fs_extra_1.default.pathExists(input.dstPath);
+    const relPath = node_path_1.default.relative(input.baseRoot, input.dstPath);
+    if (exists && !input.overwrite) {
+        logger_1.logger.warn(`${input.kind} 已存在，跳过：${relPath}`);
+        return 'skipped';
+    }
+    await fs_extra_1.default.outputFile(input.dstPath, input.content, 'utf8');
+    if (exists && input.overwrite) {
+        logger_1.logger.warn(`${input.kind} 已存在，--force 覆盖：${relPath}`);
+    }
+    return exists ? 'overwritten' : 'written';
+}
 function buildSkillsBindingYaml(input, adapter) {
     const harness_root_rel = `./${input.harnessDirName.replace(/\\/g, '/')}/`;
     const obj = {
@@ -67,7 +80,7 @@ function applyBuildSkillReplacements(raw, adapter, harnessPrefix, opts) {
  *                      beside the harness folder instead of inside it.
  * @param binding        Metadata for `harness-build-skills-main` (inlined YAML).
  */
-async function injectSkills(skillsSrcDir, targetRoot, adapter, skillsRoot, binding) {
+async function injectSkills(skillsSrcDir, targetRoot, adapter, skillsRoot, binding, force = false) {
     if (!(await fs_extra_1.default.pathExists(skillsSrcDir))) {
         throw new Error(`build-skills source directory missing: ${skillsSrcDir}`);
     }
@@ -100,9 +113,18 @@ async function injectSkills(skillsSrcDir, targetRoot, adapter, skillsRoot, bindi
         const skillDir = node_path_1.default.join(dstDir, baseName);
         await fs_extra_1.default.ensureDir(skillDir);
         const dstPath = node_path_1.default.join(skillDir, 'SKILL' + adapter.skillExt);
-        await fs_extra_1.default.outputFile(dstPath, content, 'utf8');
+        const writeMode = await writeInjectedFile({
+            dstPath,
+            content,
+            overwrite: force,
+            kind: 'skill',
+            baseRoot: base,
+        });
+        if (writeMode === 'skipped') {
+            continue;
+        }
         injected.push(node_path_1.default.relative(base, dstPath));
-        logger_1.logger.debug(`injected skill: ${dstPath}`);
+        logger_1.logger.debug(`${writeMode === 'overwritten' ? 'overwrote' : 'injected'} skill: ${dstPath}`);
     }
     return injected;
 }
@@ -127,7 +149,7 @@ async function injectSkills(skillsSrcDir, targetRoot, adapter, skillsRoot, bindi
  * @param binding        Metadata for `__HARNESS_ROOT__` and inlined YAML in
  *                        `harness-build-skills-main` (`harnessDirName` inside binding).
  */
-async function injectSkillsLayered(skillsSrcDirs, targetRoot, adapter, skillsRoot, binding) {
+async function injectSkillsLayered(skillsSrcDirs, targetRoot, adapter, skillsRoot, binding, force = false) {
     const existing = [];
     for (const d of skillsSrcDirs) {
         if (await fs_extra_1.default.pathExists(d))
@@ -168,9 +190,18 @@ async function injectSkillsLayered(skillsSrcDirs, targetRoot, adapter, skillsRoo
         const skillDir = node_path_1.default.join(dstDir, baseName);
         await fs_extra_1.default.ensureDir(skillDir);
         const dstPath = node_path_1.default.join(skillDir, 'SKILL' + adapter.skillExt);
-        await fs_extra_1.default.outputFile(dstPath, content, 'utf8');
+        const writeMode = await writeInjectedFile({
+            dstPath,
+            content,
+            overwrite: force,
+            kind: 'skill',
+            baseRoot: base,
+        });
+        if (writeMode === 'skipped') {
+            continue;
+        }
         injected.push(node_path_1.default.relative(base, dstPath));
-        logger_1.logger.debug(`injected skill: ${dstPath} (from ${picked})`);
+        logger_1.logger.debug(`${writeMode === 'overwritten' ? 'overwrote' : 'injected'} skill: ${dstPath} (from ${picked})`);
     }
     return injected;
 }
@@ -188,7 +219,7 @@ async function injectSkillsLayered(skillsSrcDirs, targetRoot, adapter, skillsRoo
  * @param adapter       Agent-specific configuration
  * @param rulesRoot     Base directory for the agent rules folder, typically cwd.
  */
-async function injectRulesLayered(rulesSrcDirs, adapter, rulesRoot) {
+async function injectRulesLayered(rulesSrcDirs, adapter, rulesRoot, force = false) {
     if (!adapter.rulesDir) {
         logger_1.logger.info(`agent ${adapter.name} 未声明 rulesDir，跳过 rules 注入`);
         return [];
@@ -233,9 +264,18 @@ async function injectRulesLayered(rulesSrcDirs, adapter, rulesRoot) {
             : raw;
         const baseName = srcName.replace(/\.md$/i, '');
         const dstPath = node_path_1.default.join(dstDir, baseName + ruleExt);
-        await fs_extra_1.default.outputFile(dstPath, content, 'utf8');
+        const writeMode = await writeInjectedFile({
+            dstPath,
+            content,
+            overwrite: force,
+            kind: 'rule',
+            baseRoot: rulesRoot,
+        });
+        if (writeMode === 'skipped') {
+            continue;
+        }
         injected.push(node_path_1.default.relative(rulesRoot, dstPath));
-        logger_1.logger.debug(`injected rule: ${dstPath} (from ${picked})`);
+        logger_1.logger.debug(`${writeMode === 'overwritten' ? 'overwrote' : 'injected'} rule: ${dstPath} (from ${picked})`);
     }
     return injected;
 }

package/dist/core/apply-project-entry.js

@@ -38,6 +38,18 @@ function rewriteEntryReferences(content, harnessDirName) {
         return `\`${toHarnessScopedRef(token, harnessDirName)}\``;
     });
 }
+function renderBuildBridgeHint(input) {
+    if (!input.includeBuildBridge)
+        return '';
+    return [
+        '> 高级模式（仅构建流二次改造场景）',
+        '>',
+        `> - 已启用 bridge skill：\`${input.bridgeSkillName}\`（路径：\`${input.adapter.skillsDir}/${input.bridgeSkillName}/\`）`,
+        '> - 该入口仅用于修改 build-agent-env 下的构建期技能/规则，不作为默认业务开发入口',
+        '> - 普通开发仍以 `harness-apply-skills-main` 为主入口',
+        '',
+    ].join('\n');
+}
 /**
  * Write `AGENTS.md` or `CLAUDE.md` at the target project root by copying
  * `<harness>/AGENTS_APPLY.md` and renaming it to the adapter's entry file.
@@ -59,7 +71,17 @@ async function writeApplyProjectEntry(input) {
         }
     }
     const raw = await fs_extra_1.default.readFile(src, 'utf8');
-    const rewritten = rewriteEntryReferences(raw, input.harnessDirName);
+    const bridgeHint = renderBuildBridgeHint({
+        includeBuildBridge: !!input.includeBuildBridge,
+        adapter: input.adapter,
+        bridgeSkillName: input.buildBridgeSkillName ?? 'harness-build-skills-bridge',
+    });
+    const withBridgeHint = raw.includes('__BUILD_MAIN_BRIDGE_HINT__')
+        ? raw.replace(/__BUILD_MAIN_BRIDGE_HINT__/g, bridgeHint)
+        : bridgeHint.length > 0
+            ? `${raw.trimEnd()}\n\n${bridgeHint}`
+            : raw;
+    const rewritten = rewriteEntryReferences(withBridgeHint, input.harnessDirName);
     await fs_extra_1.default.outputFile(dest, rewritten, 'utf8');
     logger_1.logger.success(`已写入项目根 AI 入口：${rel}（由 AGENTS_APPLY.md 重命名）`);
     return rel;

package/dist/core/extra-assets-intake.js

@@ -231,9 +231,16 @@ function buildSuggestedName(sourcePath, detectedType) {
         .replace(/--+/g, '-');
     if (!normalized)
         return undefined;
+    const skillPrefix = 'harness-apply-skills-';
+    const rulePrefix = 'harness-apply-rules-';
+    const stripped = normalized
+        .replace(new RegExp(`^${skillPrefix}`), '')
+        .replace(new RegExp(`^${rulePrefix}`), '');
+    if (!stripped)
+        return undefined;
     if (detectedType === 'skill')
-        return `harness-apply-skills-${normalized}`;
-    return `harness-apply-rules-${normalized}`;
+        return `${skillPrefix}${stripped}`;
+    return `${rulePrefix}${stripped}`;
 }
 async function allocateName(targetDir, baseName, used) {
     if (!used.has(baseName) && !(await fs_extra_1.default.pathExists(node_path_1.default.join(targetDir, baseName)))) {

package/dist/core/project-ignore.js

@@ -46,8 +46,9 @@ async function appendToIgnoreFile(filePath, entries, marker, createNew) {
     }
     if (added.length === 0)
         return [];
-    const appendix = `\n${marker}\n` + added.map((line) => `${line}\n`).join('');
-    const next = raw.endsWith('\n') || raw.length === 0 ? raw + appendix : raw + '\n' + appendix;
-    await fs_extra_1.default.outputFile(filePath, next, 'utf8');
+    const prefix = raw.length === 0 ? '' : raw.endsWith('\n') ? '\n' : '\n\n';
+    const appendix = `${prefix}${marker}\n${added.map((line) => `${line}\n`).join('')}`;
+    await fs_extra_1.default.ensureDir(node_path_1.default.dirname(filePath));
+    await fs_extra_1.default.appendFile(filePath, appendix, 'utf8');
     return added;
 }

package/dist/index.js

@@ -273,11 +273,12 @@ function main() {
         .option('--config <path>', `从配置文件读取 apply 节（默认 ${config_1.DEFAULT_CONFIG_FILENAME}）`)
         .option('--harness <path>', '已构建好的 harness 目录路径（可在配置文件的 apply.harness 中提供）')
         .option('--target <path>', '目标项目根目录（默认：当前工作目录）')
-        .option('--agent <agent>', '目标 Agent：' +
-        (0, validate_args_1.listSupportedAgents)().join(' | ') +
-        '（省略时从 harness 状态文件读取）')
+        .option('--agent <agent>', '目标 Agent：' + (0, validate_args_1.listSupportedAgents)().join(' | '), DEFAULT_AGENT)
         .option('--force', '覆盖已存在的 dispatcher skill 目录')
         .option('--clone', '拷贝整个 harness 到目标项目（默认 bind-only）')
+        .option('--include-build-assets', '显式拷贝构建期 skills/rules 到 build-agent-env/')
+        .option('--inject-build-main-bridge', '在运行期 skills 中注入 build 主入口桥接 skill（需 include-build-assets）')
+        .option('--consistency <mode>', '一致性检查级别：basic | strict（strict 预留）', 'basic')
         .option('-y, --yes', '跳过交互确认')
         .option('--verbose', '显示详细日志')
         .action(async (opts, cmd) => {
@@ -287,12 +288,23 @@ function main() {
             if (!merged.harness) {
                 throw new Error('--harness <path> 是必填参数（可在配置文件的 apply.harness 中提供）');
             }
+            const agent = (merged.agent ?? DEFAULT_AGENT);
+            if (!(0, validate_args_1.listSupportedAgents)().includes(agent)) {
+                throw new Error(`--agent "${merged.agent}" is not supported. Allowed: ${(0, validate_args_1.listSupportedAgents)().join(', ')}`);
+            }
+            const consistency = merged.consistency ?? 'basic';
+            if (consistency !== 'basic' && consistency !== 'strict') {
+                throw new Error(`--consistency 仅支持 basic | strict，收到：${consistency}`);
+            }
             await (0, apply_1.runApply)({
                 harness: merged.harness,
                 target: merged.target,
-                agent: merged.agent,
+                agent,
                 force: !!merged.force,
                 clone: !!merged.clone,
+                includeBuildAssets: !!merged.includeBuildAssets,
+                injectBuildMainBridge: !!merged.injectBuildMainBridge,
+                consistency,
                 yes: !!merged.yes,
                 verbose: !!merged.verbose,
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svharness",
-  "version": "0.13.2",
+  "version": "0.13.5",
   "description": "CLI scaffolder for SDD-Driven Agent-Agnostic Coding Framework (harness)",
   "bin": {
     "svharness": "./bin/cli.js",

package/templates/_shared/apply-skills/harness-apply-skills-main.md

@@ -1,8 +1,8 @@
 ---
 name: harness-apply-skills-main
 description: >
-  harness 应用入口（薄索引模式）。提示用户当前项目已注入 runtime skills/rules，
-  优先直接调用已注入的 `harness-apply-skills-*` 子 skill；如无匹配，再按普通开发流程执行。
+  harness 应用入口（薄索引模式）。提示用户当前项目已注入 runtime rules/skills，
+  优先遵守 `alwaysApply: true` 规则，匹配最相关 skill；如无匹配，再按普通开发流程执行。
 ---
 
 # harness-apply-skills-main（harness 应用入口）
@@ -16,9 +16,10 @@ description: >
 ## 使用原则
 
 1. 优先枚举当前项目已注入的 `harness-apply-skills-*` 子 skill，并调用最匹配者完成任务。
-2. 每次任务必须遵守已注入的 rules（always_on 优先）。
+2. 每次任务必须遵守已注入 rules 中 `alwaysApply: true` 的硬约束。
 3. 若没有匹配 skill，按普通实现流程完成，但仍需参考 `__HARNESS_ROOT_REL__/specs/`、`__HARNESS_ROOT_REL__/baseline/`。
 4. 不修改 `__HARNESS_ROOT_REL__` 下的任何文件；harness 作为只读知识源。
+5. 入口链路以项目根 AI 入口文档为准：`AGENTS.md` 或 `CLAUDE.md`。
 
 ## 典型触发
 
@@ -29,4 +30,5 @@ description: >
 ## 注意
 
 - 本 skill 不负责二级调度与 binding 解析。
+- 本 skill 不替代项目根应用指南；仅做入口提示与路由索引。
 - 如发现路径不一致，请重新执行 `svharness apply --force`。

package/templates/_shared/apply-skills/harness-build-skills-bridge.md

@@ -0,0 +1,29 @@
+---
+name: harness-build-skills-bridge
+description: >
+  build 流程桥接入口。仅用于已启用 include-build-assets 的场景，
+  指引 Agent 进入 build-agent-env 下的构建期技能与规则，不替代 apply 主入口。
+---
+
+# harness-build-skills-bridge（build 流程桥接入口）
+
+你是一个 **构建流桥接提示器**。此入口仅用于“二次改造 harness 构建流程”。
+
+- harness 根目录：`__HARNESS_ROOT_REL__`
+- 构建期 skills：`__BUILD_SKILLS_DIR__`
+- 构建期 rules：`__BUILD_RULES_DIR__`
+- 运行期默认入口：`__APPLY_MAIN_SKILL__`
+
+## 使用边界
+
+1. 普通业务开发默认走 `__APPLY_MAIN_SKILL__`，不要把本桥接当作默认入口。
+2. 仅当用户明确要求“修改构建流 / 调整 build 规则 / 演进 build skill”时，才使用本桥接。
+3. 构建期改造优先在 `__BUILD_SKILLS_DIR__` 与 `__BUILD_RULES_DIR__` 中进行。
+4. 不直接把整套 build skills/rules 注入为运行期默认能力。
+5. 产出后需执行一致性自检（frontmatter 字段、引用可达、目录存在性）。
+
+## 典型触发
+
+- 使用 build bridge 调整 harness 构建流程
+- 修改 build-agent-env 下的构建期技能
+- 对构建期规则做最小侵入修订

package/templates/_shared/build-rules/harness-build-rule-convert-check.md

@@ -11,11 +11,13 @@ Agent 在进入 S30_convert_docs 阶段后必须逐一检查以下两个目录
 
 ## 转换前置检查
 
-对上述两个目录执行以下检查：
+对上述两个目录执行以下检查（**必须同时读取 `raw/` 与 `md/`，不得只扫 raw**）：
 
-1. **列出原始文件**：扫描目录，识别所有非 `.md`、非 `.gitkeep` 的文件（如 `.pdf`、`.docx`、`.pptx`、`.xlsx`、`.html`、`.txt`、`.csv` 等）。
-2. **检查对应 md 是否存在**：对每个原始文件，检查对应 `md/` 目录中是否存在同基名的 `.md` 文件（如 `requirements/raw/需求文档.pdf` → `requirements/md/需求文档.md`）。
-3. **判断是否需要转换**：仅当 `md/` 中缺少对应文件时，才需要执行转换；已存在的跳过。
+1. **列出原始文件**：扫描 `raw/`，识别所有非 `.md`、非 `.gitkeep` 的文件（如 `.pdf`、`.docx`、`.pptx`、`.xlsx`、`.html`、`.txt`、`.csv` 等）。
+2. **列出已有产物**：扫描对应 `md/`，列出已有 `.md`（忽略 `.gitkeep`）。
+3. **同基名配对**：对每个原始文件，检查 `md/` 中是否存在同基名的 `.md`（如 `requirements/raw/需求文档.pdf` → `requirements/md/需求文档.md`）。`svharness build` 自动 convert 或用户手工放入的产物均算已完成。
+4. **判断是否需要转换**：仅当 `md/` 中缺少同基名文件时才转换；**`raw/` 中仍保留 pdf/docx 不代表未转换**（源文件不得删除）。
+5. **常见误判**：勿将 `raw/` 内已是 `.md` 的文件计入待转换；勿忽略 `md/` 已有文件；若产物在 `raw/**/converted_md/`，应移至对应 `md/` 后再判定。
 
 ## 转换方式（按优先级）
 

package/templates/_shared/build-skills/harness-build-skill-agent-env-merge.md

@@ -49,6 +49,8 @@ description: >
 - 额外 skill 目录建议：`harness-apply-skills-<topic>`
 - 额外 rule 文件建议：`harness-apply-rules-<topic>.md` / `.mdc`
 - 命名不合规时必须先给重命名建议，不得直接写入。
+- 若 skill 目录被重命名，必须同步修改该目录下 `SKILL.md` 的 frontmatter `name` 字段为新目录名。
+- 若 skill 文档一级标题显式包含旧 skill 名，也必须同步改为新名，避免目录名与文档语义漂移。
 
 ## 状态更新
 

package/templates/_shared/build-skills/harness-build-skill-orchestrator.md

@@ -43,12 +43,12 @@ description: >
     5. 类型确认：若输入包含规则文件或无法识别类型的资源，提示将由 S65 根据 `__HARNESS_ROOT__agent-env/_incoming/manifest.yaml` 做分流确认（skill→`agent-env/skills/`，rule→`agent-env/rules/`）。
     **关键约束**：用户选择"不新增"仅表示不再添加新文件，**不等于**跳过本阶段；仍须完成第 1 步盘点并基于 `raw/` 现有文件做确认后方可退出。
     **退出条件**：已完成第 1 步盘点；`requirements/raw/` 存在真实文档；其余项完成"已提供/无新增"确认。严禁自动生成占位文档。
-  - **S30_convert_docs** — 将 `raw/` 中的非 Markdown 原始文档统一转换为 Markdown：
-     1. 检查 `__HARNESS_ROOT__requirements/raw/` 中是否有非 `.md`、非 `.gitkeep` 的文件。
-     2. 检查 `__HARNESS_ROOT__references/raw/` 中是否有非 `.md`、非 `.gitkeep` 的文件。
-     3. 若有，以表单提示用户运行 `svharness convert --input <path> --output __HARNESS_ROOT__ --type requirements`（或 references）将文档转为 md；也可由 Agent 直接调用 CLI（若运行环境支持）。
-     4. 校验两个 `md/` 目录是否已包含 `raw/` 中每份源文档对应的 `.md` 文件。
-    5. 全部完成后标记 DONE 并推进到 S40_extract_requirements。
+  - **S30_convert_docs** — 将 `raw/` 中的非 Markdown 原始文档统一转换为 Markdown（**必须遵守 `harness-build-rule-convert-check`，同时盘点 raw 与 md 并按同基名配对**）：
+     1. **四目录盘点（不可跳过）**：分别列出 `__HARNESS_ROOT__requirements/raw/`、`requirements/md/`、`references/raw/`、`references/md/` 的文件清单。不得仅因 `raw/` 中仍存在 `.pdf`/`.docx` 等就判定“待转换”——转换后原始文件**故意保留**在 `raw/`。
+     2. **配对判定**：对每个 `raw/` 中的非 `.md`、非 `.gitkeep` 源文件，检查对应 `md/` 是否已有**同基名** `.md`（如 `foo.pdf` → `md/foo.md`；`清单.csv` → `md/清单.md`）。仅当 `md/` 缺失时才计入待处理。
+     3. **状态卡片写法**：`已完成` 只写已配对的 requirements/references 项；`待处理` **只列** md 仍缺失的源文件。禁止把“raw 里有多少个非 md 文件”直接等同于待转换数量。
+     4. 对待处理项：优先调用 `svharness convert`（或表单提示用户运行 CLI）；若 `md/` 已有同基名 `.md` 则**跳过转换**。
+     5. 全部配对完成后标记 DONE 并推进到 S40_extract_requirements。
   - **S40_extract_requirements** — 委派给 `harness-build-skill-spec-builder`（需求条目化提取到 `__HARNESS_ROOT__requirements/yaml/`）。
   - **S50_generate_specs** — 委派给 `harness-build-skill-spec-builder`（生成受 schema 校验的 YAML）。
   - **S60_process_references**（references 处理）— 仅处理 references：执行 `svharness convert`，产出结构化索引（规制约束 / skills 候选 / signals / manuals），并通过表单确认落地策略；委派给 `harness-build-skill-references-intake`。

package/templates/_shared/meta/AGENTS_APPLY.md.ejs

@@ -4,8 +4,8 @@
 > 与 `AGENTS_BUILD.md`（构建指南）互补：`AGENTS_BUILD.md` 驱动 harness 本体的构建与演进，
 > **本文件驱动 harness 知识向目标项目的落地执行**。
 >
-> 如果你是通过 `svharnessbuild apply` 注入的 `harness-apply-skills-main` skill
-> 进入的，请先执行该 skill 的调度流程，再参照本文件的守则补充上下文。
+> 若你通过 `svharness apply` 触发了 `harness-apply-skills-main`，它是薄入口提示器；
+> **实际开发流程以本文件为准**。
 
 ## 1. 前置条件
 
@@ -20,23 +20,45 @@
 > 若 harness 尚未完成构建（如 `S70_runtime_assets` 仍为 `PENDING`），
 > 建议先回到 harness 本体执行构建流程，而非直接应用。
 
-## 2. 加载约束与能力
+## 2. apply 注入布局（先识别执行面）
 
-### 2.1 强约束（必须遵守）
+`svharness apply` 完成后，运行时通常存在三类路径：
+
+1. 项目根入口：`AGENTS.md` 或 `CLAUDE.md`（由本文件重命名写入）
+2. 运行时注入目录（以 adapter 为准）：
+   - rules：`<target>/<adapter.rulesDir>/`
+   - skills：`<target>/<adapter.skillsDir>/`
+3. harness 只读知识库：`./<name>-harness/`
+
+若 `svharness apply` 使用了 `--include-build-assets`，还会存在：
+
+4. 构建期二次改造目录：`build-agent-env/skills/` + `build-agent-env/rules/`
+
+__BUILD_MAIN_BRIDGE_HINT__
+
+执行建议：
+
+- 编码阶段优先遵守 **注入到 adapter 目录** 的 rules/skills（这是 agent 直接可见层）
+- 规格、基线、references 从 `./<name>-harness/` 读取（只读）
+- 需要重构 harness 工作流时，优先在 `build-agent-env/` 下调整构建期 skill/rule，再通过一致性检查确认可用
+
+## 3. 加载约束与能力
+
+### 3.1 强约束（必须遵守）
 
 枚举并读取 `agent-env/rules/` 下所有规则文件：
 
-- `always_on` 规则 —— **每次任务都必须遵守**，不得跳过
-- `model_decision` 规则 —— 按本次任务语义挑选适用规则
+- frontmatter 中 `alwaysApply: true` 的规则 —— **每次任务都必须遵守**，不得跳过
+- frontmatter 中非 `alwaysApply: true` 的规则 —— 按本次任务语义挑选适用规则
 
-规则冲突时以 `always_on` 规则为准。典型约束包括但不限于：
+规则冲突时以 `alwaysApply: true` 规则为准。典型约束包括但不限于：
 
 - `harness-compose-mandatory.mdc` —— Compose UI 强制规范
 - `harness-mvi-layering.mdc` —— MVI 分层约束
 - `harness-hilt-injection.mdc` —— 依赖注入规范
 - `harness-coroutines-scope.mdc` —— 协程作用域规范
 
-### 2.2 子能力（按需调用）
+### 3.2 子能力（按需调用）
 
 枚举 `agent-env/skills/*/SKILL.md`，提取 `name` + `description` 建立路由表。
 不要整目录朗读，按需要再深读。典型子能力包括：
@@ -48,19 +70,29 @@
 - `harness-kotlin-coroutines` —— 协程最佳实践
 - `harness-android-cli` —— ADB / Gradle 命令
 
-## 3. 开发工作流
+### 3.3 references 路由（内容引用）
+
+若任务命中 `references/apply-skills-registry.yaml` 中登记项：
+
+- 先读取对应 `reference_md` 原文（位于 `references/md/`）
+- 按原文流程与 entry 指令执行
+- 仍需同时遵守 rules 与 specs
+
+若未命中登记项，再回到普通 skill 路由。
+
+## 4. 开发工作流
 
 ```
 用户需求 → 加载约束 → 语义路由 → 查阅基线/规格 → 编码 → 校验 → 交付
 ```
 
-### 3.1 理解需求
+### 4.1 理解需求
 
 - 明确功能边界：是新增、修改还是重构？
 - 若存在 `specs/` 中对应的规格文件，**必须先对齐 schema** 再编码
 - 若需求与现有规格冲突，先提规格变更，再写代码
 
-### 3.2 查阅基线与规格
+### 4.2 查阅基线与规格
 
 按需参考以下目录（均在 harness 根下）：
 
@@ -74,22 +106,27 @@
 | `specs/interfaces/` | 接口规格 | 只读 |
 | `tasks/templates/` | 任务模板 | 只读 |
 
-> **禁止引用 `baseline/code/` 之外的源码**作为"参考实现"。
+> `baseline/code/` 是“参考实现”的权威来源。  
+> 你仍需阅读并修改目标项目业务源码来完成交付，但不得把 `baseline/code/` 之外的路径当作规范样本来源。
 
-### 3.3 编码执行
+### 4.3 编码执行
 
 - **所有代码写在目标项目下**，不得修改 harness 目录内的文件
 - 引用 harness 文件时使用相对路径
 - 严格遵守 `agent-env/rules/` 中的所有约束
 - 产出必须同时满足 `specs/`（做什么）与 `agent-env/rules/`（怎么做）
 
-### 3.4 交付校验
+### 4.4 交付校验
 
-- 涉及 specs 的任务，产物必须通过 `specs/*/schema.json` 校验
+- 涉及 specs 的任务，产物需与 `specs/*/schema.json` 一致（工具可用时执行自动校验）
 - 代码改动不得违反 `agent-env/rules/` 中的规则
 - 在 PR 描述中记录每一条外部假设
+- 若存在 `build-agent-env/`，额外执行一致性自检：
+  - 目录存在性：`build-agent-env/skills`、`build-agent-env/rules`
+  - frontmatter 关键字段：skill 至少包含 `name`、`description`；rule 至少包含 `description`
+  - 引用可达性：文档中的相对路径需能解析到实际文件
 
-## 4. 记忆沉淀
+## 5. 记忆沉淀
 
 若本次开发产生了可复用经验：
 
@@ -97,41 +134,41 @@
 - 经人工审核后转入 `agent-env/memory/categories/`
 - 不确定时停住询问，不得擅自归档
 
-## 5. 守则（不得违反）
+## 6. 守则（不得违反）
 
 - **不得修改 harness 目录下的文件**（rules / skills / specs / baseline / VERSION）
   harness 是只读知识源，演进由构建流程负责
 - **不得绕过绑定元数据**猜测 harness 路径；路径错误须让用户重新绑定
-- **不得把 `always_on` 规则当成"建议"**——它们是硬约束
+- **不得把 `alwaysApply: true` 规则当成"建议"**——它们是硬约束
 - **不得引用 `baseline/code/` 之外的源码**作为参考实现
 - 所有面向用户的说明使用**中文**；字段名、类名、路径保留英文
 - 多个子 skill 有冲突结论时，显式告知用户并请其裁决
 
-## 6. 典型应用示例
+## 7. 典型应用示例
 
-### 示例 1：新增设置项页面
+### 示例 1：新增配置项功能
 
 ```
-用户：基于 harness 新增"显示设置"Fragment
+用户：基于 harness 新增“配置项 A”
 Agent：
-  1. 加载 harness-compose-mandatory.mdc + harness-mvi-layering.mdc
-  2. 路由到 harness-compose-ui skill
-  3. 查阅 specs/ui/ 中是否有显示设置相关规格
-  4. 参考 baseline/code/ 中的 Fragment 样本
-  5. 在目标项目 src/ 下编写 Compose UI + ViewModel + Repository
-  6. 校验规格一致性
+  1. 读取 `alwaysApply: true` 规则并装载
+  2. 语义匹配最相关子 skill（或 references 登记项）
+  3. 查阅对应 specs（ui/behavior/interfaces）
+  4. 参考 baseline/code/ 中同类实现样本
+  5. 在目标项目源码目录完成实现
+  6. 校验与 schema / rules 一致
 ```
 
-### 示例 2：新增协议信号
+### 示例 2：新增协议字段解析
 
 ```
 用户：按 harness 规范实现 CMDID 0xA3 信号解析
 Agent：
-  1. 加载 harness-mvi-layering.mdc
+  1. 加载 `alwaysApply: true` 规则
   2. 查阅 specs/signals/ 中的信号规格
-  3. 参考 baseline/code/ 中的现有信号解析代码
-  4. 编写信号解析 + 状态层
-  5. 通过 specs/signals/schema.json 校验
+  3. 参考 baseline/code/ 中同类型解析实现
+  4. 在目标项目实现解析与状态更新
+  5. 对齐 signals schema 并完成校验
 ```
 
 ---

package/templates/svharness.config.example.yaml

@@ -28,7 +28,11 @@ build:
 apply:
   harness: ./my-app-harness
   target: .
+  agent: codechat
   clone: false
+  includeBuildAssets: false
+  injectBuildMainBridge: false
+  consistency: basic
   yes: true
 
 # convert：output 无 harness.yaml 时写入该目录；有 harness.yaml 时写入 <output>/<type>/md/