easy-coding-harness 0.5.1 → 0.5.2-beta.0

package/CHANGELOG.md

@@ -6,11 +6,12 @@
 - `y`：常规功能升级
 - `z`：日常 bug 修复
 
-## 0.5.1
+## 0.5.2-beta.0
 
-- 修复 Claude Code hook 命令使用相对路径导致在子目录 cwd 下找不到 `.claude/hooks/*.py` 的问题；Claude、Codex、Qoder 的 hook 配置现在安装时渲染为带引号的绝对脚本路径。
-- `easy-coding upgrade` 可直接刷新存量 0.5.0 项目的 hook 配置并解决该问题；升级后 `ec-init` 合规扫描会校验 hook 配置是否已使用当前版本要求的绝对路径。
-- `easy-coding clear` 和 `install-manifest.json` 兼容新绝对 hook 命令，清理时仍按项目相对 hook 路径识别托管注册项。
+- 修复 Claude Code hook 命令使用直接相对路径导致在子目录 cwd 下找不到 `.claude/hooks/*.py` 的问题；Claude、Codex、Qoder 的 hook 配置现在使用可共享的 portable relative launcher，并绑定 `.easy-coding/config.yaml` 的 `project.id`，避免把本机仓库绝对路径写入可提交配置，同时防止 supermodule 父仓 hook 被子仓 cwd 错路由。
+- `easy-coding upgrade` 可直接刷新存量 0.5.0 项目和已安装 0.5.1 beta 绝对路径配置；同版本也会修复缺失、重复、事件错位或 stale 的托管 hook 注册。
+- `easy-coding clear` 和 `install-manifest.json` 兼容 portable launcher、旧直接相对命令和旧绝对 hook 命令，清理时仍按项目相对 hook 路径识别托管注册项。
+- npm `0.5.1` 已发布不可覆盖，本版本作为 beta 修复包发布，用于替代原 `0.5.1` beta。
 
 ## 0.5.0
 

package/dist/cli.js

@@ -61,6 +61,7 @@ function colorizeBanner(art) {
 }
 
 // src/utils/config-yaml.ts
+import { randomUUID } from "crypto";
 import { readFile as readFile2 } from "fs/promises";
 import YAML, { isScalar, isSeq, parseDocument } from "yaml";
 
@@ -108,6 +109,7 @@ function createDefaultConfig(params) {
     harness_version: params.harnessVersion,
     agents: params.agents,
     project: {
+      id: params.projectId ?? createProjectId(),
       name: params.projectName
     },
     memory: {
@@ -138,6 +140,14 @@ async function readConfigYaml(filePath) {
   const content = await readFile2(filePath, "utf8");
   return YAML.parse(content);
 }
+async function readProjectIdIfExists(filePath) {
+  try {
+    const config = await readConfigYaml(filePath);
+    return typeof config.project?.id === "string" && config.project.id.trim() ? config.project.id : null;
+  } catch {
+    return null;
+  }
+}
 async function updateConfigYaml(filePath, updater) {
   const content = await readFile2(filePath, "utf8");
   const document = parseDocument(content);
@@ -160,11 +170,27 @@ async function updateHarnessVersion(filePath, version) {
     config.harness_version = version;
   });
 }
+async function ensureProjectId(filePath) {
+  let projectId = "";
+  await updateConfigYaml(filePath, (config) => {
+    if (!config.project || typeof config.project !== "object") {
+      config.project = { id: createProjectId(), name: "" };
+    }
+    if (typeof config.project.id !== "string" || !config.project.id.trim()) {
+      config.project.id = createProjectId();
+    }
+    projectId = config.project.id;
+  });
+  return projectId;
+}
 async function updateSupermoduleConfig(filePath, supermodule) {
   return updateConfigYaml(filePath, (config) => {
     config.supermodule = supermodule;
   });
 }
+function createProjectId() {
+  return `ec-${randomUUID()}`;
+}
 
 // src/utils/gitignore.ts
 import path3 from "path";
@@ -568,17 +594,21 @@ async function writeRuntimeScaffold(cwd, agents, opts = {}) {
   const easyCodingDir = path6.join(cwd, EASY_CODING_DIR);
   await ensureDir(easyCodingDir);
   const configPath2 = path6.join(easyCodingDir, CONFIG_FILE);
+  let projectId = opts.projectId ?? createProjectId();
   if (!await pathExists(configPath2)) {
     const projectName = path6.basename(cwd);
     await writeConfigYaml(
       configPath2,
       createDefaultConfig({
         projectName,
+        projectId,
         harnessVersion: VERSION,
         agents,
         supermodule: opts.supermodule
       })
     );
+  } else {
+    projectId = await ensureProjectId(configPath2);
   }
   await ensureDir(path6.join(easyCodingDir, "tasks"));
   await ensureDir(path6.join(easyCodingDir, SESSIONS_DIR));
@@ -586,6 +616,7 @@ async function writeRuntimeScaffold(cwd, agents, opts = {}) {
   await ensureDir(path6.join(easyCodingDir, SPEC_DIR, DEV_SPEC_DIR));
   await writeMemoryScaffold(easyCodingDir);
   await writeTemplatesScaffold(easyCodingDir);
+  return projectId;
 }
 async function writeTemplatesScaffold(easyCodingDir) {
   const templatesDir = path6.join(easyCodingDir, TEMPLATES_DIR);
@@ -762,17 +793,28 @@ function resolvePlaceholders(content, ctx, contentName = "template") {
   }
   return resolved;
 }
-function withInstallPaths(cwd, ctx) {
-  const hooksDir = toPosixPath(path8.resolve(cwd, ctx.platform_config_dir, "hooks"));
+async function withProjectInstallPaths(cwd, ctx, projectId) {
+  const resolvedProjectId = projectId ?? await readProjectIdIfExists(path8.join(cwd, EASY_CODING_DIR, CONFIG_FILE));
+  return withInstallPaths(cwd, ctx, resolvedProjectId ?? void 0);
+}
+function withInstallPaths(cwd, ctx, projectId) {
   return {
     ...ctx,
-    platform_hooks_dir_abs: hooksDir,
-    platform_hooks_dir_shell: jsonStringContent(shellDoubleQuoteArg(hooksDir))
+    platform_hook_session_start_command: jsonStringContent(
+      renderHookCommand(cwd, ctx, "session-start.py", process.platform, projectId)
+    ),
+    platform_hook_inject_workflow_state_command: jsonStringContent(
+      renderHookCommand(cwd, ctx, "inject-workflow-state.py", process.platform, projectId)
+    ),
+    platform_hook_inject_subagent_context_command: jsonStringContent(
+      renderHookCommand(cwd, ctx, "inject-subagent-context.py", process.platform, projectId)
+    )
   };
 }
-function renderHookCommand(cwd, ctx, scriptName, platform = process.platform) {
-  const hooksDir = toPosixPath(path8.resolve(cwd, ctx.platform_config_dir, "hooks"));
-  return `${ctx.python_cmd} ${shellDoubleQuoteArg(hooksDir, platform)}/${scriptName}`;
+function renderHookCommand(_cwd, ctx, scriptName, platform = process.platform, projectId) {
+  const launcher = `import base64;exec(base64.b64decode('${Buffer.from(HOOK_LAUNCHER_PYTHON).toString("base64")}').decode())`;
+  const rootIdArg = projectId ? ` ${shellDoubleQuoteArg(projectId, platform)}` : "";
+  return `${ctx.python_cmd} -c ${shellDoubleQuoteArg(launcher, platform)}${rootIdArg} ${ctx.platform_config_dir}/hooks/${scriptName}`;
 }
 function shellDoubleQuoteArg(value, platform = process.platform) {
   if (platform === "win32") {
@@ -783,12 +825,57 @@ function shellDoubleQuoteArg(value, platform = process.platform) {
   }
   return `"${value.replace(/(["\\$`])/g, "\\$1")}"`;
 }
-function toPosixPath(filePath) {
-  return filePath.split(path8.sep).join("/");
-}
 function jsonStringContent(value) {
   return JSON.stringify(value).slice(1, -1);
 }
+var HOOK_LAUNCHER_PYTHON = [
+  "import io,json,os,re,runpy,sys",
+  "from pathlib import Path",
+  "payload=sys.stdin.read()",
+  "try:",
+  "    data=json.loads(payload or '{}')",
+  "except Exception:",
+  "    data={}",
+  "expected_id=sys.argv[1] if len(sys.argv) > 2 else None",
+  "script_arg=sys.argv[2] if len(sys.argv) > 2 else (sys.argv[1] if len(sys.argv) > 1 else None)",
+  "def project_id(root):",
+  "    try:",
+  "        lines=(root / '.easy-coding' / 'config.yaml').read_text(encoding='utf-8').splitlines()",
+  "    except Exception:",
+  "        return None",
+  "    in_project=False",
+  "    for line in lines:",
+  "        if not in_project:",
+  "            if re.match(r'^project\\s*:\\s*(?:#.*)?$', line):",
+  "                in_project=True",
+  "            continue",
+  "        if not line.strip() or line.lstrip().startswith('#'):",
+  "            continue",
+  "        if not line.startswith((' ', '\\t')):",
+  "            return None",
+  `        match=re.match(r"\\s+id\\s*:\\s*['\\"]?([^'\\"#\\s]+)", line)`,
+  "        if match:",
+  "            return match.group(1)",
+  "    return None",
+  "def roots_from(raw):",
+  "    if not raw:",
+  "        return []",
+  "    start=Path(raw).resolve()",
+  "    return [candidate for candidate in (start, *start.parents) if (candidate / '.easy-coding').is_dir()]",
+  "sources=[os.environ.get('CLAUDE_PROJECT_DIR'), os.environ.get('QODER_PROJECT_DIR'), data.get('cwd'), os.getcwd()]",
+  "root=None",
+  "if expected_id:",
+  "    root=next((candidate for raw in sources for candidate in roots_from(raw) if project_id(candidate) == expected_id), None)",
+  "else:",
+  "    root=next((candidate for raw in sources for candidate in roots_from(raw)), None)",
+  "target=(root / script_arg) if root and script_arg else None",
+  "if target and target.is_file():",
+  "    os.chdir(root)",
+  "    data['cwd']=str(root)",
+  "    sys.stdin=io.StringIO(json.dumps(data))",
+  "    sys.path.insert(0, str(target.parent))",
+  "    runpy.run_path(str(target), run_name='__main__')"
+].join("\n");
 async function resolveSkills(ctx) {
   const skillsRoot = getTemplatePath("common", "skills");
   const entries = await readdir2(skillsRoot);
@@ -944,7 +1031,7 @@ function stripTemplateExtension(fileName) {
 async function configureClaude(cwd, opts = {}) {
   const platform = "claude-code";
   const meta = PLATFORM_META[platform];
-  const ctx = withInstallPaths(cwd, meta.templateContext);
+  const ctx = await withProjectInstallPaths(cwd, meta.templateContext, opts.projectId);
   const dest = path9.join(cwd, ".claude");
   const hookConfigPath = path9.join(cwd, meta.hookConfigFile);
   const artifacts = [];
@@ -982,7 +1069,7 @@ import path10 from "path";
 async function configureCodex(cwd, opts = {}) {
   const platform = "codex";
   const meta = PLATFORM_META[platform];
-  const ctx = withInstallPaths(cwd, meta.templateContext);
+  const ctx = await withProjectInstallPaths(cwd, meta.templateContext, opts.projectId);
   const hookConfigPath = path10.join(cwd, meta.hookConfigFile);
   const artifacts = [];
   artifacts.push(
@@ -1098,7 +1185,7 @@ async function existingManagedSkillArtifacts(skillsDir, skillNames, platform) {
 async function configureQoder(cwd, opts = {}) {
   const platform = "qoder";
   const meta = resolvePlatformMeta(cwd, platform);
-  const ctx = withInstallPaths(cwd, meta.templateContext);
+  const ctx = await withProjectInstallPaths(cwd, meta.templateContext, opts.projectId);
   const dest = path12.join(cwd, ctx.platform_config_dir);
   const hookConfigPath = path12.join(cwd, meta.hookConfigFile);
   const artifacts = [];
@@ -1149,17 +1236,22 @@ var CONFIGURATORS = {
 };
 
 // src/commands/install-harness.ts
-async function configurePlatformsForDir(targetDir, platforms, boundary) {
+async function configurePlatformsForDir(targetDir, platforms, opts = {}) {
   const artifacts = [];
   for (const platform of platforms) {
-    artifacts.push(...await CONFIGURATORS[platform](targetDir, { supermodule: boundary }));
+    artifacts.push(...await CONFIGURATORS[platform](targetDir, opts));
   }
   return artifacts;
 }
 async function installHarnessToDir(targetDir, platforms, ctx) {
-  const artifacts = await configurePlatformsForDir(targetDir, platforms, boundaryFromContext(ctx));
+  const projectId = createProjectId();
+  const artifacts = await configurePlatformsForDir(targetDir, platforms, {
+    supermodule: boundaryFromContext(ctx),
+    projectId
+  });
   await writeRuntimeScaffold(targetDir, platforms, {
-    supermodule: supermoduleConfigFromContext(ctx)
+    supermodule: supermoduleConfigFromContext(ctx),
+    projectId
   });
   await writeInstallManifest(targetDir, {
     harnessVersion: VERSION,
@@ -1653,14 +1745,13 @@ async function addAgent(opts) {
     const toInstall = platforms.filter((platform) => !config.agents.includes(platform));
     const agents = [...config.agents, ...toInstall];
     if (toInstall.length > 0) {
-      const artifacts = await configurePlatformsForDir(
-        target.dir,
-        toInstall,
-        target.boundary
-      );
-      await writeRuntimeScaffold(target.dir, agents, {
+      const projectId = await writeRuntimeScaffold(target.dir, agents, {
         supermodule: target.supermodule
       });
+      const artifacts = await configurePlatformsForDir(target.dir, toInstall, {
+        supermodule: target.boundary,
+        projectId
+      });
       await writeInstallManifest(target.dir, {
         harnessVersion: VERSION,
         agents: toInstall,
@@ -2757,14 +2848,13 @@ async function upgrade(opts) {
     }
   }
   for (const { target, config } of pending) {
-    const artifacts = await configurePlatformsForDir(
-      target.dir,
-      config.agents,
-      target.boundary
-    );
-    await writeRuntimeScaffold(target.dir, config.agents, {
+    const projectId = await writeRuntimeScaffold(target.dir, config.agents, {
       supermodule: target.supermodule
     });
+    const artifacts = await configurePlatformsForDir(target.dir, config.agents, {
+      supermodule: target.boundary,
+      projectId
+    });
     await writeInstallManifest(target.dir, {
       harnessVersion: VERSION,
       agents: config.agents,
@@ -2811,15 +2901,19 @@ async function resolvePendingUpgradeTargets(targets) {
         `${target.label} harness version ${installedVersion} is newer than CLI ${VERSION}. Update the CLI first.`
       );
     }
-    if (relation === -1 || relation === 0 && await needsHookConfigRefresh(target, config.agents)) {
+    if (relation === -1 || relation === 0 && await needsHookConfigRefresh(target, config)) {
       pending.push({ target, config });
     }
   }
   return pending;
 }
-async function needsHookConfigRefresh(target, agents) {
+async function needsHookConfigRefresh(target, config) {
+  const projectId = typeof config.project?.id === "string" ? config.project.id.trim() : "";
+  if (!projectId) {
+    return true;
+  }
   const manifest = await readInstallManifest(target.dir);
-  for (const agent of agents) {
+  for (const agent of config.agents) {
     const meta = resolvePlatformMeta(target.dir, agent);
     const configPath2 = path22.join(target.dir, meta.hookConfigFile);
     const content = await readTextIfExists(configPath2);
@@ -2834,7 +2928,7 @@ async function needsHookConfigRefresh(target, agents) {
     }
     const commandsByEvent = collectHookCommandsByEvent(parsed.hooks);
     const commands = [...commandsByEvent.values()].flat();
-    const expectedRegistrations = expectedHookRegistrations(target.dir, meta, agent);
+    const expectedRegistrations = expectedHookRegistrations(target.dir, meta, agent, projectId);
     const expectedCommandSet = new Set(
       expectedRegistrations.map((registration) => registration.command)
     );
@@ -2859,10 +2953,10 @@ async function needsHookConfigRefresh(target, agents) {
   }
   return false;
 }
-function expectedHookRegistrations(cwd, meta, platform) {
+function expectedHookRegistrations(cwd, meta, platform, projectId) {
   return EXPECTED_HOOK_REGISTRATION_SCRIPTS[platform].map(({ event, scriptName }) => ({
     event,
-    command: renderHookCommand(cwd, meta.templateContext, scriptName)
+    command: renderHookCommand(cwd, meta.templateContext, scriptName, process.platform, projectId)
   }));
 }
 function hasExpectedHookRegistrations(commandsByEvent, expectedRegistrations) {