niceeval 0.5.0 → 0.5.2

package/docs-site/zh/guides/agent-feedback-loop.mdx

@@ -82,9 +82,9 @@ niceeval show fixtures/button --diff          # sandbox 里的文件改动
 
 榜单、单个 eval 与各证据切面的输出长什么样、历史与抖动怎么看（`--history`）、多次 run 的合成口径，都在[查看结果](/zh/guides/viewing-results)；要项目自己的口径（考试成绩单、代码行数榜），写一个打到 stdout 的报告脚本，见[自定义报告](/zh/guides/custom-reports)——给 agent 的指引只多一行：跑 `npx tsx scripts/report.ts`，读 stdout。
 
-## AGENTS.md 指引区块
+## AGENTS.md / CLAUDE.md 指引区块
 
-模型的训练数据里没有 NiceEval。`npx niceeval init` 会在项目的 `AGENTS.md` 里写入一个托管区块，告诉 agent 先读随包文档再动手：
+模型的训练数据里没有 NiceEval。`npx niceeval init` 会写入一个托管区块，告诉 agent 先读随包文档再动手：项目已有 `AGENTS.md` 就写那份；只有 `CLAUDE.md`（没有 `AGENTS.md`）就直接写进 `CLAUDE.md`，不另建重复文件；两者都没有则新建 `AGENTS.md`。`CLAUDE.md` 是指向 `AGENTS.md` 的符号链接时，写入自动落到链接目标，不会分裂成两份内容。
 
 ```md
 <!-- BEGIN:niceeval-agent-rules -->
@@ -100,7 +100,7 @@ artifact files it references are the structured source of truth.
 <!-- END:niceeval-agent-rules -->
 ```
 
-标记之外的内容不会被改动；升级 NiceEval 后重跑 `npx niceeval init` 会刷新标记之内的指引。npm 包只随包发布中文文档（`node_modules/niceeval/docs-site/zh/`）——中文是唯一始终与代码同步的准绳版本，agent 读中文没有障碍，读到的永远是和安装版本一致的行为，而不是训练数据里的旧记忆。
+标记之外的内容不会被改动；升级 NiceEval 后重跑 `npx niceeval init` 会刷新标记之内的指引，且每次都会重新按上述规则判断该写哪份文件。npm 包只随包发布中文文档（`node_modules/niceeval/docs-site/zh/`）——中文是唯一始终与代码同步的准绳版本，agent 读中文没有障碍，读到的永远是和安装版本一致的行为，而不是训练数据里的旧记忆。
 
 ## 报错自带修法
 

package/docs-site/zh/reference/cli.mdx

@@ -13,7 +13,7 @@ description: "NiceEval CLI 参考：exp、init、list、clean 和 view 命令，
     运行命名实验组或配置。可选尾随位置参数按 eval ID 前缀过滤。
   </Card>
   <Card title="npx niceeval init" icon="wand-magic-sparkles">
-    创建空的 `evals/` 目录和最小的 `niceeval.config.ts`；不生成示例 eval 文件。同时在 `AGENTS.md` 写入/刷新 niceeval 指引区块（见[Agent 反馈闭环](/zh/guides/agent-feedback-loop)）。
+    创建空的 `evals/` 目录和最小的 `niceeval.config.ts`；不生成示例 eval 文件。同时写入/刷新 niceeval 指引区块——项目已有 `AGENTS.md` 就写那份，只有 `CLAUDE.md` 就写进 `CLAUDE.md`，都没有则新建 `AGENTS.md`（见[Agent 反馈闭环](/zh/guides/agent-feedback-loop)）。
   </Card>
   <Card title="npx niceeval list" icon="list">
     发现并打印所有 eval，不运行。
@@ -87,6 +87,7 @@ npx niceeval exp compare-models weather
 | `--early-exit` / `--no-early-exit` | boolean | 某个 eval 的一次 attempt 通过后,停止该 eval 剩余的 attempts。 |
 | `--open` / `--no-open` | boolean | `view` 命令专用:启动后自动打开浏览器(默认行为)。 |
 | `--help` | boolean | 打印用法说明并退出。 |
+| `--version` | boolean | 打印 niceeval 的版本号并退出。 |
 
 {/* GENERATED:END cli-flags */}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",

package/src/cli.ts

@@ -64,6 +64,7 @@ interface Flags {
   out?: string;
   port?: number;
   help: boolean;
+  version: boolean;
   // ── show 专属(位置参数仍是 eval id 前缀;这些 flag 选「怎么看」)──
   transcript: boolean;
   trace: boolean;
@@ -116,6 +117,7 @@ const FLAG_OPTIONS = {
   open: { type: "boolean" },
   "no-open": { type: "boolean" },
   help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "v" },
 } as const;
 
 function numberFlag(name: string, raw: string | undefined): number | undefined {
@@ -185,6 +187,7 @@ function parseArgs(argv: string[]): { command: string; positionals: string[]; fl
     earlyExit: values["no-early-exit"] === true ? false : values["early-exit"] === true ? true : undefined,
     open: values["no-open"] === true ? false : values.open === true ? true : undefined,
     help: values.help === true,
+    version: values.version === true,
     transcript: values.transcript === true,
     trace: values.trace === true,
     diff: values.diff === true && diffPath === undefined,
@@ -239,7 +242,7 @@ async function loadConfig(cwd: string): Promise<Config> {
   return mod.default;
 }
 
-// AGENTS.md 托管区块:告诉在这个项目里干活的 coding agent「niceeval 不在你的训练数据里,
+// AGENTS.md/CLAUDE.md 托管区块:告诉在这个项目里干活的 coding agent「niceeval 不在你的训练数据里,
 // 先读随包文档,跑完读结构化结果」。随包只发中文准绳版文档(英文站是手工同步、可能滞后,
 // 不进包,见 package.json 的 files);init 时写入/刷新;标记之外的用户内容永不触碰。
 const AGENT_RULES_BEGIN = "<!-- BEGIN:niceeval-agent-rules -->";
@@ -256,6 +259,18 @@ const AGENT_RULES_CONTENT = [
   "artifact files it references are the structured source of truth.",
 ].join("\n");
 
+// 优先复用已有的 AGENTS.md;项目只有 CLAUDE.md(没有 AGENTS.md)时改写 CLAUDE.md 本身,
+// 不再另建一份重复文件;两者都没有则新建 AGENTS.md。CLAUDE.md 是指向 AGENTS.md 的符号链接时,
+// existsSync 会 follow 链接——目标存在则直接算作「AGENTS.md 已存在」,写入的还是同一份内容,
+// 不会产生分裂;目标不存在(悬空链接)则落回新建 AGENTS.md,写入后链接自然生效。
+function resolveAgentDocPath(cwd: string): string {
+  const agentsPath = join(cwd, "AGENTS.md");
+  if (existsSync(agentsPath)) return agentsPath;
+  const claudePath = join(cwd, "CLAUDE.md");
+  if (existsSync(claudePath)) return claudePath;
+  return agentsPath;
+}
+
 async function initProject(cwd: string): Promise<void> {
   await mkdir(join(cwd, "evals"), { recursive: true });
   const configPath = join(cwd, "niceeval.config.ts");
@@ -273,10 +288,10 @@ async function initProject(cwd: string): Promise<void> {
       "utf-8",
     );
   }
-  const agentsPath = join(cwd, "AGENTS.md");
-  const existing = existsSync(agentsPath) ? await readFile(agentsPath, "utf-8") : "";
+  const agentDocPath = resolveAgentDocPath(cwd);
+  const existing = existsSync(agentDocPath) ? await readFile(agentDocPath, "utf-8") : "";
   const next = upsertManagedBlock(existing, AGENT_RULES_BEGIN, AGENT_RULES_END, AGENT_RULES_CONTENT);
-  if (next !== existing) await writeFile(agentsPath, next, "utf-8");
+  if (next !== existing) await writeFile(agentDocPath, next, "utf-8");
 }
 
 async function openBrowser(url: string): Promise<boolean> {
@@ -312,17 +327,28 @@ function evalsFilterFromExperiment(
   return (id) => expFilter(id) && patternFilter(id);
 }
 
+/** package.json 的 version 字段;-v/--version 直接回显这个号。 */
+async function packageVersion(): Promise<string> {
+  const raw = await readFile(new URL("../package.json", import.meta.url), "utf-8");
+  return (JSON.parse(raw) as { version: string }).version;
+}
+
 async function main(): Promise<void> {
   const cwd = process.cwd();
   await loadDotenv(cwd);
   const { command, positionals, flags } = parseArgs(process.argv.slice(2));
 
-  // --help 不需要 config,先于一切命令处理。
+  // --help / --version 不需要 config,先于一切命令处理。
   if (flags.help) {
     process.stdout.write(t("cli.help"));
     process.exit(0);
   }
 
+  if (flags.version) {
+    process.stdout.write(`${await packageVersion()}\n`);
+    process.exit(0);
+  }
+
   if (command === "view") {
     // 位置参数 = eval id 前缀(收窄报告槽选集);存在的文件路径 = 单文件模式;
     // 结果目录经 --run 递入;--report 整槽替换报告槽(与 show --report 吃同一个文件)。

package/src/i18n/en.ts

@@ -59,7 +59,7 @@ export const en = {
     "Flags:\n" +
     "  --runs n  --max-concurrency n  --timeout ms  --budget usd  --tag t\n" +
     "  --early-exit / --no-early-exit  --strict  --force  --dry  --quiet\n" +
-    "  --junit path  --out dir  --port n  --open / --no-open  -h, --help\n\n" +
+    "  --junit path  --out dir  --port n  --open / --no-open  -h, --help  -v, --version\n\n" +
     "Positional args only select which evals to run (id prefixes); which agent and\n" +
     "how to run come from experiments/ + flags. Env overrides (flag > env > config):\n" +
     "  NICEEVAL_RUNS  NICEEVAL_MAX_CONCURRENCY  NICEEVAL_TIMEOUT  NICEEVAL_BUDGET\n",

package/src/i18n/zh-CN.ts

@@ -55,7 +55,7 @@ export const zhCN = {
     "标志:\n" +
     "  --runs n  --max-concurrency n  --timeout ms  --budget usd  --tag t\n" +
     "  --early-exit / --no-early-exit  --strict  --force  --dry  --quiet\n" +
-    "  --junit path  --out dir  --port n  --open / --no-open  -h, --help\n\n" +
+    "  --junit path  --out dir  --port n  --open / --no-open  -h, --help  -v, --version\n\n" +
     "位置参数只选「跑哪些 eval」(id 前缀);对着哪个 agent、怎么跑来自 experiments/ 与\n" +
     "标志。环境变量覆盖(标志 > 环境变量 > config):\n" +
     "  NICEEVAL_RUNS  NICEEVAL_MAX_CONCURRENCY  NICEEVAL_TIMEOUT  NICEEVAL_BUDGET\n",