@chriszp/harness-config

PKPMCloud 前端项目 AI Harness 统一配置工具。

为什么需要这个包？

团队有 30+ 个前端仓库（Vue 2 微应用、Vue 3 应用、React 应用、共享依赖包），每个仓库都需要配置 CLAUDE.md、.claude/settings.json、hooks、skills 等 AI 辅助工程的规则文件。如果每个仓库独立维护：

• 重复劳动 — 同样的权限规则、代码规范、组件模板在每个仓库手动复制
• 规则漂移 — 各仓库的配置逐渐分化，AI 行为不一致
• 升级困难 — 一条通用规则变更，需要到 30 个仓库逐一修改
• 新人接入慢 — 新项目从零配置 AI Harness，不知道有哪些规则

本包将这些通用规则集中管理，作为 npm 包发布，各项目按需接入。

核心能力

| 能力 | 说明 | |------|------| | 9 条通用协作规则 | 先思后码、简单至上、外科手术式修改、目标驱动执行、暴露冲突、落笔前阅读、检查点、遵从既有规范、显式失败 —— 所有模板统一包含 | | AI 驱动项目检测 | harness init 自动扫描 package.json、Vue 版本、构建工具、微前端框架、状态管理等，展示技术栈摘要后确认 | | 两层规则体系 | ALWAYS（全局强制，9 条通用规则 + 代码规范 + 禁止事项）+ CONTEXTUAL（按目录/模块触发，如 qiankun、状态管理、版本发布） | | 统一权限模型 | 所有项目的 deny/allow/ask 规则基座一致，危险操作硬禁止 | | 可复用 Skills | 创建组件、代码审查、发布包等高频操作封装为 skill | | 自动同步 + 定制区 | HARNESS:AUTO 区由 harness sync 统一升级，HARNESS:CUSTOM 区保留项目自有内容，互不覆盖 |

安装

npm install -D @chriszp/harness-config --registry=http://222.249.116.8:9010/

命令

npx harness init

初始化项目的 AI Harness 配置。自动检测技术栈，交互式确认后生成：

• CLAUDE.md — AI 上下文文件（AUTO 区 ≤ 100 行）
• .claude/settings.json — 权限配置
• .claude/hooks/ — 自动化 hooks（可选）
• .claude/skills/ — 可复用 skills（可选）

# 交互式（推荐）
npx harness init

# 指定类型 + 全量输出（CI / 脚本使用）
npx harness init -t vue3-app -a

# 强制覆盖
npx harness init -t dep -f

npx harness sync

升级包后同步模板更新。只覆盖 HARNESS:AUTO 区域，保留 HARNESS:CUSTOM 中的项目自有内容。

npx harness sync

npx harness check

CI 中使用，检查 AI Harness 配置是否合规。

npx harness check
# 退出码 0 = 合规, 1 = 存在问题

项目类型

| 类型 | 适用场景 | |------|---------| | vue3-app | Vue 3 应用（Vite / Vue CLI，可选 qiankun） | | vue2-app | Vue 2 + qiankun 微应用 | | react-app | React 应用（Hooks + TypeScript） | | dep | dep/ 共享依赖包 | | standalone | 独立仓库（TypeScript 通用） | | root | monorepo 根目录 |

模板设计

AUTO / CUSTOM 分层

<!-- ═══ HARNESS:AUTO — harness sync 会覆盖 ═══ -->
... 9 条通用规则 + 技术栈规范 + 禁止事项 + CONTEXTUAL 规则 ...

<!-- ═══ HARNESS:CUSTOM — harness sync 不会覆盖 ═══ -->
... 项目概述、技术栈、命令、关键文件、特有约束 ...

ALWAYS / CONTEXTUAL 两层规则

• ALWAYS：9 条通用协作规则 + 代码规范 + 禁止事项，所有任务生效
• CONTEXTUAL：按触发条件激活，仅编辑相关文件时适用（如 qiankun 约束仅在编辑构建/路由配置时激活）

目录结构

harness-config/
├── bin/cli.js              # CLI 入口（init / sync / check）
├── templates/
│   ├── claude/             # CLAUDE.md 模板（6 种项目类型）
│   └── settings/           # settings.json 模板（root / dep / app）
├── configs/                # 共享 tsconfig / eslint / prettier
├── hooks/                  # 自动化钩子脚本
├── skills/                 # 可复用技能定义
└── docs/                   # 接入文档

升级

# 必须加 @latest，否则 npm 的 ^ 范围会阻止跨 minor 升级
npm install -D @chriszp/harness-config@latest --registry=http://222.249.116.8:9010/
npx harness sync