agim-cli 1.2.149 → 1.2.151

package/CHANGELOG.md

@@ -4,6 +4,162 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.2.151] - 2026-06-13
+
+### Changed (skills injection — workspace 完整注入铁律 + 编辑入口)
+
+v1.2.150 的 cluster 压缩对 workspace 太狠：35 个 `fin-data-*` 折成一行
+`fin-data-* (35): name1 · name2 · …` 后 LLM 路由质量下降——只剩名字猜，没了
+description 关键词。运营者亲装的 workspace skill 是最强 "我要用" 信号，
+不应该为省 token 牺牲精度。
+
+#### 铁律：workspace 完整注入，不折叠
+
+`buildSkillsSummary` 拆出 `buildAutoInjectionBlock(all)`，bucket 3（workspace）
+重新走 `renderSkillRow`（完整描述行）：
+
+- bucket 0/1/3 全部 full row（agim 框架 / agim builtin / **workspace**）
+- bucket 2 ECC picks 仍 full row（20 个 curated 推荐）
+- 只有 bucket 4（ECC remainder 210 个）才 cluster
+
+#### 渲染顺序调整：0 → 1 → 3 → 2 → 4
+
+workspace 排在 ECC picks 之前。运营者亲装 > 框架预选 > ECC remainder。
+
+#### cluster refine bug fix
+
+旧实现遇到"所有成员都在单个 sub-key 下"（例如全部 `fin-data-*` skill 都共享
+2 段前缀）时 bottom out 不再递归，导致 fin-data 全部折成一行 cluster。
+现在加分支：单 sub-key 占全部成员时自动 `segDepth+1` 继续细分，
+所以 `fin-data-aspd-*` / `fin-data-stock-*` / `fin-data-fund-*` 会拆成
+独立 cluster 而非合并。
+
+#### 编辑入口：~/.agim/skill-injection-override.md
+
+运营者可以覆盖自动生成的 skill 块。文件存在且非空时，**全文替换** auto block
+（路由头 + always-on body 保留）。三个 helper：
+`readInjectionOverride / writeInjectionOverride / deleteInjectionOverride`。
+环境变量 `IMHUB_SKILLS_INJECTION_OVERRIDE_PATH` 可改路径（测试用）。
+
+#### Admin API + SPA 页
+
+- `GET /api/agim-skills/injection` → 返回 `{ auto, override, overrideActive, overridePath, maxOverrideChars }`
+- `PUT /api/agim-skills/injection` body `{ body: string }` → 写 override（空 body=删除；>40k 字符 413）
+- `DELETE /api/agim-skills/injection` → 清除 override
+- 受现有 `/api/agim-skills/*` admin allowlist 守卫
+- 新页面 `/settings/agim-skills/injection`：auto 只读 textarea + override 可编辑 textarea +
+  Save / Clear / Copy-auto / Refresh 按钮 + 字符计数 + ≥10k 警告
+- 中英 i18n 全套
+
+#### 新增 env knob
+
+- `IMHUB_SKILLS_ECC_PICKS=name1,name2,...` 覆盖默认 20 picks（推荐池）
+- `IMHUB_SKILLS_INJECT_ECC_REMAINDER=on|off|name-list`：
+  - `on`（默认）：cluster 模式
+  - `off`：完全抑制 ECC remainder 块（省 token）
+  - 逗号分隔白名单：只保留指定 skill
+
+### Files
+
+- `src/core/skills/loader.ts` — workspace 完整注入 + 顺序调整 + refine bug fix +
+  env knob 解析（`resolveEccTopPicks` / `resolveEccRemainderMode`）+
+  override 文件 helper（read / write / delete / `injectionOverridePath`）+
+  `buildAutoInjectionBlock` 导出供 API 预览
+- `src/web/agim-skills-api.ts` — 新 GET/PUT/DELETE `/api/agim-skills/injection`
+- `src/web/agim-skills-api.test.ts` — +5 case（GET 元数据 / PUT 保存 / DELETE / 空 body=删 / 413 超限）
+- `src/web-app/src/hooks/use-agim-skills.ts` — `useSkillInjection / Save / Delete`
+- `src/web-app/src/routes/settings/agim-skills/injection.tsx` — 新页面
+- `src/web-app/src/routes/settings/agim-skills/layout.tsx` — tab 新增"系统提示注入"
+- `src/web-app/src/router.tsx` — 注册新 route
+- `src/web-app/src/i18n/locales/{zh,en}/settings.json` — `skillInjection.*` 文案
+- `src/core/skills/loader.test.ts` — +5 case（refine 单 sub-key 递归 / picks env / remainder off / remainder allowlist / override 全文替换）；2 case 旧断言更新（workspace 不聚类 / workspace 排在 ECC picks 前）
+
+### Tests
+
+- `loader.test.ts`：42/42 全过
+- `agim-skills-api.test.ts`：19/19 全过
+- typecheck 干净（search.tsx 是历史遗留，不归本 PR）
+- SPA build 干净（`injection-*.js` chunk 已生成）
+
+## [1.2.150] - 2026-06-12
+
+### Changed (skills system-prompt injection — cluster-aware compression)
+
+v1.2.149 的固定 32 行排序在 builtin 加了 230 ECC 后产生回归：
+**用户业务 skill（workspace 源的 fin-data-* / ash-* / 白猪 / 等）全部跌出 top 32**，
+LLM 看不到 description → 无法 route。
+
+#### 新模型：按桶 + cluster 压缩
+
+`buildSkillsSummary` 重写为"按桶+ cluster"输出：
+
+- **Bucket 0–2**：逐行完整 description（curated 小集合，需要颗粒度）
+  - 0 = `agim-*` 框架（4）
+  - 1 = 非 ECC builtin（github / image-generation / long-goal / my / skill-creator / summarize / tmux / weather）
+  - 2 = ECC pinned 推荐（20）
+- **Bucket 3（workspace）**：≥3 个同前缀 skill 自动 cluster——一行块标注 `prefix-* (N)` + 全名 + 短指引；singleton 仍 full row。运营者业务 skill（如 60 个 `fin-data-*`）只用 ~500 字符就能让 **LLM 看到所有名字 + 触发关键词**，而非吃掉 12000 字符 description 预算
+- **Bucket 4（ECC 余下 210）**：cluster + name-only 输出（无 trigger hint）。LLM 看得到这 210 个名字，但要触发时按 description 关键词或显式 `read_skill('exact-name')` 拉全文
+
+#### `clusterSkills(skills, minSize=3)` 算法（pure helper）
+
+按 dash-segment 分层 group：先一段（`fin-*`），≥3 个则尝试细化到二段（`fin-data-*` 单独成 cluster）……最多 3 段深。Cluster prefix 取实际**最长公共段前缀**，所以 35 个 `fin-data-s000..s034` 合成一个 `fin-data` cluster，不是浅 `fin`。
+
+#### 重新分桶（rankSkillBucket）
+
+- workspace 与 ECC 余下 split 开（之前混在 bucket 3）：
+  - workspace → bucket 3（按运营者意图—亲装的优先 cluster 露出，trigger hint 详细）
+  - ECC 余下 → bucket 4（aggressive cluster，仅名字）
+
+#### 实测（agim 默认 builtin）
+
+```
+## Framework (agim-* — …) (4)
+- agim-memory: …（full row）
+- agim-reminders: …
+- agim-self: …
+- agim-skill-discovery: …
+
+## Agim builtin (8)
+- github: … / image-generation / long-goal / my / skill-creator / summarize / tmux / weather
+
+## ECC harness + methodology picks (recommended) (20)
+- agent-eval / agent-harness-construction / agent-introspection-debugging / agentic-engineering
+  / architecture-decision-records / article-writing / autonomous-* / benchmark / blueprint
+  / code-tour / coding-standards / content-engine / context-budget / continuous-learning-v2
+  / cost-aware-llm-pipeline / prompt-optimizer / security-review / tdd-workflow / verification-loop
+
+## ECC remainder (read full description via mcp__imhub__read_skill) (210)
+- django-* (5): django-celery · django-patterns · django-security · django-tdd · django-verification
+- kotlin-* (5): kotlin-coroutines-flows · kotlin-exposed-patterns · kotlin-ktor-patterns
+                 · kotlin-patterns · kotlin-testing
+- laravel-* (5): laravel-{patterns, plugin-discovery, security, tdd, verification}
+- springboot-* (4): springboot-{patterns, security, tdd, verification}
+- quarkus-* (4): quarkus-{patterns, security, tdd, verification}
+- orch-* (6): orch-add-feature · orch-build-mvp · orch-change-feature · …
+- … 14 个 cluster 共 56 skill + (other ECC, 154 个) name 列表
+```
+
+#### Token 预算
+
+- v1.2.149 old: 32 行 × ~200 chars = ~1700 tokens（32 个 skill 露脸）
+- v1.2.150 new: ~3300 tokens（**241 builtin + workspace skill 全部露脸**）
+- net: token +~1600，但**每个 skill 的"存在感"露出**——对 LLM routing 是巨大改善
+- 用户有 ~80 workspace skill 时，预计 +~500 tokens 加 workspace cluster；总 ~3800 tokens
+
+#### `always: true` 行为
+
+原本只走 visible 32；现在改成扫所有 buckets，按 `s.always && s.available` 来内联——
+operator 主动标 `always: true` 的少数 skill 仍可正常 inline。
+
+### Files
+
+- `src/core/skills/loader.ts` — 新增 `SkillCluster` interface + `clusterSkills` pure function + cluster-aware `buildSkillsSummary` + bucket 3/4 split in `rankSkillBucket`
+- `src/core/skills/loader.test.ts` — 更新 2 case（bucket order workspace=3 / ECC remainder=4；cap test 改为验证 cluster 块）
+
+### Tests
+
+37/37 全过，typecheck 双绿，build 8.2s。
+
 ## [1.2.149] - 2026-06-12
 
 ### Fixed (ECC pack — folded-description parser bug)

package/dist/core/skills/loader.d.ts

@@ -104,6 +104,40 @@ export declare function getSkillByName(name: string): SkillMeta | null;
  *  unknown name OR read failure. Honors the MAX_SKILL_BODY_CHARS cap;
  *  oversize files come back truncated with a `[truncated …]` footer. */
 export declare function readSkillBody(name: string): string | null;
+/**
+ * v1.2.151 — Resolve the active ECC top-pick set. Operators can override
+ * via `IMHUB_SKILLS_ECC_PICKS=name1,name2,...`. An empty or unset value
+ * falls back to the default 20-name list. Validation is intentionally
+ * forgiving: unknown names pass through (they just become no-ops when
+ * the named skill isn't installed).
+ */
+export declare function resolveEccTopPicks(): ReadonlySet<string>;
+/**
+ * v1.2.151 — ECC remainder injection policy. Default `on` emits the
+ * cluster block. `off` suppresses it entirely (token-saving for ops
+ * who only want the recommended picks). A comma-list value flips to
+ * "allowlist" mode: only remainder skills in the list are emitted.
+ */
+type EccRemainderMode = {
+    mode: 'on';
+} | {
+    mode: 'off';
+} | {
+    mode: 'allowlist';
+    names: Set<string>;
+};
+export declare function resolveEccRemainderMode(): EccRemainderMode;
+export declare function injectionOverridePath(): string;
+/** Read the override file. Returns the trimmed body, or null when the
+ *  file is missing / empty / unreadable. Never throws. */
+export declare function readInjectionOverride(): string | null;
+/** Write (or replace) the override file. The caller is responsible for
+ *  authorization — this is a thin filesystem helper. Returns true on
+ *  success, false on any disk error. */
+export declare function writeInjectionOverride(body: string): boolean;
+/** Delete the override file. Returns true when a file was actually
+ *  removed (or already gone), false on filesystem error. */
+export declare function deleteInjectionOverride(): boolean;
 /**
  * v1.2.149 — Rank a skill into one of four buckets for system-prompt
  * injection. Lower rank wins (fills the visible 32 first). Within a
@@ -127,5 +161,63 @@ export declare function readSkillBody(name: string): string | null;
  * homelab skills. Both belong in the on-demand pool, not the cap.
  */
 export declare function rankSkillBucket(s: SkillMeta): number;
+/**
+ * v1.2.150 — A prefix-based skill cluster. Many skills sharing a name
+ * prefix (`fin-data-aspd-*`, `white-pig-*`, …) get collapsed into one
+ * block: title + name list + brief trigger hint. The LLM still sees
+ * every skill name, just not every full description; it can call
+ * `read_skill('exact-name')` for granular content.
+ */
+export interface SkillCluster {
+    /** The shared prefix, e.g. "fin-data-aspd" or "white-pig". */
+    prefix: string;
+    /** Skill names in the cluster, alphabetically sorted. */
+    names: string[];
+    /** One-line trigger summary derived from member descriptions
+     *  (best effort). Empty when descriptions are unhelpful. */
+    triggerHint: string;
+}
+/**
+ * v1.2.150 — Pure helper: group `skills` into prefix-based clusters.
+ *
+ * Algorithm:
+ *   1. Group by first dash-segment (`fin-data-aspd-*` → key `fin`).
+ *   2. For groups of size ≥ minSize, try refining to TWO segments
+ *      (`fin-data-*`). If at least 2 two-segment sub-groups themselves
+ *      reach minSize, emit each sub-group as a cluster and the leftover
+ *      single-segment-only members as a fallback `<seg1>-*` cluster.
+ *   3. Sub-clustering attempts also at THREE segments before bottoming
+ *      out, so `fin-data-aspd-*` peels off `fin-data-aspd` instead of
+ *      drowning in a generic `fin-data`.
+ *   4. Skills that don't land in any cluster (≤ minSize − 1 with their
+ *      prefix peers) are returned as singletons; the caller renders
+ *      them as individual rows.
+ *
+ * Pure / deterministic — same input always yields same output.
+ */
+export declare function clusterSkills(skills: ReadonlyArray<SkillMeta>, minSize?: number): {
+    clusters: SkillCluster[];
+    singletons: SkillMeta[];
+};
+/**
+ * v1.2.151 — Build the auto-generated tier-1 block (no header, no
+ * always-on bodies — caller wraps). Separated so the SPA editor can
+ * preview "what would auto produce right now" via the admin API.
+ *
+ * Bucket render order:
+ *   0 framework → 1 builtin → **3 workspace** → 2 ECC picks → 4 ECC remainder
+ *
+ * Operator-installed workspace skills out-rank ECC pinned picks because
+ * they are the strongest "I want this" signal. ECC picks (curated
+ * harness vocabulary) come right after so the LLM still has them
+ * within reach. ECC remainder lives at the bottom as the on-demand
+ * pool.
+ *
+ * Buckets 0/1/2/3 all emit full rows (renderSkillRow). Only bucket 4
+ * (ECC remainder) clusters — and even then, the cluster path can be
+ * disabled or scoped via `IMHUB_SKILLS_INJECT_ECC_REMAINDER`.
+ */
+export declare function buildAutoInjectionBlock(all: ReadonlyArray<SkillMeta>): string;
 export declare function buildSkillsSummary(): string;
+export {};
 //# sourceMappingURL=loader.d.ts.map

package/dist/core/skills/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/core/skills/loader.ts"],"names":[],"mappings":"AAiDA;;sEAEsE;AACtE,eAAO,MAAM,oBAAoB,QAAS,CAAA;AAE1C;;gDAEgD;AAChD,eAAO,MAAM,qBAAqB,MAAM,CAAA;AAExC;;oDAEoD;AACpD,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAErC,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,4EAA4E;IAC5E,MAAM,EAAE,WAAW,GAAG,SAAS,CAAA;IAC/B,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAA;IACX;;2DAEuD;IACvD,MAAM,EAAE,OAAO,CAAA;IACf;qCACiC;IACjC,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB;0DACsD;IACtD,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB;;0EAEsE;IACtE,SAAS,EAAE,OAAO,CAAA;IAClB,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;mEAE+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAmCD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAA;AA4BxD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAiB7C;AAED;sEACsE;AACtE,wBAAgB,oBAAoB,IAAI;IACtC,IAAI,EAAE,UAAU,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;CACpB,CAOA;AAuBD,wEAAwE;AACxE,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAmB3E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAajD;AAYD;;oDAEoD;AACpD,wBAAgB,UAAU,IAAI,SAAS,EAAE,CAExC;AAED;;6BAE6B;AAC7B,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAE7D;AAED;;wEAEwE;AACxE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYzD;AAkDD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAiBpD;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAmE3C"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/core/skills/loader.ts"],"names":[],"mappings":"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"}