# CLAVUE Development Context (Auto-distilled)

**Generated**: 2026-05-29 by scripts/distill-context.mjs (Memory & Handoff 2.0)
**Purpose**: Lightweight, human-curated long-term context for continuous handoff.

---

## 1. Product Identity (from PRODUCT.md)

Clavue is an **execution-first AI coding CLI** for real software work. Provider routing, memory, agents, skills are supporting capabilities.

(See full PRODUCT.md and the approved specs for non-goals.)

## 2. Core Invariants

- One runtime decision per turn
- authored src/ → dist/ only (never hand-edit dist/)
- Surgical changes only + tests + npm run check
- (See AGENTS.md + ARCHITECTURE.md)

## 3. Current Major Initiatives (2026-05)

- Code Health & v11 follow-up (large files, startup latency baseline ~300ms p50 on --version fast path)
- Memory & Handoff 2.0 — this distillation + explicit task sidecars + workspace startup snapshots

## 4. Recent Handoffs (source of active task state)


### Recent Handoff: d9f4ed27-7127-44e4-aa1e-17357a9923a1-2026-05-29T01-22-13-313Z.md

```markdown
---
schemaVersion: handoff-v1
sessionId: d9f4ed27-7127-44e4-aa1e-17357a9923a1
createdAt: "2026-05-29T01:22:13.313Z"
trigger: auto
projectRoot: /Users/lu/codebase
worktreePath: null
planFilePath: null
tokenCountAtCompact: 167742
---

# Handoff: 实现 Opus 4.8 兼容性(用户选定范围:「4.8注册+修4.7bug」)。即:在代码库注册 `claude-opus-4-8`,并修复 Opus 4.7 当年只接一半导致的现存 bug。不改默认模型。changelog 学习 +…

## Task Scope

实现 Opus 4.8 兼容性(用户选定范围:「4.8注册+修4.7bug」)。即:在代码库注册 `claude-opus-4-8`,并修复 Opus 4.7 当年只接一半导致的现存 bug。不改默认模型。changelog 学习 + 现状梳理已在对话中完成,剩下的是把实现改完并验证通过。

## Active Work State

- Opus 4.8 注册 + 4.7 修复的源码改动**已全部落地**(7 个源文件)。 - 测试文件 `tests/known-model-detection.test.mjs` 已扩展:加了 4.8 known-model、`[1m]` 后缀、max-output 回归、effort、knowledge-cutoff、adaptive-thinking 断言。 - **最后两个测试(knowledge-cutoff + adaptive-thinking)刚加完,尚未重跑**。prompts.ts + thinking.ts 的源码改动之后也尚未重跑测试。 - 上一次成功的全量:`npm test` → 1764 tests / 1758 pass / 0 fail / 6 skipped(在 prompts.ts/thinking.ts 编辑和最后 2 个测试新增**之前**)。

## Exact Next Step

运行 `node --test tests/known-model-detection.test.mjs`,确认新增的 knowledge-cutoff 与 adaptive-thinking 断言通过;通过后立即跑 `npm test` 全量回归。失败则按实际源码格式修正测试 regex。

## User Constraints

- 范围限定:「4.8注册+修4.7bug」—— 只注册 4.8 + 修 4.7 现存 bug,**不改默认模型**(`getDefaultOpusModel` firstParty 与 3P 都保持 `opus46`)。
- 「用你分析出来的真正的原因 彻底解决问题」。
- Brand identity: Clavue first;非 Claude-family 模型不要自称 Claude/Anthropic。
- 不嵌入凭证;不手工编辑 `dist/cli.js`;不用 `--no-verify`;npm publish 不可逆需 dry-run。
- 改 `branding.ts` 后必须 `npm run rebuild:dist`。5 个版本面共同 bump。`npm run check` EXIT=0 才发布。
- 「目前这个只发npm 其他的后面再步」——不部署 clavue.com。
- 执行优先:用可用的直接工具做下一个可逆步骤,不要只给状态承诺;不问宽泛战略菜单除非有破坏性风险/缺访问/真正阻塞的产品决策。

## Files In Play

- src/utils/model/configs.ts
- src/utils/model/model.ts
- src/utils/context.ts
- 4.7
- src/utils/effort.ts
- src/constants/prompts.ts
- 4.7/4.8
- src/utils/thinking.ts
- tests/known-model-detection.test.mjs
- src/utils/model/modelOptions.ts

## Pending Tasks

- 重跑 `node --test tests/known-model-detection.test.mjs` 确认全部新断言通过(尤其最后 2 个 regex)。
- 重跑 `npm test` 全量确认无回归(预期 pass 数较 1758 再 +2)。
- 若 regex 断言因源码实际格式不匹配而失败,微调 regex(而非改源码语义)。
- (待用户确认)是否为 Opus 4.8 改动单独 commit;若 commit,遵守版本面 bump + `npm run check` 规则。

## Key Decisions and Invariants

- 顺序敏感:canonical / knowledge-cutoff / max-output 分支里 `opus-4-8` 必须在 `opus-4-7` 之前、`opus-4-6` 之前、通用 `opus-4` 之前。
- 4.6/4.7/4.8 共享 64k default / 128k upper output 上限;旧版保持(4.5→64k,4.1/4.0→32k)。
- modelOptions.ts picker 行绑 `opus` alias → 仍正确显示 4.6 默认;显式 `--model claude-opus-4-8` 经 getMarketingNameForModel 修复后正确渲染 "Opus 4.8"。所以 picker **不需改**。
- 不动产品策略门控(<redacted-token>)——属策略非能力,改即越界。
- 自我纠正:`opus47` 当年**已**在 ALL_MODEL_CONFIGS 中(早先误判为缺失,已更正)。4.7 真 bug 是 max-output(落到 32k)、knowledge-cutoff(落到 Jan 2025)、adaptive-thinking 缺、effort 缺、getMarketingNameForModel 缺。

## Open Issues and Blockers

- 尚未在 prompts.ts/thinking.ts 编辑 + 最后 2 个测试新增之后重跑测试 —— 存在未验证风险(尤其新加的 2 个 regex 断言可能与实际源码格式不完全匹配,需跑过确认)。
- typecheck 的 2 个错误是预存环境问题,与本次改动无关:`error TS2688: Cannot find type definition file for 'node'.` 和 `tsconfig.json(18,5): error TS5101: Option 'baseUrl' is deprecated`。

## Retrieval Hints

- thinking.ts 有两个相似的 opus-4-6/sonnet-4-6 block;目标是第 113 行起的 `modelSupportsAdaptiveThinking`(已改),另一个 block 未动 —— 验证时勿混淆。
- context.ts:getModelMaxOutputTokens 分支顺序(opus-4-8||opus-4-7||opus-4-6 必须先于 opus-4)是 4.7 bug 的根因点。
- prompts.ts:getKnowledgeCutoff 顺序(opus-4-8/4-7 先于通用 opus-4)是 cutoff bug 根因点。
- 模型注册 @[MODEL LAUNCH] 锚点散落在 configs.ts / model.ts / context.ts / effort.ts / thinking.ts / prompts.ts / modelOptions.ts / betas.ts —— 未来新模型需逐一检查。

## How to Resume

```bash
clavue --resume-from-handoff "/Users/lu/.clavue/projects/-Users-lu-codebase/handoffs/d9f4ed27-7127-44e4-aa1e-17357a9923a1-2026-05-29T01-22-13-313Z.md"
```

```


### Recent Handoff: d9f4ed27-7127-44e4-aa1e-17357a9923a1-2026-05-29T01-20-45-267Z.md

```markdown
---
schemaVersion: handoff-v1
sessionId: d9f4ed27-7127-44e4-aa1e-17357a9923a1
createdAt: "2026-05-29T01:20:45.267Z"
trigger: low_efficiency
projectRoot: /Users/lu/codebase
worktreePath: null
planFilePath: null
tokenCountAtCompact: 158564
---

# Handoff: 当前任务:为 Opus 4.8 做兼容(用户原话「Claude Opus 4.8 我们需要针对性的进行一些兼容 看下目前是否正确 你梳理一下」),范围已确认为「**4.8 注册 + 修 4.7 已有 bug**」—— 不改默认模型(`…

## Task Scope

当前任务:为 Opus 4.8 做兼容(用户原话「Claude Opus 4.8 我们需要针对性的进行一些兼容 看下目前是否正确 你梳理一下」),范围已确认为「**4.8 注册 + 修 4.7 已有 bug**」—— 不改默认模型(`opus` alias 仍解析到 4.6)。附带任务:用户还问了 changelog 近期更新「有什么对我们有帮助的启发」——此项只展示了 changelog 要点,**尚未给出提炼后的「对我们的启发」结论**。

## Active Work State

- Opus 4.8 注册核心改动**已全部落地并验证通过**(见下「Files In Play」逐条)。 - 全量测试:**1764 tests / 1758 pass / 0 fail / 6 skipped**(较基线 +3,即我新增的 3 个测试),无回归。模型相关单测 77/77 过。 - 最后一个 grep(检查遗漏的 `opus-4-6` 门控)刚跑完,**结果尚未处理**:发现约 10 处其它文件仍是 `opus-4-6`-only,可能也需要加 4.8(及 4.7),但**还没逐条评估/编辑**。 - Opus 4.8 这批改动**尚未 commit**。

## Exact Next Step

评估 grep 命中的剩余 `opus-4-6` 门控(从 `src/utils/thinking.ts:120`、`src/utils/betas.ts:154`、`src/utils/validateModel.ts:149` 这几个明显属「能力门控」的开始,这些大概率需要加 opus-4-8;而 `extraUsage.ts`/`fastMode.ts`/cost 相关需谨慎判断是否故意限 4.6)。逐个 Read 确认语义后只补该补的,然后跑单测+全量验证。

## User Constraints

- 范围严格限定:**只注册 4.8 + 修 4.7 bug,不改默认模型**(`getDefaultOpusModel` 的 firstParty 保持返回 `opus46`,3P 也保持 4.6)。
- 执行优先:直接做下一个可逆步骤,不要只给计划;广义升级请求选最安全有用的默认范围开工。
- 用真正分析出的根因彻底解决问题。
- (仍在册的发布类铁律,虽本批未触及版本面)改 `branding.ts` 必须 `npm run rebuild:dist`;5 个版本面共同 bump;`npm run check` EXIT=0 才发布;npm publish 不可逆务必 dry-run;不嵌 SSH 凭证;不手编 `dist/cli.js`;不用 `--no-verify`。
- Brand:Clavue first;非 Claude-family 模型不自称 Claude/Anthropic。

## Files In Play

- src/utils/model/configs.ts
- src/utils/model/model.ts
- src/utils/context.ts
- src/utils/effort.ts
- tests/known-model-detection.test.mjs
- 4.8
- src/constants/prompts.ts
- src/utils/extraUsage.ts
- src/utils/fastMode.ts
- src/utils/betas.ts

## Pending Tasks

- 逐条评估 grep 命中的 ~10 处 `opus-4-6` 门控,判断哪些语义上需要 4.8(/4.7),只改该改的(避免动 cost/pricing 等故意只认 4.6 的特例)。
- 改动后重跑 `node --test tests/known-model-detection.test.mjs` + 全量 `npm test` 确认无回归。
- 产出 changelog「对 Clavue 的启发」提炼清单(回应用户第一问)。
- 视情况询问/执行 Opus 4.8 这批的 commit。

## Key Decisions and Invariants

- Opus 4.6/4.7/4.8 三者 max-output 同档:default 64k / upper 128k;旧版不动(4.5→32k/64k,4.1/4.0→32k/32k)。
- `firstPartyNameToCanonical` 与 `getMarketingNameForModel` 中**顺序敏感**:4.8 分支必须在 4.7 之前,4.7 在 4.6 之前。
- `modelSupportsMaxEffort`:只有 opus-4-6 与 opus-4-8 返回 true(4.8 支持 `/effort xhigh`);4.7 不在 max 列。
- **不改 `modelOptions.ts`**:picker 行用 `opus` alias→默认 4.6 是对的;显式 `--model claude-opus-4-8` 已能经 `getMarketingNameForModel` 正确渲染为 "Opus 4.8"。
- tsc 的 2 个报错(`Cannot find type definition file for 'node'`、`baseUrl deprecated`)是**预存环境问题**,与本次改动无关,不要去修。
- Opus 4.8 是**公开 ID**(非 codename),无需进 `scripts/excluded-strings.txt`。

## Open Issues and Blockers

- 未决:grep 命中的 ~10 处 `opus-4-6`-only 门控是否需要补 4.8/4.7(<redacted-token>)。需逐个判断语义(有些是 cost/pricing/fastMode 特例,可能**故意**只认 4.6,不应盲目加)。
- 无失败测试、无报错阻塞。

## Retrieval Hints

- `tests/known-model-detection.test.mjs` 是 4.7/4.8 兼容回归测试模板。
- `src/utils/model/model.ts` 顶部多个 `@[MODEL LAUNCH]` 锚点标记所有需随新模型更新的位置。
- 用户消息含两个官方链接:code.claude.com/docs/en/changelog 与 platform.claude.<redacted-token>(本轮已 fetch,要点见 Critical Context)。
- context.ts:171 的 `getModelMaxOutputTokens` 分支顺序是 4.7 max-output bug 的根因点。

## How to Resume

```bash
clavue --resume-from-handoff "/Users/lu/.clavue/projects/-Users-lu-codebase/handoffs/d9f4ed27-7127-44e4-aa1e-17357a9923a1-2026-05-29T01-20-45-267Z.md"
```

```


### Recent Handoff: d9f4ed27-7127-44e4-aa1e-17357a9923a1-2026-05-29T01-19-12-492Z.md

```markdown
---
schemaVersion: handoff-v1
sessionId: d9f4ed27-7127-44e4-aa1e-17357a9923a1
createdAt: "2026-05-29T01:19:12.492Z"
trigger: low_efficiency
projectRoot: /Users/lu/codebase
worktreePath: null
planFilePath: null
tokenCountAtCompact: 157397
---

# Handoff: 让 Clavue 兼容新发布的 Claude Opus 4.8,并修复梳理出的 Opus 4.7 现存 bug。用户选定范围:**「4.8 注册 + 修 4.7 bug」—— 注册新模型、修 4.7 的两个真 bug,但不改默认模型(…

## Task Scope

让 Clavue 兼容新发布的 Claude Opus 4.8,并修复梳理出的 Opus 4.7 现存 bug。用户选定范围:**「4.8 注册 + 修 4.7 bug」—— 注册新模型、修 4.7 的两个真 bug,但不改默认模型(opus 仍解析到 4.6)**。同时之前还做了 changelog 学习(已完成,产出诊断)。

## Active Work State

Opus 4.8 注册 + 4.7 bug 修复的全部源码编辑**已完成**。最后动作是跑了 7 个模型测试文件,**77/77 全过**。尚未跑全量 `npm test`。此为新的未提交改动集(上一系列已 commit 在 91a7c59)。

## Exact Next Step

运行 `npm test 2>&1 | tail -15`,确认全量无回归(0 fail);若 known-model 相关或任何模型测试失败,定位并修。过则汇报。

## User Constraints

- 范围严格限定:**注册 Opus 4.8 + 修 4.7 bug,不改默认模型**(getDefaultOpusModel 的 firstParty 仍返回 4.6,3P 也保持 4.6)。
- 执行优先(execute now):用工具做下一个可逆步骤,不要只给计划。
- 「用你分析出来的真正的原因 彻底解决问题」。
- 不部署 clavue.com,只发 npm(后续才步进其他)。
- npm publish 不可逆,务必 dry-run;`npm run check` 必须 EXIT=0 才发布。
- 改 branding.ts 后必须 `npm run rebuild:dist`。5 面版本共同 bump(package.json/branding.ts/README/llms.txt/llms-full.txt)。
- 不嵌 SSH 凭证、不手编 dist/cli.js、不用 --no-verify。
- Brand identity: Clavue first;非 Claude-family 模型不要自称 Claude/Anthropic。

## Files In Play

- src/utils/model/configs.ts
- src/utils/model/model.ts
- src/utils/context.ts
- src/utils/effort.ts
- tests/known-model-detection.test.mjs
- 4.8
- src/utils/model/modelOptions.ts

## Pending Tasks

- 跑全量 `npm test` 确认无回归(预期 1761→新增 3 测试,pass 应 +3)。
- 如全过,向用户汇报 Opus 4.8 兼容完成 + 4.7 bug 修复结论。
- (待用户决定)是否 commit 本改动集;是否需要进一步处理 changelog 其他启发项(lean prompt/MCP env vars/plugin defaultEnabled 等)。

## Key Decisions and Invariants

- Opus 4.8: API ID `claude-opus-4-8`(dateless pinned),1M context,**128k max output**(default 64k/upper 128k,同 4.6),effort 默认 high 且**支持 xhigh/max**,知识截止 Jan 2026。Bedrock `us.anthropic.claude-opus-4-8-v1`。
- 4.7 真 bug(已修):原 `claude-opus-4-7` 命中 `m.includes('opus-4')` 落到 32k/32k(Opus 4.0 档);现 4.6/4.7/4.8 共享 64k/128k 分支,放在 opus-4 fallthrough 之前。
- 4.7 的 getMarketingNameForModel 原本缺失,已一并补。
- firstPartyNameToCanonical 顺序敏感:4.8 分支必须在 4.7 之前,4.7 在 4.6 之前。
- modelOptions.ts 不改:picker 默认行绑 `opus` alias→getDefaultOpusModel()(仍 4.6),不改默认就该保持;显式 `--model claude-opus-4-8` 经 getMarketingNameForModel 已能正确渲染 "Opus 4.8"。
- 纠错:opus47 本来就在 ALL_MODEL_CONFIGS 里(早先误判为缺失)。
- 不加 4.8 migration(additive,无 legacy remap 需要)。
- 代码库有 `@[MODEL LAUNCH]:` 锚点注释标记所有需更新点。

## Open Issues and Blockers

- `npx tsc --noEmit` 报 2 个错误,均为**预存环境/配置问题,与本次改动无关**:`error TS2688: Cannot find type definition file for 'node'` 和 `tsconfig.json(18,5): error TS5101: Option 'baseUrl' is deprecated`。我的模型注册改动零类型错误。项目正式验证用 `npm test` 而非 ra…
- 尚未跑全量 npm test 确认无回归。

## Retrieval Hints

- 若需复查 4.8 文档原始字段(pricing/Bedrock 全 ID/Foundry 200k 例外),见本轮 WebFetch models overview 输出。
- modelOptions.ts 里大量 "Opus 4.6" 文案绑 opus alias,刻意未改 —— 若后续用户要求切默认到 4.8,需同步改这些 + getDefaultOpusModel + getClaudeAiUserDefaultModelDescription + renderDefaultModelSetting + getOpusPlanOption 描述。
- `@[MODEL LAUNCH]:` 注释是定位所有需改点的检索关键词。

## How to Resume

```bash
clavue --resume-from-handoff "/Users/lu/.clavue/projects/-Users-lu-codebase/handoffs/d9f4ed27-7127-44e4-aa1e-17357a9923a1-2026-05-29T01-19-12-492Z.md"
```

```


## 5. How to Handoff (recommended)

1. Read this file + latest handoff sidecar.
2. Run `git status` and the most recent approved spec.
3. Make the next reversible step.
4. On phase complete or context pressure: create handoff (future explicit task sidecar) and update this CONTEXT.

---

*This file is the long-term memory layer. Active state lives in handoff sidecars. Raw history in jsonl.*

**Next evolution goal**: Make the above fully automatic via `clavue memory distill` and explicit lightweight task sidecars.
