# AI Tool

**Repository Path**: WangDKB/ai-tool

## Basic Information

- **Project Name**: AI Tool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-24
- **Last Updated**: 2026-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Portable AI Engineering Harness

这是项目无关的 AI 辅助开发骨架，用于把同一套方法、验证门禁和模块知识管理迁移到不同仓库、技术栈和业务模块。

第一次使用请先阅读：[lucyharness/TUTORIAL.md](lucyharness/TUTORIAL.md)。完整设计背景与演进说明见：[从 Prompt 到 Portable Harness](lucyharness/FROM-PROMPT-TO-HARNESS.md)。

## 四层结构

```text
Core                方法论、任务分级、验证、Evidence、恢复机制
Project Adapter     仓库、技术栈、分层、构建和测试约定
Module Adapter      业务模块、状态机、外部 API、数据契约和风险门
Runtime Adapter     Claude Code 原生 settings、skills、agents、rules
```

## 能力速查（场景 → 工具）

日常只记 `python h.py`（任务导向菜单）；下表按场景给出首选工具与触发时机。V0–V1 琐碎单文件改动只需 `diff-classify`，V2+（多文件 / 行为性）或 V3+（并发 / 重试 / 跨进程）才走 task 闭环。

| 场景 | 首选 | 时机 |
|---|---|---|
| 初始化 / 刷新项目适配 | `project-init` skill / `init` | 项目接入或事实源变化 |
| 开始一个改动 | `diff-classify`；V2+ 加 `task start` | 开工，事前记录预期深度 |
| 改完自检 | `check` | 写完，跑 validate + health |
| 收工交付 | `task done` + `evidence-check`；V2+ 必须有 evidence | 收工，事后核对缺口 |
| 长任务中断保护 | `task-checkpoint` / `task-recover` | 长任务或跨会话 |
| 写操作回滚 | `backup-restore` | recover 报需要人工介入时 |
| 建模块知识 | `module-lifecycle` skill / `module init` + `lifecycle` | 新业务模块接入 |
| 模块健康巡检 | `module-drift-check` skill / `module-drift` + `references-drift` | 模块或源码变化后 |
| 交付前总验证 | `harness-verify` skill | 合并 / 发布前 |
| 改了内核怕改坏 | `eval` | 内核或共享逻辑改动后 |
| 下游对齐模板 | `parity-check` | 内核同步到下游后 |
| 新增项目专家 | `project-expert-scaffold` skill | 反复出现的项目知识需固化时（显式确认才写入） |
| 模板发布检查 | `release-check` skill / `release-check` | 打包、发布或同步共享模板前 |

所有命令支持 `--format json`（agent 自动化）和 `--format text`（人看）；内部异常默认只给一行信封，加 `--debug` 才看完整堆栈。提交阻断只由 pre-commit（`check`，仅配置 / 结构 ERROR）负责；evidence / diff / parity / eval 是审查节点显式调用的软门禁，不进 commit 门禁。

## 目录

```text
portable-solution-template/
├── CLAUDE.md
├── README.md
├── harnessctl.py              # 公开 CLI 启动器
├── h.py                       # 引导式交互入口（无参数开菜单）
├── .claude/                   # Claude Code Runtime Adapter（发现入口）
│   ├── settings.json
│   ├── README.md
│   ├── skills/                       # 显式触发的 workflow（仅一级目录可发现）
│   │   ├── project-init/SKILL.md
│   │   ├── harness-verify/SKILL.md
│   │   ├── harness-health/SKILL.md
│   │   ├── module-lifecycle/SKILL.md
│   │   ├── module-drift-check/SKILL.md
│   │   ├── evidence-gate/SKILL.md
│   │   ├── task-start/SKILL.md
│   │   ├── task-done/SKILL.md
│   │   ├── task-checkpoint/SKILL.md
│   │   ├── task-recover/SKILL.md
│   │   ├── backup-restore/SKILL.md
│   │   ├── project-expert-scaffold/SKILL.md
│   │   └── release-check/SKILL.md
│   ├── agents/                       # 递归分组；frontmatter name 全树唯一
│   │   ├── core/harness-architect.md          # 共享方法论专家（parity 强制）
│   │   ├── project/project-adapter-reviewer.md
│   │   ├── modules/module-knowledge-reviewer.md
│   │   ├── domain/                            # 可选：下游领域专家扩展点（不参与 parity）
│   │   └── stack/                             # 可选：下游技术栈专家扩展点（不参与 parity）
│   └── rules/
│       ├── core/operating-model.md
│       ├── project/project-adapter.md
│       └── modules/module-lifecycle.md
└── lucyharness/               # 自包含的可移植内核与事实源
    ├── METHODOLOGY.md
    ├── TUTORIAL.md
    ├── MIGRATION-CHECKLIST.md
    ├── COMPATIBILITY.md
    ├── CHANGELOG.md
    ├── VERSION
    ├── tools/
    │   ├── harnessctl.py
    │   ├── harnesslib/
    │   └── hooks/pre-commit
    ├── harness/
    │   ├── project.config.json
    │   ├── modules.registry.json
    │   ├── validation.rules.json
    │   ├── evidence.schema.json
    │   └── schemas/
    ├── references/
    │   ├── core/
    │   ├── project/
    │   └── modules/
    ├── state/                  # task-start card、canonical task-state 与 Markdown checkpoint
    ├── tests/
    └── examples/
```

## 安装模型

1. 将模板内容合并复制到目标仓库根目录，保留其中的 `.claude/` 目录。
2. 不要把整个 `portable-solution-template` 目录重命名为 `.claude`；可移植内核与事实源集中在 `lucyharness/` 下，根 `harnessctl.py`、`h.py` 是启动器。
3. 从目标仓库根目录或任意子目录启动 Claude Code 会话，使 Claude Code 能发现根 `CLAUDE.md` 和项目级 `.claude/`。
4. 运行 `python harnessctl.py init --dry-run --format json` 预检项目适配，再运行 `init` 或手工填写 `lucyharness/harness/project.config.json` 与 `lucyharness/references/project/`。
5. 从空的 `lucyharness/harness/modules.registry.json` 开始注册真实模块，并为成熟模块维护 `lucyharness/references/modules/<module-name>/` 知识包。
6. 用一条低风险真实需求跑通：路由、计划、实现、验证、审查、Evidence、References 更新。

## Claude Code 发现行为

- 根 `CLAUDE.md` 是项目级 Claude Code 指导文件。
- `.claude/settings.json` 是安全最小 JSON object；本模板不启用会自动修改或阻断工作的 hooks。
- `.claude/skills/` 只发现直接一级 skill 目录，例如 `.claude/skills/harness-health/SKILL.md`。不支持 `.claude/skills/core/<skill>/SKILL.md` 这种分组嵌套。
- `.claude/agents/` 允许递归分组，但所有 agent frontmatter `name` 必须全树唯一。
- `.claude/rules/` 存放 Claude Code 规则；Project 规则的 `paths` 只能覆盖 `lucyharness/harness/project.config.json` 与 `lucyharness/references/project/**`，Module 规则只能覆盖 `lucyharness/harness/modules.registry.json` 与 `lucyharness/references/modules/**`。
- 不创建新的 `.claude/commands`。Commands 在本模板中视为 legacy；新增能力优先写成 skills。
- `lucyharness/references/` 和未来可能存在的 `scripts/` 都是普通仓库文件，除非被 skill、hook 或 CLI 显式调用，不会被当作 Claude Code 自动发现入口。

## 可运行内核

本模板内置 `harnessctl`，要求 Python 3.10 或更高版本（推荐 3.11/3.12），运行时仅使用 Python 标准库，支持 Windows/Linux。Skills 统一通过公开 CLI 调用，不直接 import 内部函数。自动化可继续使用 `python harnessctl.py ...`；人工命令也可在 POSIX 使用 `sh harnessctl ...`、在 Windows 使用 `harnessctl.cmd ...`，启动器会探测 `python3`、`python` 或 `py -3`，也可通过 `HARNESS_PYTHON` 指定解释器路径。

### 日常入口：无需记命令

人工操作首先只需要记住：

```bash
python h.py
```

不带子命令时会打开任务导向菜单，按“检查仓库”“分析变更”“管理模块知识”“保存或恢复任务进度”等任务选择即可。菜单会询问必要参数，并显示最终执行的完整命令。

高频用户可以额外使用三个快捷方式：

```bash
python h.py c
python h.py d --files README.md lucyharness/harness/project.config.json
python h.py m init orders --paths "src/orders/**"
```

其他低频操作直接使用完整名称，例如 `python h.py backup-restore --list`。`h.py` 与 `harnessctl.py` 使用同一个 CLI；自动化、CI 和 Skills 继续使用完整的 `harnessctl.py` 入口。已有别名继续兼容，但不要求用户记忆。

### 入口

```bash
python harnessctl.py version
python harnessctl.py validate --format text
python harnessctl.py validate --format json
python harnessctl.py health --format text
python harnessctl.py health --format json
python harnessctl.py diff-classify --files README.md lucyharness/harness/project.config.json --format json
python harnessctl.py module-drift --format json
python harnessctl.py references-drift --files src/payments/service.py --format json
python harnessctl.py checkpoint --input task.md --output state/current-task.md --format json
python harnessctl.py recover --format json
python harnessctl.py recover --details --format json
python harnessctl.py backup-restore --list --format json
python harnessctl.py evidence-check path/to/evidence.md --format text
python harnessctl.py check --format json
python harnessctl.py eval --format json
python harnessctl.py parity-check --against /path/to/template --format json
python harnessctl.py init --dry-run --format json
python harnessctl.py init --project-name my-service --format json
python harnessctl.py module init orders --paths src/orders/** --knowledge-maturity source-only --format json
python harnessctl.py module template-check orders --add-missing --format json
python harnessctl.py module lifecycle orders --to documented --format json
python harnessctl.py module lifecycle orders --to operational --format json
python harnessctl.py module lifecycle orders --to mature --format json
python harnessctl.py module lifecycle orders --to deprecated --reason "replaced by new module" --format json
```

也可以直接调用工具入口：

```bash
python lucyharness/tools/harnessctl.py validate --format json
```

如需从其他工作目录运行，可传入仓库根目录：

```bash
python harnessctl.py --root /path/to/repository health --format json
```

### 子命令

- `version`：输出当前模板版本。
- `validate`：校验 `lucyharness/harness/project.config.json`、`lucyharness/harness/modules.registry.json`、`lucyharness/harness/validation.rules.json`、`lucyharness/harness/evidence.schema.json` 的 JSON 语法、字段、枚举、重复模块、相对路径、模块引用文件、成熟模块 context-pack 和验证规则引用。
- `health`：在 `validate` 基础上检查模板结构、根 `harnessctl.py`、Claude Code Runtime Adapter 可发现性、settings JSON object、skills/agents/rules frontmatter、project/module rule paths、unsupported nested skill、legacy root runtime files、真实模板 placeholder、绝对路径样式、secret-like assignment 和 git 状态可用性。模板 placeholder 只产生 WARNING，不导致失败；普通说明文档里的元语法不会作为迁移占位符告警。
- `diff-classify`：根据 `lucyharness/harness/validation.rules.json` 的 `pathRules`/`riskRules` 计算最高验证等级，并输出 `changedAreas`、`affectedModules`、`matchedRules`、`reasons`、`referencesDriftTargets`。传入 `--files` 时不依赖 git；不传时在 git 仓库中读取 `git status --short`。
- `module-drift`：检查模块 registry 中的 `paths`、`contextPack`、`referenceFiles`、嵌套 `references` 是否存在；成熟模块必须声明 `contextPack`；并以保守规则从已注册模块路径的同级源码目录发现可能未注册的业务模块候选。
- `references-drift`：基于 `--files` 命中的 `pathRules.referencesDriftTargets` 和命中模块的 `contextPack`/`referenceFiles`/嵌套 `references` 输出 drift targets；也支持 `--module <name>` 显式选择模块；不执行外部命令。
- `checkpoint`：保存仓库内人类编写的 Markdown checkpoint（默认 `state/current-task.md`），并从受支持章节提取字段更新机器权威的 `state/task-state.json`；Markdown 不是 canonical state 自动生成的双向投影。命令拒绝绝对路径、Windows drive-relative、`..` 和 symlink 逃逸，检测 secret-like 内容后原子替换写入。
- `recover`：优先使用 canonical `state/task-state.json`；Markdown 仅在路径、字节数和 SHA-256 与 canonical checkpoint 一致时用于展示摘要。Markdown 缺失、未关联或被修改时仍以结构化状态继续并告警；结构化状态文件不存在时回退到旧 Markdown 解析，canonical state 损坏时要求人工介入。诊断始终基于 canonical 模块，并聚合当前 git status、`validate`、`health`、`module-drift`、`references-drift`；不会执行 `project.config.json` 中的命令。
- `evidence-check`：读取 Markdown Evidence，并根据 `lucyharness/harness/evidence.schema.json` 检查必需章节、验证等级、V2+ 验证命令或未验证原因、未验证项和剩余风险。
- `init`：安全初始化 Project Adapter。自动探测的技术栈、源码根、测试根和命令都进入 `initMetadata.inferred`，只有 CLI override 进入 `confirmed`；`.claude/` 和 harness runtime/kernel 目录不会被当作技术栈、source root 或模块候选。
- `module init`：创建完整模块知识包和 registry entry，支持 `--paths` 相对路径或 glob。命令先完成全部目标文件冲突和安全预检，再开始写入。
- `module template-check`：检查 registry 引用和模块知识包文件；`--add-missing` 补齐缺失模板和 registry 引用。
- `module lifecycle`：按知识成熟度门禁推进模块，禁止无理由 deprecated 和不合理回退；相同状态幂等。
- `check`：validate + health 的组合门禁（可选带 `--against` 顺带跑 parity-check）。这是 pre-commit hook 实际跑的命令，也是唯一会阻断提交的 gate。
- `eval`：运行 `lucyharness/tests/scenarios/scenario_*.py` 回归场景集，输出 scorecard（ok / total / passed / failed / score + 逐条状态），用于防止"改 A 坏 B"。空或缺失场景目录返回 `ok:true,total:0` + note，不视为错误。
- `parity-check`：把本仓库的 kernel 文件（`KERNEL_GLOBS`）与另一个根按逻辑路径、CRLF 归一比较，列出漂移文件，用于下游对齐模板内核。
- `backup-restore`：列出或回滚原子写操作留下的 `.bak` / `.bak.N` 备份；`--list` 列出，`--backup <rel>` 精确恢复指定代，`--all` 为每个目标只恢复数字代号最大的最新备份，避免 `.bak.10` 被按字符串顺序排在 `.bak.2` 前后造成错误结果。
- `task start`：对计划改动跑 diff-classify，把验证等级、受影响模块、references-drift 目标写入 `state/task-start.json`，并创建带唯一 `taskId`、显式 status/stage 的 `state/task-state.json`。V2+ 改动开工时调用。
- `task done`：读开工卡片 + 校验 evidence + 重算 references-drift + 对比实际改动，列出方法论缺口（`missing_evidence`、`evidence_check_failed`、`references_not_updated`、`concurrency_check_undeclared`、`scope_grew`、`missing_task_start`），并把 canonical task state 更新为 `completed/deliver` 或 `blocked/verify`。V2+ 缺 evidence 等阻断性缺口返回非零退出码（软门禁，不阻断提交）。

### Knowledge Maturity 生命周期

| 阶段 | 进入条件 |
|---|---|
| `discovered` | 只要求已注册并有 `module.json`。 |
| `source-only` | 要求 `module.json`、`context-pack.md`、`requirements.md`，且源码路径或 glob 至少命中一个目标。 |
| `documented` | 在 source-only 基础上要求 `current-design.md`、`open-questions.md`。 |
| `operational` | 在 documented 基础上要求 `implemented-status.md`、`verification.md`。 |
| `mature` | 在 operational 基础上要求 `state-machine.md`、`api-mapping.md`、`sql-design.md`。 |
| `deprecated` | 可从任意已注册状态进入，但必须提供非空 `--reason`。 |

模块 registry 可额外声明 `description`、`aliases`、`codeSymbols`、`riskGates`、`defaultValidationLevel` 和 `notes`，用于模块路由、代码符号定位和语义风险门提示；`riskTags` 仍专用于引用 `validation.rules.json` 中的 `riskRules`。完整路由规则见 `lucyharness/references/core/module-routing.md`，长任务上下文预算见 `lucyharness/references/core/context-budget.md`。

### 退出码

- `0`：命令成功，且未发现 ERROR。
- `1`：命令执行完成但发现 ERROR，例如配置校验失败、Evidence 不充分、非 git 目录未给 `diff-classify --files`。
- `2`：CLI 参数错误（由 `argparse` 返回）。

## 基本约束

- Core 中禁止出现项目名、业务名、绝对路径、表名和固定构建命令。
- 项目事实只放 Project Adapter。
- 业务事实只放 Module Adapter。
- Runtime Adapter 只承载 Claude Code 发现入口，事实内容引用根 `lucyharness/references/`。
- 脚本优先读取配置，不写死项目路径和模块名称。
- 同一事实只保留一个权威来源。
- 未确认的产品规则必须进入 `open-questions.md`，不能直接固化为实现规则。