@cyning/harness 0.3.0

package/harness/templates/TASK_graph_bootstrap.md

@@ -0,0 +1,113 @@
+# Task：图谱 Bootstrap · 模块表人签（D4-a）
+
+> **状态**：`draft` / `in_progress` / `done`  
+> **类型**：存量 **首次** 接入 / 新仓图谱初始化  
+> **关联**：[`docs/_tech_graph/01_struct.md`](../../graph/templates/01_struct.md) · ONBOARDING 档位 S0～S3
+
+---
+
+## Harness 元信息
+
+| 字段 | 值 |
+|------|-----|
+| **task_slug** | `graph-bootstrap` |
+| **test_strategy** | `recommended` |
+| **test_strategy_note** | 文档 + 文件存在性；无业务单测 |
+| **code_quality_bar** | `not_applicable` |
+| **orchestration** | 单 task 或 Epic 首棒 |
+| **git_branch** | `task/graph-bootstrap` |
+| **experience_capture** | `recommended` |
+
+### 人工闸（本 task 核心）
+
+| human_gate_id | status | blocks_hats | 说明 |
+|---------------|--------|-------------|------|
+| **HG-GRAPH-MODULES** | pending → **approved** | **30** | `01_struct` **一级模块表** 人签；**非**「全部 flow 画完」 |
+| HG-TASK-DRAFT | pending | 22-R1 | 可选 · 小 task 可合并 |
+| HG-AUDIT-R1 | pending | 30 | 22 R1 后允许改码 task 派发 |
+
+> **D4-a**：「全量」= **模块登记表覆盖一级模块**；flow 按后续 task **增量**。
+
+---
+
+## 背景与目标
+
+**完成态**：
+
+- [ ] `docs/_tech_graph/` 骨架就位（`00_main` 双轨、`99_mermaid_protocol`、`02_version` 可选）
+- [ ] `01_struct.md` 模块表填完 **一级模块**（module_id · glob · 依赖方向）
+- [ ] **至少 1** 条主 flow（新仓 / **S0**）；S2+ 可在 `00_main` 列「待补 flow 清单」
+- [ ] **`HG-GRAPH-MODULES` approved** — 维护者签核后，**30 执行改码** task 方可开工
+- [ ] 本 task 关账 invoke + `### 自检结论` 回填
+
+**不做**：
+
+- 首次 onboarding **全仓 flow 一次画完**
+- 全仓代码扫描自动生图
+
+---
+
+## 范围
+
+- [ ] 从 `cyning-harness/graph/templates/` 复制骨架至 `docs/_tech_graph/`
+- [ ] 填写 `01_struct.md` 模块表（删除模板示例行）
+- [ ] 新仓/S0：完成 `10_flow_MAIN` 或等价主路径（替换占位锚点）
+- [ ] 在 `01_struct.md` 或本 task 记录 **人签表**（签核人 · 日期）
+
+## 非范围
+
+- 业务功能代码改动（除非同 Epic 明示）
+- L0-e `graph.json` 全量 export（随 `.ai.md` 增量即可）
+
+---
+
+## 失败路径
+
+| 触发条件 | 系统行为 | 可重试 | 用户可见 |
+|----------|----------|--------|----------|
+| `HG-GRAPH-MODULES` pending 即开 30 改码 task | 执行 **拒开工** | 是 | 须先完成本 bootstrap + 人签 |
+| 模块表空表或仅模板示例行 | 22 **打回** | 是 | 一级模块未覆盖 |
+| 试图一次画完所有 flow | 审查 **打回** | 是 | 违反 D4-a |
+
+---
+
+## 验收标准
+
+- [ ] `docs/_tech_graph/00_main.md` + `.ai.md` 存在且语义一致
+- [ ] `01_struct.md` ≥3 行真实模块（按仓规模；通常 3～12）
+- [ ] `HG-GRAPH-MODULES` → **approved**（本 task 或 `01_struct` 人签表）
+- [ ] 新仓/S0：≥1 主 flow；S2：模块表 + 待补清单即可
+- [ ] invoke 落盘 `docs/harness/invokes/by-task/<task_slug>/`
+
+---
+
+## 给执行帽的必读列表
+
+1. [`docs/ONBOARDING.md`](../../docs/ONBOARDING.md) §3 存量档位
+2. `docs/_tech_graph/01_struct.md` · `99_mermaid_protocol.md`
+3. 本 task 验收表
+
+---
+
+## 实现备忘
+
+| 项 | 状态 | 备注 |
+|----|------|------|
+| 骨架复制 | ⏳ | |
+| 模块表 | ⏳ | |
+| HG-GRAPH-MODULES | ⏳ | pending → approved |
+| 主 flow | ⏳ | 按档位 |
+
+---
+
+### 自检结论（执行者）
+
+（30/40 回填）
+
+---
+
+## 修订记录
+
+| 日期 | 说明 |
+|------|------|
+| YYYY-MM-DD | 从 cyning-harness `TASK_graph_bootstrap.md` 嵌入 |

package/harness/templates/VIEW_done_by_domain.md

@@ -0,0 +1,66 @@
+# Tasks 视图：已完成 · 按域分组（done_by_domain）
+
+> **说明**：聚合索引 · **非真值**。真值：`done/` 各 task 文件 + [`../done/README.md`](../done/README.md) Hub。  
+> **维护**：关账时在对应域表追加一行；Epic 母单单独一节。
+
+---
+
+## harness
+
+| 关账日 | 链接 | 一行摘要 |
+|--------|------|----------|
+| YYYY-MM-DD | [`../done/harness/task_<slug>_v1.md`](../done/harness/task_<slug>_v1.md) | … |
+
+---
+
+## cyning-harness
+
+| 关账日 | 链接 | 一行摘要 |
+|--------|------|----------|
+| YYYY-MM-DD | [`../done/cyning-harness/task_<slug>_v1.md`](../done/cyning-harness/task_<slug>_v1.md) | … |
+
+---
+
+## engineering
+
+| 关账日 | 链接 | 一行摘要 |
+|--------|------|----------|
+| YYYY-MM-DD | [`../done/engineering/task_<slug>_v1.md`](../done/engineering/task_<slug>_v1.md) | … |
+
+---
+
+## governance
+
+| 关账日 | 链接 | 一行摘要 |
+|--------|------|----------|
+| YYYY-MM-DD | [`../done/governance/task_<slug>_v1.md`](../done/governance/task_<slug>_v1.md) | … |
+
+---
+
+## chatbi
+
+| 关账日 | 链接 | 一行摘要 |
+|--------|------|----------|
+| YYYY-MM-DD | [`../done/chatbi/task_<slug>_v1.md`](../done/chatbi/task_<slug>_v1.md) | … |
+
+---
+
+## standards
+
+| 关账日 | 链接 | 一行摘要 |
+|--------|------|----------|
+| YYYY-MM-DD | [`../done/standards/task_<slug>_v1.md`](../done/standards/task_<slug>_v1.md) | … |
+
+---
+
+## epics（母单 · MANIFEST）
+
+| 关账日 | 链接 | 子单 |
+|--------|------|------|
+| YYYY-MM-DD | [`../done/epics/epic_<slug>.md`](../done/epics/epic_<slug>.md) | 见母单 §编排 |
+
+---
+
+## 给 Cursor
+
+`done_by_domain`、`_views`、域分组、Epic、Hub

package/harness/templates/VIEW_done_thin_pointer.md

@@ -0,0 +1,16 @@
+# Tasks 状态视图：已完成（done）
+
+> **薄指针**：完整导航见 **[`../done/README.md`](../done/README.md)**（按域 Hub）。  
+> **分组表**：[`done_by_domain.md`](./done_by_domain.md）。
+
+---
+
+## 快速入口
+
+| 视图 | 路径 |
+|------|------|
+| **Hub（首选）** | [`../done/README.md`](../done/README.md) |
+| 按域分组 | [`done_by_domain.md`](./done_by_domain.md) |
+| 进行中 | [`in_progress.md`](./in_progress.md) |
+
+**维护纪律**：关账时更新 Hub / `done_by_domain`；**勿**在本文件追加长列表。

package/ide/adapters/AGENTS.md.fragment.example

@@ -0,0 +1,31 @@
+# Harness Starter（业务仓 · 通用 Agent）
+
+> **单源真值**：`docs/coding_wiki/` 读序 + `docs/standards/` + 本文件其余业务约定。  
+> **本片段**：摘要 + **POINTER**；Harness 条文真值在 `docs/harness/prompts/`。
+
+## 执行 task 前
+
+1. Open Folder = **本仓根**
+2. 读 `docs/tasks/active/task_*.md`：`test_strategy` · `failure_paths` · **人工闸**表
+3. **30 改码前** GATE_VERIFY（真值在 task **人工闸表**，**非**聊天 / invoke 字面 `approved`）：
+   - 首输出闸扫描表 · 见 `docs/harness/prompts/FRAGMENT_30_gate_verify_v1_zh.md`
+   - **`HG-AUDIT-R1` pending** → **30 拒改码**（须维护者签 task 表 `approved`）
+   - **`HG-GRAPH-MODULES` pending** → **30 拒改码**（D4-a）
+   - 用户声称与 task 表冲突 → **STOP** · 以 task 表为准
+4. 过程 invoke：`docs/harness/invokes/by-task/<task_slug>/`
+
+## Verify（合并前）
+
+| 栈 | 命令（与 `.github/workflows/` 一致） |
+|----|--------------------------------------|
+| 前端 | `pnpm lint` → `pnpm test` → `pnpm build` |
+| 后端 | `pytest tests`（按仓 marker 裁剪） |
+| iOS | `xcodebuild`（见 task `test_strategy_note`） |
+
+## 关键词
+
+`Harness`、`task`、`invoke`、`HG-AUDIT-R1`、`HG-GRAPH-MODULES`、`human_gate`、`拒开工`
+
+## 完整库 POINTER
+
+工作区：`docs/harness/prompts/`（22/30/TEMPLATE_30_gate_stop 等）

package/ide/adapters/CLAUDE.md.fragment.example

@@ -0,0 +1,30 @@
+# Harness Starter（业务仓 · Claude Code）
+
+> **单源真值**：`docs/coding_wiki/` 读序 + `docs/standards/` + `AGENTS.md`。  
+> **本片段**：摘要 + **POINTER**；条文真值在 `docs/harness/prompts/`。
+
+## 执行 task 前
+
+1. Open Folder = **本仓根**
+2. 读 `docs/tasks/active/task_*.md`：`test_strategy` · `failure_paths` · **人工闸**表
+3. **30 改码前** GATE_VERIFY（真值在 task **人工闸表**，**非** invoke 字面 `approved`）：
+   - 首输出闸扫描 · `FRAGMENT_30_gate_verify_v1_zh.md`
+   - **`HG-AUDIT-R1` pending** → **30 拒改码**
+   - 声称与 task 表冲突 → **STOP**
+4. 过程 invoke：`docs/harness/invokes/by-task/<task_slug>/`
+
+## Verify（合并前）
+
+| 栈 | 命令（与 `.github/workflows/` 一致） |
+|----|--------------------------------------|
+| 前端 | `pnpm lint` → `pnpm test` → `pnpm build` |
+| 后端 | `pytest tests`（按仓 marker 裁剪） |
+| iOS | `xcodebuild`（见 task `test_strategy_note`） |
+
+## 关键词
+
+`Harness`、`task`、`invoke`、`HG-AUDIT-R1`、`HG-GRAPH-MODULES`、`human_gate`、`拒开工`
+
+## 完整库 POINTER
+
+工作区：`docs/harness/prompts/`（22/30/TEMPLATE_30_gate_stop 等）

package/ide/adapters/README.md

@@ -0,0 +1,46 @@
+# ide/adapters
+
+**单源 POINTER**：真值在 `docs/coding_wiki/` + `docs/standards/` + `AGENTS.md`；本目录仅 **IDE 入口片段**。
+
+## v0.2 已交付（D3 · M2 补完）
+
+| 文件 | 状态 | 勾选 IDE | 嵌入路径 |
+|------|------|----------|----------|
+| [`cursor-harness-starter.mdc.example`](./cursor-harness-starter.mdc.example) | ✅ | **Cursor**（默认推荐） | `.cursor/rules/05-harness-starter.mdc` |
+| [`CLAUDE.md.fragment.example`](./CLAUDE.md.fragment.example) | ✅ | **Claude Code** | 仓根 `CLAUDE.md`（marker merge） |
+| [`AGENTS.md.fragment.example`](./AGENTS.md.fragment.example) | ✅ | **通用 Agent** | 仓根 `AGENTS.md`（marker merge） |
+
+## 安装勾选
+
+```bash
+# 三类 IDE 一次勾选（dry-run 预览）
+/path/to/cyning-harness/wizard/install.sh \
+  --preset harness-only \
+  --ide cursor,claude,agents \
+  --dry-run --target /path/to/project
+
+# 实装
+/path/to/cyning-harness/wizard/install.sh \
+  --preset harness-only --ide cursor,claude,agents
+```
+
+profile 字段：`tracks.ide_cursor` · `tracks.ide_claude` · `tracks.ide_agents`（缺省：cursor=true，其余 false）。
+
+## marker merge 纪律（D3）
+
+- 块标记：`<!-- cyning-harness:begin -->` … `<!-- cyning-harness:end -->`
+- **不覆盖**用户仓已有 `CLAUDE.md` / `AGENTS.md` 全文；块外手写保持不变
+- 由 [`wizard/install.sh`](../install.sh) + [`harness-sync.sh`](../harness-sync.sh) 执行
+
+## 手工嵌入（备查）
+
+```bash
+mkdir -p .cursor/rules
+cp cyning-harness/ide/adapters/cursor-harness-starter.mdc.example .cursor/rules/05-harness-starter.mdc
+```
+
+## 纪律（D3）
+
+- **多入口仅 POINTER** — 不在各 IDE 文件重复 L1/L2 全文
+- 过程轨（task、invoke、CI）**与 IDE 无关**
+- 向导 **默认不全选** IDE；按实际编辑器勾选

package/ide/adapters/cursor-harness-starter.mdc.example

@@ -0,0 +1,37 @@
+---
+description: Harness Starter — 读序、task、人工闸与 Verify 纪律（嵌入业务仓 · Cursor）
+alwaysApply: true
+globs:
+  - "**/*"
+---
+
+# Harness Starter（业务仓 · Cursor）
+
+> **单源真值**：`docs/coding_wiki/` 读序 + `docs/standards/` + `AGENTS.md`。  
+> **本规则**：摘要 + **POINTER**；条文真值在 `docs/harness/prompts/`。
+
+## 执行 task 前
+
+1. Open Folder = **本仓根**
+2. 读 `docs/tasks/active/task_*.md`：`test_strategy` · `failure_paths` · **人工闸**表
+3. **30 改码前** GATE_VERIFY（真值在 task **人工闸表**，**非** invoke 字面 `approved`）：
+   - 首输出闸扫描 · `FRAGMENT_30_gate_verify_v1_zh.md`
+   - **`HG-AUDIT-R1` pending** → **30 拒改码**
+   - 声称与 task 表冲突 → **STOP**
+4. 过程 invoke：`docs/harness/invokes/by-task/<task_slug>/`
+
+## Verify（合并前）
+
+| 栈 | 命令（与 `.github/workflows/` 一致） |
+|----|--------------------------------------|
+| 前端 | `pnpm lint` → `pnpm test` → `pnpm build` |
+| 后端 | `pytest tests`（按仓 marker 裁剪） |
+| iOS | `xcodebuild`（见 task `test_strategy_note`） |
+
+## 关键词
+
+`Harness`、`task`、`invoke`、`HG-AUDIT-R1`、`HG-GRAPH-MODULES`、`human_gate`、`拒开工`
+
+## 完整库 POINTER
+
+工作区：`docs/harness/prompts/`（22/30/TEMPLATE_30_gate_stop 等）

package/lib/cli.js

@@ -0,0 +1,180 @@
+import { readManifest, isNewerVersion } from './manifest.js';
+import {
+  resolveHarnessRoot,
+  resolvePackageVersion,
+  resolveTarget,
+  wizardScript,
+} from './paths.js';
+import { runBash } from './run.js';
+
+function usage() {
+  console.log(`@cyning/harness · cyning-harness CLI (v0.3+)
+
+用法:
+  npx @cyning/harness init [--preset NAME] [--ide LIST] [--target PATH] [--yes]
+  npx @cyning/harness upgrade [--target PATH] [--ide LIST] [--yes] [--force] [--gate-check]
+  npx @cyning/harness check [--target PATH]
+
+说明:
+  init     首次接入 · 内部调用 wizard/install.sh + harness-sync.sh apply
+  upgrade  升级已接入仓 · 等价 wizard/upgrade.sh --yes
+  check    读 manifest.json · 对比当前包版本是否有可升级版本
+
+环境:
+  CYNING_HARNESS   覆盖产品包根（维护者本地 clone 开发）
+  HARNESS_VERSION  覆盖写入 manifest 的版本号
+`);
+}
+
+function takeOption(args, name) {
+  const idx = args.indexOf(name);
+  if (idx === -1 || idx + 1 >= args.length) {
+    return { value: undefined, rest: args };
+  }
+  const value = args[idx + 1];
+  const rest = args.slice(0, idx).concat(args.slice(idx + 2));
+  return { value, rest };
+}
+
+export async function runCli(argv) {
+  const harnessRoot = resolveHarnessRoot();
+  const pkgVersion = resolvePackageVersion(harnessRoot);
+
+  if (argv.length === 0 || argv.includes('-h') || argv.includes('--help')) {
+    usage();
+    return;
+  }
+
+  const [cmd, ...rest] = argv;
+
+  if (cmd === 'init') {
+    await cmdInit(rest, harnessRoot, pkgVersion);
+    return;
+  }
+  if (cmd === 'upgrade') {
+    await cmdUpgrade(rest, harnessRoot, pkgVersion);
+    return;
+  }
+  if (cmd === 'check') {
+    await cmdCheck(rest, harnessRoot, pkgVersion);
+    return;
+  }
+
+  const err = new Error(`未知命令: ${cmd}\n`);
+  err.exitCode = 1;
+  throw err;
+}
+
+async function cmdInit(args, harnessRoot, pkgVersion) {
+  const yes = args.includes('--yes');
+  let rest = args.filter((a) => a !== '--yes');
+  const { value: preset, rest: r1 } = takeOption(rest, '--preset');
+  rest = r1;
+  const { value: ide, rest: r2 } = takeOption(rest, '--ide');
+  rest = r2;
+  const { value: targetArg, rest: r3 } = takeOption(rest, '--target');
+  rest = r3;
+
+  if (rest.length > 0) {
+    const err = new Error(`init 未知参数: ${rest.join(' ')}`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const target = resolveTarget(process.cwd(), targetArg);
+  const installSh = wizardScript(harnessRoot, 'install.sh');
+  const installArgs = ['--target', target];
+  if (preset) installArgs.push('--preset', preset);
+  if (ide) installArgs.push('--ide', ide);
+
+  runBash(installSh, installArgs, {
+    env: {
+      CYNING_HARNESS: harnessRoot,
+      HARNESS_VERSION: pkgVersion,
+    },
+    inherit: true,
+  });
+
+  console.log(`manifest: ${target}/.cyning-harness/manifest.json`);
+  if (!yes) {
+    console.log('init 完成。');
+  }
+}
+
+async function cmdUpgrade(args, harnessRoot, pkgVersion) {
+  const checkOnly = args.includes('--check');
+  const force = args.includes('--force');
+  const gateCheck = args.includes('--gate-check');
+  const yes = args.includes('--yes') || !checkOnly;
+  let rest = args.filter(
+    (a) => !['--check', '--force', '--gate-check', '--yes'].includes(a),
+  );
+  const { value: ide, rest: r1 } = takeOption(rest, '--ide');
+  rest = r1;
+  const { value: targetArg, rest: r2 } = takeOption(rest, '--target');
+  rest = r2;
+
+  if (rest.length > 0) {
+    const err = new Error(`upgrade 未知参数: ${rest.join(' ')}`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const target = resolveTarget(process.cwd(), targetArg);
+
+  if (checkOnly) {
+    await cmdCheck(['--target', target], harnessRoot, pkgVersion);
+    return;
+  }
+
+  const upgradeSh = wizardScript(harnessRoot, 'upgrade.sh');
+  const upgradeArgs = ['--target', target];
+  if (ide) upgradeArgs.push('--ide', ide);
+  if (yes) upgradeArgs.push('--yes');
+  if (force) upgradeArgs.push('--force');
+  if (gateCheck) upgradeArgs.push('--gate-check');
+
+  runBash(upgradeSh, upgradeArgs, {
+    env: {
+      CYNING_HARNESS: harnessRoot,
+      HARNESS_VERSION: pkgVersion,
+      ...(force ? { HARNESS_SYNC_FORCE: '1' } : {}),
+    },
+    inherit: true,
+  });
+}
+
+async function cmdCheck(args, harnessRoot, pkgVersion) {
+  let rest = args;
+  const { value: targetArg, rest: r1 } = takeOption(rest, '--target');
+  rest = r1;
+
+  if (rest.length > 0) {
+    const err = new Error(`check 未知参数: ${rest.join(' ')}`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const target = resolveTarget(process.cwd(), targetArg);
+  const manifest = readManifest(target);
+
+  console.log(`目标: ${target}`);
+  console.log(`包版本: ${pkgVersion}`);
+
+  if (!manifest) {
+    console.log('状态: 未接入（无 .cyning-harness/manifest.json）');
+    console.log('建议: npx @cyning/harness init --preset harness-only --ide cursor,agents');
+    return;
+  }
+
+  console.log(`manifest.version: ${manifest.version}`);
+  console.log(`manifest.preset: ${manifest.preset}`);
+  console.log(`manifest.ide: ${(manifest.ide || []).join(',')}`);
+
+  if (isNewerVersion(manifest.version, pkgVersion)) {
+    console.log('状态: 可升级');
+    console.log(`建议: npx @cyning/harness upgrade --target ${target}`);
+  } else {
+    console.log('状态: 已是最新（或版本不可 semver 比较且相同）');
+  }
+}

package/lib/manifest.js

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function manifestPath(targetRoot) {
+  return path.join(targetRoot, '.cyning-harness', 'manifest.json');
+}
+
+export function readManifest(targetRoot) {
+  const file = manifestPath(targetRoot);
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+/** 比较 semver 前缀；非 semver 时做字符串相等判断 */
+export function normalizeVersion(version) {
+  if (!version || version === 'unknown') return version;
+  const m = String(version).match(/^v?(\d+\.\d+\.\d+)/);
+  return m ? m[1] : String(version);
+}
+
+export function isNewerVersion(current, latest) {
+  const a = normalizeVersion(current);
+  const b = normalizeVersion(latest);
+  if (!a || !b || a === 'unknown' || b === 'unknown') {
+    return current !== latest;
+  }
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (db > da) return true;
+    if (db < da) return false;
+  }
+  return false;
+}

package/lib/paths.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** npm 包根 = cyning-harness 产品包根 */
+export function resolveHarnessRoot() {
+  if (process.env.CYNING_HARNESS) {
+    return path.resolve(process.env.CYNING_HARNESS);
+  }
+  return path.resolve(__dirname, '..');
+}
+
+export function resolvePackageVersion(harnessRoot) {
+  if (process.env.HARNESS_VERSION) {
+    return process.env.HARNESS_VERSION;
+  }
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(harnessRoot, 'package.json'), 'utf8'),
+    );
+    if (pkg.version) return pkg.version;
+  } catch {
+    // fall through
+  }
+  return 'unknown';
+}
+
+export function resolveTarget(cwd, targetArg) {
+  return path.resolve(targetArg || cwd);
+}
+
+export function wizardScript(harnessRoot, name) {
+  return path.join(harnessRoot, 'wizard', name);
+}

package/lib/run.js

@@ -0,0 +1,33 @@
+import { spawnSync } from 'node:child_process';
+
+/**
+ * 调用 wizard shell；保持 S2 写路径唯一真值在 harness-sync.sh
+ */
+export function runBash(scriptPath, args, options = {}) {
+  const { cwd, env = {}, inherit = false } = options;
+  const result = spawnSync('bash', [scriptPath, ...args], {
+    cwd,
+    env: { ...process.env, ...env },
+    encoding: 'utf8',
+    stdio: inherit ? 'inherit' : 'pipe',
+  });
+
+  if (result.error) {
+    const err = new Error(result.error.message);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  if (result.status !== 0) {
+    const err = new Error(
+      (result.stderr || result.stdout || `命令失败: bash ${scriptPath}`).trim(),
+    );
+    err.exitCode = result.status ?? 1;
+    throw err;
+  }
+
+  return {
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+  };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@cyning/harness",
+  "version": "0.3.0",
+  "description": "cyning-harness discipline package · init / upgrade / check CLI",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "harness": "bin/harness.js",
+    "cyning-harness": "bin/harness.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "schema/",
+    "wizard/",
+    "harness/",
+    "graph/",
+    "coding_wiki/",
+    "standards/",
+    "ci/",
+    "ide/",
+    "golden/",
+    "examples/",
+    "!examples/demo_checkout/_sandbox",
+    "!examples/demo_checkout/_sandbox/**",
+    "docs/",
+    "README.md",
+    "CHANGELOG.md",
+    "AGENTS.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}