@fuxi-ailabs/dsh-ecat 0.1.0-alpha.1 → 0.1.0-alpha.3

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Fuxi AI Labs
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Fuxi AI Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,4 @@
-# @fuxi-ailabs/dsh-ecat
+# dsh-ecat
 
 Two DSH commands over the ECAT refinement loop.
 
@@ -14,7 +14,7 @@ argv array; the raw input is never passed to a shell.
 ## Install
 
 ```
-dsh plugin --profile <profile> add @fuxi-ailabs/dsh-ecat
+dsh plugin --profile <profile> add dsh-ecat
 ```
 
 Or add the market index source and install from the discovers page. The package is MIT
@@ -149,3 +149,21 @@ than silently reading the session's cwd, which could start the loop on the wrong
 | `spawn failed: ENOENT` | `pythonPath` does not exist on the DSH host |
 | preflight `exit 15` | `ecat` is not on the host PATH |
 | preflight `exit 13` | the variable named by `api_key_env` has no value in `<ws>/.env` |
+
+## Releasing the npm package
+
+Everything needed to build and publish ships on the `dsh-plugin` branch: `src/`,
+the two skills under `assets/skills/`, and the ECAT wheel under `assets/wheels/`.
+The `ECAT_core` branch is not required for a release (refresh the wheel only when
+core behaviour that the plugin relies on changed).
+
+1. `git checkout dsh-plugin` and make sure the tree is clean.
+2. `node integrations/dsh/scripts/sync-skills.mjs` — keeps `assets/skills` identical to `./skills`.
+3. If ECAT core changed: build a wheel from that revision (`uv build`) and replace `assets/wheels/ecat-*.whl`.
+4. Bump the version: `npm version prerelease --preid=alpha --no-git-tag-version`.
+5. `cd integrations/dsh && npm pack --dry-run` — expect the same 37 files, including `src/client.js`.
+6. `npm publish --tag alpha`.
+7. `git push origin dsh-plugin`.
+
+Keep `name` in `package.json` and the `insert` entry in `cordis.patch.yml`
+identical (`@fuxi-ailabs/dsh-ecat`); a mismatch makes the plugin fail to import.

package/assets/skills/ecat-refine/config.dsh.yaml

@@ -1,104 +1,104 @@
-# ECAT — DeepSeek Harness (dsh) runtime, headless one-shot mode.
-#
-# Differences from the claude_code config:
-#   * no base_url — dsh owns its endpoint (official route or DEEPSEEK_BASE_URL);
-#     ECAT rejects base_url for this runtime rather than silently ignoring it.
-#   * model is written into a per-call patch, because headless has no --model.
-#   * api_key_env defaults to DEEPSEEK_API_KEY; the runner exports the resolved
-#     value under that name whatever variable the config points at.
-#   * each role gets its own DSH_HOME under .ecat/agents/<role>/ (profile +
-#     AGENTS.md), created automatically on the first run.
-#
-# Verify with: python <skill>/scripts/preflight.py --config <this file> --workspace <WS>
-
-# ─── Identity ────────────────────────────────────────────────────────────────
-project: my-project
-work_dir: .
-
-# ─── Prompt profile ──────────────────────────────────────────────────────────
-# Domain fragment under ecat/prompts/profiles/<name>/. "a2h" ships with the
-# repo; create your own with the ecat-setup skill.
-profile: a2h
-
-# ─── Source / Target paths ───────────────────────────────────────────────────
-paths:
-  # source: ./reference      # optional: only for a task with a ground-truth tree
-  target: ./target           # required, must exist
-
-# ─── Agents ──────────────────────────────────────────────────────────────────
-generator:
-  runtime: dsh
-  model: deepseek-flash
-  provider: deepseek
-  base_url: null             # must stay null for dsh
-  api_key_env: DEEPSEEK_API_KEY
-  config_dir: .ecat/agents/generator
-  timeout_s: 5400
-  extra_args: []
-  # Continue the same dsh session across iterations (--session-id). Saves
-  # cache reads; context grows, so pair it with the loop's compaction setting.
-  resume_session: true
-
-discriminator:
-  runtime: dsh
-  model: deepseek-flash
-  provider: deepseek
-  base_url: null
-  api_key_env: DEEPSEEK_API_KEY
-  config_dir: .ecat/agents/discriminator
-  timeout_s: 3600
-  extra_args: []
-  evolution_write_paths:
-    - .ecat/agents/generator/skills
-    - .ecat/agents/generator/memory
-
-# ─── Adversarial loop ────────────────────────────────────────────────────────
-loop:
-  max_iterations: 100
-  entropy_threshold: 0.01
-  stable_iters_to_stop: 2
-  regression_tolerance: 0.1
-  revert_on_regression: true
-  oscillation_guard:
-    enabled: true
-    window: 5
-    min_delta: 0.02
-  # dsh runs one process per call and has no in-session /compact, so this knob
-  # is a no-op here. Context growth is handled by dsh's own compaction-basic
-  # (threshold 0.8 of the model window) inside each resumed session.
-  generator_compact_interval: 0
-  max_items_per_iter: 25
-
-# ─── Entropy plugin set ──────────────────────────────────────────────────────
-# `example` ships with the repo. Replace with the set you build; every
-# dimension listed in weights must be registered by some plugin.
-entropy:
-  plugin_set: example
-  judge_max_issues: 10
-  weights:
-    compile: 0.30
-    feature_parity: 0.35
-
-# ─── Retry ────────────────────────────────────────────────────────────────────
-# dsh retries transient provider failures inside the turn (dsh-llm-retry).
-# Keep this modest so an upstream outage surfaces as a failed iteration rather
-# than hours of silent retrying.
-retry:
-  max_attempts: 2
-  base_delay_s: 2
-  max_delay_s: 30
-  jitter: true
-
-# ─── Phase gates ─────────────────────────────────────────────────────────────
-features:
-  memory_evolution: false
-  skill_evolution: false
-  multi_discriminator: false
-  in_loop_intervention: false
-
-# ─── Reporting ───────────────────────────────────────────────────────────────
-reporting:
-  chart_format: png
-  chart_on_each_iter: true
-  keep_run_artifacts: -1
-  log_level: info
+# ECAT — DeepSeek Harness (dsh) runtime, headless one-shot mode.
+#
+# Differences from the claude_code config:
+#   * no base_url — dsh owns its endpoint (official route or DEEPSEEK_BASE_URL);
+#     ECAT rejects base_url for this runtime rather than silently ignoring it.
+#   * model is written into a per-call patch, because headless has no --model.
+#   * api_key_env defaults to DEEPSEEK_API_KEY; the runner exports the resolved
+#     value under that name whatever variable the config points at.
+#   * each role gets its own DSH_HOME under .ecat/agents/<role>/ (profile +
+#     AGENTS.md), created automatically on the first run.
+#
+# Verify with: python <skill>/scripts/preflight.py --config <this file> --workspace <WS>
+
+# ─── Identity ────────────────────────────────────────────────────────────────
+project: my-project
+work_dir: .
+
+# ─── Prompt profile ──────────────────────────────────────────────────────────
+# Domain fragment under ecat/prompts/profiles/<name>/. "a2h" ships with the
+# repo; create your own with the ecat-setup skill.
+profile: a2h
+
+# ─── Source / Target paths ───────────────────────────────────────────────────
+paths:
+  # source: ./reference      # optional: only for a task with a ground-truth tree
+  target: ./target           # required, must exist
+
+# ─── Agents ──────────────────────────────────────────────────────────────────
+generator:
+  runtime: dsh
+  model: deepseek-flash
+  provider: deepseek
+  base_url: null             # must stay null for dsh
+  api_key_env: DEEPSEEK_API_KEY
+  config_dir: .ecat/agents/generator
+  timeout_s: 5400
+  extra_args: []
+  # Continue the same dsh session across iterations (--session-id). Saves
+  # cache reads; context grows, so pair it with the loop's compaction setting.
+  resume_session: true
+
+discriminator:
+  runtime: dsh
+  model: deepseek-flash
+  provider: deepseek
+  base_url: null
+  api_key_env: DEEPSEEK_API_KEY
+  config_dir: .ecat/agents/discriminator
+  timeout_s: 3600
+  extra_args: []
+  evolution_write_paths:
+    - .ecat/agents/generator/skills
+    - .ecat/agents/generator/memory
+
+# ─── Adversarial loop ────────────────────────────────────────────────────────
+loop:
+  max_iterations: 100
+  entropy_threshold: 0.01
+  stable_iters_to_stop: 2
+  regression_tolerance: 0.1
+  revert_on_regression: true
+  oscillation_guard:
+    enabled: true
+    window: 5
+    min_delta: 0.02
+  # dsh runs one process per call and has no in-session /compact, so this knob
+  # is a no-op here. Context growth is handled by dsh's own compaction-basic
+  # (threshold 0.8 of the model window) inside each resumed session.
+  generator_compact_interval: 0
+  max_items_per_iter: 25
+
+# ─── Entropy plugin set ──────────────────────────────────────────────────────
+# `example` ships with the repo. Replace with the set you build; every
+# dimension listed in weights must be registered by some plugin.
+entropy:
+  plugin_set: example
+  judge_max_issues: 10
+  weights:
+    compile: 0.30
+    feature_parity: 0.35
+
+# ─── Retry ────────────────────────────────────────────────────────────────────
+# dsh retries transient provider failures inside the turn (dsh-llm-retry).
+# Keep this modest so an upstream outage surfaces as a failed iteration rather
+# than hours of silent retrying.
+retry:
+  max_attempts: 2
+  base_delay_s: 2
+  max_delay_s: 30
+  jitter: true
+
+# ─── Phase gates ─────────────────────────────────────────────────────────────
+features:
+  memory_evolution: false
+  skill_evolution: false
+  multi_discriminator: false
+  in_loop_intervention: false
+
+# ─── Reporting ───────────────────────────────────────────────────────────────
+reporting:
+  chart_format: png
+  chart_on_each_iter: true
+  keep_run_artifacts: -1
+  log_level: info

package/assets/skills/ecat-refine/scripts/_cli_path.py

@@ -56,9 +56,14 @@ def _npm_bin() -> Path | None:
     return prefix if os.name == "nt" else prefix / "bin"
 
 
-def find_cli(name: str) -> tuple[Path | None, bool]:
-    """返回 (可执行文件路径, 是否已在 PATH 上)。找不到返回 (None, False)。"""
-    on_path = shutil.which(name)
+def find_cli(name: str, path: str | None = None) -> tuple[Path | None, bool]:
+    """返回 (可执行文件路径, 是否在给定 PATH 上)。找不到返回 (None, False)。
+
+    *path* 是可选的自定义 PATH 串（默认用当前进程的 PATH）。start.py 传入的是
+    `ensure_on_path` 加过目录的 child_env，这样"体检报告的 ecat"和"启动执行的 ecat"
+    解析的是同一个环境。
+    """
+    on_path = shutil.which(name, path=path) if path is not None else shutil.which(name)
     if on_path:
         return Path(on_path), True
 
@@ -67,8 +72,9 @@ def find_cli(name: str) -> tuple[Path | None, bool]:
     if npm:
         dirs.insert(0, npm)
 
-    # Windows 上 npm 装出来的是 name.cmd（外加一个无扩展名的 shell 包装，不能直接跑）
-    names = [f"{name}.cmd", f"{name}.exe", name] if os.name == "nt" else [name]
+    # Windows 上 .exe 优先：`CreateProcess` 只补 .exe，`.cmd` 必须经 cmd /c 才能跑
+    # （见 cli_command）。若这里先返回 .cmd，start.py 的裸命令会解析到另一个 exe。
+    names = [f"{name}.exe", f"{name}.cmd", f"{name}.bat", name] if os.name == "nt" else [name]
     for d in dirs:
         if not d.is_dir():
             continue
@@ -79,6 +85,19 @@ def find_cli(name: str) -> tuple[Path | None, bool]:
     return None, False
 
 
+def cli_command(path: str | Path, *args: str) -> list[str]:
+    """构造执行 *path* 的 argv。
+
+    Windows 的 `CreateProcess` 不能直接跑 `.cmd/.bat`（只补 `.exe`），必须显式经
+    `cmd /c`；start.py 与 preflight 共用这个函数，保证"预检认为可用"与"实际能启动"
+    指向同一个入口。
+    """
+    p = Path(path)
+    if os.name == "nt" and p.suffix.lower() in (".cmd", ".bat"):
+        return ["cmd", "/c", str(p), *args]
+    return [str(p), *args]
+
+
 def ensure_on_path(names: list[str], env: dict[str, str] | None = None) -> tuple[dict[str, str], list[str]]:
     """把 *names* 里不在 PATH 上、但能在已知位置找到的 CLI，其目录前置进 PATH。
 

package/assets/skills/ecat-refine/scripts/start.py

@@ -22,7 +22,7 @@ from datetime import datetime
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent))
-from _cli_path import ensure_on_path  # noqa: E402
+from _cli_path import cli_command, ensure_on_path, find_cli  # noqa: E402
 from _proc import pid_alive  # noqa: E402
 
 STATE_REL = Path(".ecat") / "skill-refine.state"
@@ -62,11 +62,6 @@ def main() -> int:
                   file=sys.stderr)
             return 2
 
-    cmd = ["ecat", "refine", "--config", str(cfg)]
-    if args.max_iter:
-        cmd += ["--max-iter", str(args.max_iter)]
-    cmd += args.extra
-
     # npm -g 装的 CLI 常常不在 PATH（实测 opencode 在 %APPDATA%\npm）。ECAT 起子进程
     # 时继承的就是这里的环境，所以在这一层补进去即可，不动用户的 shell profile。
     # deveco 是 opencode 的 fork（npm @deveco/deveco-code），同样装 in npm 前缀目录。
@@ -74,6 +69,26 @@ def main() -> int:
     for n in notes:
         print(f"  PATH 注入  {n}")
 
+    # 子进程（ecat CLI）的 stdout 直接写进 boot.log，失败时 start.py 按 UTF-8 读回来。
+    # 默认中文 Windows 上 Python 会按 CP936 写，这段中文就会变成乱码；强制 UTF-8，
+    # 让写入方和读取方用同一个编码（run.log 由 ECAT 自己的 FileHandler 写，本来就是 UTF-8）。
+    child_env["PYTHONUTF8"] = "1"
+    child_env["PYTHONIOENCODING"] = "utf-8"
+
+    # 与 preflight 用同一个解析结果（child_env 的 PATH），不要用裸命令：
+    # Windows 的 CreateProcess 只补 .exe，并且先搜解释器所在目录（venv\Scripts），
+    # 裸 "ecat" 可能执行到另一个安装；若只有 .cmd，则根本起不来。
+    ecat_cli, _ = find_cli("ecat", path=child_env.get("PATH"))
+    if ecat_cli is None:
+        print("找不到 ecat 命令（uv tool install --editable <ECAT 仓>）", file=sys.stderr)
+        return 3
+    print(f"  ecat      {ecat_cli}")
+
+    cmd = cli_command(ecat_cli, "refine", "--config", str(cfg))
+    if args.max_iter:
+        cmd += ["--max-iter", str(args.max_iter)]
+    cmd += args.extra
+
     (ws / ".ecat").mkdir(parents=True, exist_ok=True)
     boot = ws / BOOT_REL
     # 脱离调用方进程组：调用方会话结束时不该带走几小时的 run

package/assets/skills/ecat-setup/references/plugin-design.md

@@ -1,111 +1,111 @@
-# 熵维度插件设计 / Designing entropy dimensions
-
-配置 ECAT 时最容易做错的一步。`profile` 决定 Generator **怎么写**代码，插件决定 ECAT **怎么判断**代码好不好 —— 权重里每个维度都必须有插件来算，否则该维度静默失效（不报错、不派 judge、Generator 永远收不到该维度的工单）。
-
-## 一个维度该多大
-
-一个维度 = **一个可以独立打分的质量主张**。判断标准：它的分数能不能单独解释给用户听？
-
-- 好："目标仓的公开 API 覆盖了源仓的 `__all__`"（能单独解释、能单独修）
-- 好："目标仓能编译通过"（能单独解释）
-- 坏："代码质量"（什么都沾、分数说不清、修起来没头）
-
-3–5 个维度是舒适区。**每个维度必须有独立的 `name`** —— 它就是 `entropy.weights` 里的键。
-
-## 先问：这个判断能写成确定性检查吗？
-
-| 能 → **hard 插件** | 不能 → **agentic 插件** |
-|---|---|
-| 编译/构建成功、错误条数 | 行为是否与源一致 |
-| 导出符号表、公开 API 签名比对 | 语义是否等价 |
-| 文件/函数/用例计数 | 移植是否完整（结构在、行为丢） |
-| 静态扫描：禁用写法、TODO 残留、桩函数 | 抽象是否合理、错误处理是否到位 |
-| 测试通过率、覆盖的测试数 | API 用法是否符合目标平台惯例 |
-| 二进制体积、启动耗时 | 文档与实现是否一致 |
-
-**判据**：答案能不能用一段不调 LLM 的代码写出来。能，就写 hard —— hard 维度便宜、稳定、可复现，是熵曲线的骨架。
-
-**至少保留一个 hard 维度**：一个全是 agentic 判分的配置，每轮分数都在 LLM 的主观波动里，Generator 会沿着一堆"感觉不对"的工单乱改，而 H 曲线看不出它是在进步还是在打转。
-
-## 两种插件形状
-
-### hard 插件
-
-```python
-class ExportApiPlugin(EntropyPlugin):
-    name = "build_api"
-    default_weight = 0.3
-    judge_mode = "hard"          # 默认值，可不写
-
-    def evaluate(self, target_dir, *, source_dir=None, config=None):
-        src = _read_exports(source_dir)      # 确定性检查
-        dst = _read_exports(target_dir)
-        missing = src - dst
-        return len(missing) / max(len(src), 1), {
-            "missing": sorted(missing)[:50],
-            "total": len(src),
-        }
-
-    def extract_work_items(self, score, details):   # 必须实现
-        return [WorkItem(file=..., severity="high", summary=...) for ... in details["missing"]]
-```
-
-要点：
-- `evaluate` 返回 `(score, details)`，`0.0` = 无熵。**`details` 是给人看的 JSON** —— 它会进判别器的提示词，所以要写"哪里不对"而不是只写一个数。
-- **`extract_work_items` 是 hard 插件的价值所在**：它把 details 变成 Generator 能直接执行的工单（文件 + 问题 + 严重度）。返回 `[]` 等于告诉 Generator "这维有问题但你自己找" —— 浪费一整轮。
-- 不配 `source_dir` 时要么跳过（`{"skipped": "no_source_tree"}`），要么退化成"自查"的规则；别拿 `None` 去比。
-
-### agentic 插件
-
-照抄 `src/ecat/entropy/plugins/example/check_feature_parity.py`。三件必需的事：
-
-```python
-class BehaviourParityPlugin(EntropyPlugin):
-    name = "behaviour_parity"
-    default_weight = 0.35
-    judge_mode = "agentic"
-    hard_weight = 0.0            # 不掺 hard 分，取 judge 的分
-    judge_prompt = "..."         # 打分标准（rubric）—— 领域措辞只属于这里
-
-    def evaluate(self, target_dir, *, source_dir=None, config=None):
-        if source_dir is None or not Path(source_dir).exists():
-            return 0.0, {"skipped": "no_source_tree"}
-        return 0.0, {…}          # 只给 judge 一点定位线索，不打分
-
-    def extract_work_items(self, score, details):
-        return []                # 工单由 judge 的 issues 生成，这里必须空
-```
-
-- **`hard_weight = 0.0`**：默认 0.4 会把 `evaluate` 的分和 judge 的分混合。agentic 插件的 `evaluate` 通常只做定位、不做打分，掺进去等于用一个假分数稀释真判断。
-- **`extract_work_items` 必须返回 `[]`**：judge 的每条 issue 会被自动转成工单（按 issue 开头的文件路径分组）。这里再返回东西会**重复产出工单**，Generator 干两遍。
-- **`judge_prompt` 里写死"每条 issue 以目标文件路径开头"**：judge 的 issue 靠前导路径分组才能按文件并行派发。骨架里也有这条，但插件自己的 rubric 里重申一遍更保险。
-- **`{"skipped": ...}` 的语义**：该维度既不派 judge、也不参与权重归一化。源树缺失、清单没配时用它 —— 不要"默认通过"（那是骗自己，会掩盖漏配）。
-
-## 权重怎么定
-
-- 权重**不必和为 1**，ECAT 会归一化。写相对重要性即可。
-- 每一维都问："**这维出问题时，用户会真的在意吗？**" 只是"最好有"的维度给 0.05–0.1，核心正确性维度给 0.3–0.4。
-- **权重 0 或不在 weights 里的维度会被禁用** —— 这是关掉某维度的正确方式，不是删插件。
-- 想调但不确定：先都写 0.2–0.3 跑 2–3 轮，看 H 曲线里哪一维贡献最大再重配。
-
-## 三方库迁移（PC numpy → HarmonyOS）该配什么
-
-这个任务的特点是**源和目标语言不同、且可能需要改底层 C++**，所以"结构像"完全不代表"能用"。维度应按**可验证程度从强到弱**排：
-
-| 维度 | 形状 | 怎么打分 | 建议权重 |
-|---|---|---|---|
-| `compile_native` | hard | 跑目标平台的编译命令（hvigor / clang 交叉编译），按错误条数归一 | 0.30 |
-| `export_api` | hard | 解析源包的 `__all__` / 公开符号表（Python 侧可用 `ast`，C 侧解析头文件），与目标侧导出的 NAPI/ArkTS 接口比对，算缺失比例 | 0.25 |
-| `test_parity` | hard | 源包的测试用例能在目标上跑通的比例。**有测试就优先用它** —— 这是最强的信号，比任何 LLM 判断都硬 | 0.25 |
-| `behaviour_parity` | agentic | judge 读源实现 + 目标实现，报告行为不一致处（数值精度、边界条件、dtype 提升规则、广播语义、异常行为） | 0.15 |
-| `native_impl_gap` | agentic | judge 找目标侧留下的桩：`// TODO`、直接 `return None`、把 C++ 实现换成纯 JS 近似、砍掉的 SIMD 路径 | 0.05–0.10 |
-
-**算例里的三个坑**：
-
-1. **数值库的"能跑"和"算得对"是两回事。** 只做 hard 编译维度会让 H 降到 0 但结果全错。所以 `test_parity` 或 `behaviour_parity` 必须占足够权重。如果源包自带测试套（numpy 有），`test_parity` 是最高性价比的维度 —— 直接把源测试搬到目标上跑，通过率就是分数。
-2. **C++ 侧没有现成的符号表可比。** `export_api` 要分两层：Python/ArkTS 层的公开 API（能解析、能做），C 层函数的覆盖（往往只能靠 `native_impl_gap` 的 agentic 判断）。别硬写一个解析 C++ 的 hard 插件 —— 写不准，还会给 Generator 假工单。
-3. **单树任务退化的情形。** 如果用户的场景是"从零实现一个 numpy 子集"而没有源包，`source` 留空，`export_api`/`test_parity` 要改成对着 **spec 文件**（一份 API 清单 / 需求文档）比对，`evaluate` 里检查 spec 是否配置：未配就 `{"skipped": "no_spec_configured"}`。这正对应 `config.paths` 里 `spec` / `feature_checklist` 那类可选路径。
-
-## 写完要过的一关
-
-`check.py` 会核对 `entropy.weights` 里的每个维度名是否都有插件注册。**这一步必须 0 才起跑** —— 漏配的维度不会报错，只会安静地不生效，而你要等到跑完几小时、看 H 曲线不动时才发现。
+# 熵维度插件设计 / Designing entropy dimensions
+
+配置 ECAT 时最容易做错的一步。`profile` 决定 Generator **怎么写**代码，插件决定 ECAT **怎么判断**代码好不好 —— 权重里每个维度都必须有插件来算，否则该维度静默失效（不报错、不派 judge、Generator 永远收不到该维度的工单）。
+
+## 一个维度该多大
+
+一个维度 = **一个可以独立打分的质量主张**。判断标准：它的分数能不能单独解释给用户听？
+
+- 好："目标仓的公开 API 覆盖了源仓的 `__all__`"（能单独解释、能单独修）
+- 好："目标仓能编译通过"（能单独解释）
+- 坏："代码质量"（什么都沾、分数说不清、修起来没头）
+
+3–5 个维度是舒适区。**每个维度必须有独立的 `name`** —— 它就是 `entropy.weights` 里的键。
+
+## 先问：这个判断能写成确定性检查吗？
+
+| 能 → **hard 插件** | 不能 → **agentic 插件** |
+|---|---|
+| 编译/构建成功、错误条数 | 行为是否与源一致 |
+| 导出符号表、公开 API 签名比对 | 语义是否等价 |
+| 文件/函数/用例计数 | 移植是否完整（结构在、行为丢） |
+| 静态扫描：禁用写法、TODO 残留、桩函数 | 抽象是否合理、错误处理是否到位 |
+| 测试通过率、覆盖的测试数 | API 用法是否符合目标平台惯例 |
+| 二进制体积、启动耗时 | 文档与实现是否一致 |
+
+**判据**：答案能不能用一段不调 LLM 的代码写出来。能，就写 hard —— hard 维度便宜、稳定、可复现，是熵曲线的骨架。
+
+**至少保留一个 hard 维度**：一个全是 agentic 判分的配置，每轮分数都在 LLM 的主观波动里，Generator 会沿着一堆"感觉不对"的工单乱改，而 H 曲线看不出它是在进步还是在打转。
+
+## 两种插件形状
+
+### hard 插件
+
+```python
+class ExportApiPlugin(EntropyPlugin):
+    name = "build_api"
+    default_weight = 0.3
+    judge_mode = "hard"          # 默认值，可不写
+
+    def evaluate(self, target_dir, *, source_dir=None, config=None):
+        src = _read_exports(source_dir)      # 确定性检查
+        dst = _read_exports(target_dir)
+        missing = src - dst
+        return len(missing) / max(len(src), 1), {
+            "missing": sorted(missing)[:50],
+            "total": len(src),
+        }
+
+    def extract_work_items(self, score, details):   # 必须实现
+        return [WorkItem(file=..., severity="high", summary=...) for ... in details["missing"]]
+```
+
+要点：
+- `evaluate` 返回 `(score, details)`，`0.0` = 无熵。**`details` 是给人看的 JSON** —— 它会进判别器的提示词，所以要写"哪里不对"而不是只写一个数。
+- **`extract_work_items` 是 hard 插件的价值所在**：它把 details 变成 Generator 能直接执行的工单（文件 + 问题 + 严重度）。返回 `[]` 等于告诉 Generator "这维有问题但你自己找" —— 浪费一整轮。
+- 不配 `source_dir` 时要么跳过（`{"skipped": "no_source_tree"}`），要么退化成"自查"的规则；别拿 `None` 去比。
+
+### agentic 插件
+
+照抄 `src/ecat/entropy/plugins/example/check_feature_parity.py`。三件必需的事：
+
+```python
+class BehaviourParityPlugin(EntropyPlugin):
+    name = "behaviour_parity"
+    default_weight = 0.35
+    judge_mode = "agentic"
+    hard_weight = 0.0            # 不掺 hard 分，取 judge 的分
+    judge_prompt = "..."         # 打分标准（rubric）—— 领域措辞只属于这里
+
+    def evaluate(self, target_dir, *, source_dir=None, config=None):
+        if source_dir is None or not Path(source_dir).exists():
+            return 0.0, {"skipped": "no_source_tree"}
+        return 0.0, {…}          # 只给 judge 一点定位线索，不打分
+
+    def extract_work_items(self, score, details):
+        return []                # 工单由 judge 的 issues 生成，这里必须空
+```
+
+- **`hard_weight = 0.0`**：默认 0.4 会把 `evaluate` 的分和 judge 的分混合。agentic 插件的 `evaluate` 通常只做定位、不做打分，掺进去等于用一个假分数稀释真判断。
+- **`extract_work_items` 必须返回 `[]`**：judge 的每条 issue 会被自动转成工单（按 issue 开头的文件路径分组）。这里再返回东西会**重复产出工单**，Generator 干两遍。
+- **`judge_prompt` 里写死"每条 issue 以目标文件路径开头"**：judge 的 issue 靠前导路径分组才能按文件并行派发。骨架里也有这条，但插件自己的 rubric 里重申一遍更保险。
+- **`{"skipped": ...}` 的语义**：该维度既不派 judge、也不参与权重归一化。源树缺失、清单没配时用它 —— 不要"默认通过"（那是骗自己，会掩盖漏配）。
+
+## 权重怎么定
+
+- 权重**不必和为 1**，ECAT 会归一化。写相对重要性即可。
+- 每一维都问："**这维出问题时，用户会真的在意吗？**" 只是"最好有"的维度给 0.05–0.1，核心正确性维度给 0.3–0.4。
+- **权重 0 或不在 weights 里的维度会被禁用** —— 这是关掉某维度的正确方式，不是删插件。
+- 想调但不确定：先都写 0.2–0.3 跑 2–3 轮，看 H 曲线里哪一维贡献最大再重配。
+
+## 三方库迁移（PC numpy → HarmonyOS）该配什么
+
+这个任务的特点是**源和目标语言不同、且可能需要改底层 C++**，所以"结构像"完全不代表"能用"。维度应按**可验证程度从强到弱**排：
+
+| 维度 | 形状 | 怎么打分 | 建议权重 |
+|---|---|---|---|
+| `compile_native` | hard | 跑目标平台的编译命令（hvigor / clang 交叉编译），按错误条数归一 | 0.30 |
+| `export_api` | hard | 解析源包的 `__all__` / 公开符号表（Python 侧可用 `ast`，C 侧解析头文件），与目标侧导出的 NAPI/ArkTS 接口比对，算缺失比例 | 0.25 |
+| `test_parity` | hard | 源包的测试用例能在目标上跑通的比例。**有测试就优先用它** —— 这是最强的信号，比任何 LLM 判断都硬 | 0.25 |
+| `behaviour_parity` | agentic | judge 读源实现 + 目标实现，报告行为不一致处（数值精度、边界条件、dtype 提升规则、广播语义、异常行为） | 0.15 |
+| `native_impl_gap` | agentic | judge 找目标侧留下的桩：`// TODO`、直接 `return None`、把 C++ 实现换成纯 JS 近似、砍掉的 SIMD 路径 | 0.05–0.10 |
+
+**算例里的三个坑**：
+
+1. **数值库的"能跑"和"算得对"是两回事。** 只做 hard 编译维度会让 H 降到 0 但结果全错。所以 `test_parity` 或 `behaviour_parity` 必须占足够权重。如果源包自带测试套（numpy 有），`test_parity` 是最高性价比的维度 —— 直接把源测试搬到目标上跑，通过率就是分数。
+2. **C++ 侧没有现成的符号表可比。** `export_api` 要分两层：Python/ArkTS 层的公开 API（能解析、能做），C 层函数的覆盖（往往只能靠 `native_impl_gap` 的 agentic 判断）。别硬写一个解析 C++ 的 hard 插件 —— 写不准，还会给 Generator 假工单。
+3. **单树任务退化的情形。** 如果用户的场景是"从零实现一个 numpy 子集"而没有源包，`source` 留空，`export_api`/`test_parity` 要改成对着 **spec 文件**（一份 API 清单 / 需求文档）比对，`evaluate` 里检查 spec 是否配置：未配就 `{"skipped": "no_spec_configured"}`。这正对应 `config.paths` 里 `spec` / `feature_checklist` 那类可选路径。
+
+## 写完要过的一关
+
+`check.py` 会核对 `entropy.weights` 里的每个维度名是否都有插件注册。**这一步必须 0 才起跑** —— 漏配的维度不会报错，只会安静地不生效，而你要等到跑完几小时、看 H 曲线不动时才发现。