clearai-dsh 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -2,9 +2,45 @@
 
 All notable changes to this project are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-# Changelog
+## [0.2.2] — 2026-09-18
+
+**装的时候不再吓人。** 0.2.1 的 `npx clearai-dsh install` 会打出一串 peer 警告(react / graphology-types …),读起来像装坏了——而它们一个字都不影响运行。这一版把安装面收窄到运行时真正需要的那一个依赖,并让安装侧 CLI 按系统语言出话。
+
+### Changed
+
+- **安装面只剩一个运行时依赖。** `@xyflow/react` / `graphology` / `graphology-layout-forceatlas2` / `docx` 挪进 `devDependencies`:前三个只在构建期打 vendor(`lib/client.js` 里是**内联**的,装机后不解析 npm),`docx` 只给营销 docx 脚本用。于是 profile 里不再多装一批包,也不会再有那些注定填不上的 peer 警告——React 由 **DSH 宿主**提供(客户端半 `require('react')` 是问宿主拿的),`graphology-types` 只是类型包。运行时唯一保留的是 `zod`(宿主半 `lib/host.js` 真的 `from 'zod'`)。
+- **安装侧 CLI 跟系统语言走。** `doctor` / `install` / `root-yaml` / `seed` / `unseed` 的每一句都在中英两份文案表里(并排放在一处,改的时候不会只改一边);判据是 `--lang zh|en` > `CLEARAI_LANG` > `LC_ALL` / `LC_MESSAGES` / `LANG` > ICU 的默认 locale,`C` / `POSIX` 当「没有语言信息」按英文处理。0.2.1 之前是无论系统是什么都说中文。
+
+## [0.2.1] — 2026-09-18
+
+**知识任务是循环的原生行为,不是另一个模式。** 本体、实体、认识论早就在,但普通研究的最短路径仍然是「检索 → 总结 → 写报告」——要建本体得用户先想起来说一句。这一版修的是**接线缺口**:把知识任务的判据做成结构的(目标还开着 + 带着登记过的假设),系统自己进知识模式;并把图从手写 SVG 换成 React Flow,给了它一个真正的全屏工作区。
+
+### Added
+
+- **知识模式(分诊)**:判据是**结构的**——目标还开着,而且它带着登记过的命题。立约(`SetGoal`)本身就是模型已经做出的承诺;普通问答从不立约,于是从不进这一档(**零成本契约**)。词面启发式猜错了没人能复核,结构判据可以。
+- **知识预检**:把「已知」自动送到模型面前——只读、有界、**词面命中不猜语义**;每条读数说得出它来自哪条事实。
+- **缺口读数**:从已有事实算出还缺什么形态,每条指得出一个能补的动作。真跑的反直觉结论:改变行为的其实是**缺口的可见性**,不是门——所以两者都留(可见性让它想做,门不让它绕过)。
+- **知识门**:结案之前、派评估者之前拦住**没有形态的核心结论**——纯散文不许升格。
+- **知识 Inspector**:点节点或边 → 定义 / 关系 / 断言 / 证据链 / 登记与修订史;「按此筛选」是详情里的**显式动作**,不猜你点它的意思。新增宿主只读路由 `/api/clearai/inspector` 与行为测试。
+- **图谱工作区**:图带可展开成全屏工作区,布局是力导向(知识图谱的原生形状);渲染交给 React Flow(`@xyflow/react` 12,vendor 行随构建走,与 `dist/` 同一条纪律)。
+- **哲学 P6**:「本体生长是循环的原生行为,不是另一个模式」——写进[循环哲学](docs/loop-philosophy.zh-CN.md)与[认识论循环](docs/epistemic-loop.zh-CN.md)(中英)。
+- **素材工具** `tools/panel-shots.mjs`:折一场真会话 → 挂**真组件** → 真 Chrome 截图(与 `tools/graph-shots.mjs` 同一条口径)——面板截图从此可复现,不用人去界面里手点。
+
+### Changed
+
+- **图 DTO 统一**:图带与工作区共用同一份投影,判据只有一处(`fold` → `view()` → `graphProjection()`);「同一份账本 ⇒ 同一张图」是投影的性质。
+- **预设描述**收敛成一句中英并排:「利用认识论循环构建可信本体。Build a trustworthy ontology through the epistemic loop.」——名册只有这两行元数据,宿主不会替我们本地化,所以只能自己写死。
+- **README 的「安装」改为「安装与使用」**:写明怎么在模式选择器里切到 `ClearAI`(默认标准模式不挂认识论循环),并把本体图 / 图带 / Inspector 的真机截图放进去。
+- 营销物料换掉全部陈旧面板截图:知乎稿与 docx、小红书 9 张卡片改用真机会话的投影(统计同步为 15 套件 1618 条断言 · 29 个意图工具 · 6808 行内核 · 50 种事件分支)。
+
+### Fixed
 
-All notable changes to this project are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+- **命题身份在修订时被重新签发**:同一句话在 id 空间里躺着两份读数(一份「已支持」、一份「未触及」),真会话的卡实测 4 条主张显示成 6~8 行。现在主张原文不变就复用原 id,换了主张才发新 id;并补上 `hypothesis/superseded` 一直缺席的生产者。
+- **节点拖不动**(两次):受控 `nodes` 没接 `onNodesChange`;拖动键写成了对象,`[object Object]` 查不到。
+- **React Flow 是 forwardRef 对象,不是函数**——守卫把合法组件判成「没装上」;并改为同作用域注入,不再依赖运行时模块行。
+- **图带收不到 sessionId**;时间戳不再显示 1970。
+- **工作区读面有主人**:子会话结构上写不进词汇 / 事实货架。
+- 力导向布局的四个真机缺陷(评估者独立复核后逐条修掉)。
 
 ## [0.2.0] — 2026-09-17
 

package/README.md

@@ -59,13 +59,28 @@ ClearAI does **not** claim recursive self-improvement. It provides the epistemic
 
 ---
 
-## Install
+## Install and use
 
 ```bash
 npx clearai-dsh install
 ```
 
-Restart `dsh web` afterwards (`npx @deepseek-ai/dsh web`), create a session, and pick the **ClearAI** preset. If pnpm is not on PATH: `npm install -g pnpm` (do not `corepack enable` — it installs a version forwarder that may download a pnpm it cannot launch).
+The installer's output follows your system language (`--lang zh|en` overrides it, `doctor` / `seed` / `unseed` take the same flag). Its only runtime dependency is `zod`; the graph stack is bundled into the client half at build time.
+
+Restart `dsh web` afterwards (`npx @deepseek-ai/dsh web`), then **create a session and switch to the `ClearAI` mode in the picker at the top**:
+
+1. Open `dsh web` and click "New session";
+2. Click the current mode name at the top (default: **Standard mode**) to open the preset list;
+3. Pick **ClearAI** — its card reads "利用认识论循环构建可信本体。Build a trustworthy ontology through the epistemic loop.";
+4. Just ask your question. Ordinary Q&A runs as usual; once you set a goal and register hypotheses, the system enters knowledge mode by itself: known facts come to you, gaps stay visible, and conclusions earn their place.
+
+<picture>
+  <img src="docs/shots/zh/jepa-ontology.png" alt="The knowledge graph in ClearAI mode" width="820">
+</picture>
+
+*The ontology graph in ClearAI mode — this real session grew 21 concepts and 9 predicates; the same ledger always yields the same picture. (UI shown is Chinese.)*
+
+If pnpm is not on PATH: `npm install -g pnpm` (do not `corepack enable` — it installs a version forwarder that may download a pnpm it cannot launch).
 
 From the repository:
 
@@ -84,7 +99,19 @@ node docs/diagrams/build-hero.mjs   # redraw the product hero (needs google-chro
 
 The middle column has two switchable views: **Deliverables** and **Ontology**. The right sidebar: **Worldlines** and **External Brain**.
 
-**Ontology** — this view is your knowledge home. At the top, a **graph band**: the ontology graph (what your domain looks like) and the entity graph (what you have actually verified) toggle with one click; clicking a concept node filters the shelves below. Below that, the **ontology shelf**: established entries, each with assertion chips (click to see what the term means), boundary, and support level; contradictions surface automatically. The vocabulary maintenance block sits collapsed at the bottom — it auto-expands when a language exists before any sentence does.
+**Ontology** — this view is your knowledge home. At the top, a **graph band**: the ontology graph (what your domain looks like) and the entity graph (what you have actually verified) toggle with one click; clicking a node or edge opens the **knowledge inspector** (definition / relations / assertions / evidence chain / history), and "filter by this" is an explicit action inside the detail view. Below that, the **ontology shelf**: established entries, each with assertion chips (click to see what the term means), boundary, and support level; contradictions surface automatically. The vocabulary maintenance block sits collapsed at the bottom — it auto-expands when a language exists before any sentence does.
+
+<picture>
+  <img src="docs/shots/zh/jepa-band.png" alt="The graph band: ontology graph and entity graph" width="820">
+</picture>
+
+*The band — the ontology graph and the entity graph share one deterministic projection, so the same ledger always yields the same picture (captured from a real session: 21 concepts, 9 predicates).*
+
+<picture>
+  <img src="docs/shots/zh/jepa-inspector.png" alt="Knowledge inspector: definition, relations, assertions, evidence chain" width="820">
+</picture>
+
+*Open any node or edge: definition, relations, assertions, evidence chain, registration and revision history, all in one place. (UI shown is Chinese.)*
 
 **Worldlines** — when two routes genuinely disagree, they run as separate branches with their own readings; the losing one stays on record, and adoption is a human press.
 
@@ -107,6 +134,7 @@ The middle column has two switchable views: **Deliverables** and **Ontology**. T
 - [Positioning](docs/positioning.md) · [Domain ontology design](docs/domain-ontology.md)
 - [Epistemic loop](docs/epistemic-loop.md) · [Verification ontology](docs/verification-loop.md) · [Loop philosophy](docs/loop-philosophy.md)
 - [Design principles](docs/design-principles.md) · [Soul map](docs/soul-map.md) · [Glossary](docs/glossary.md)
+- [Knowledge-native loop ledger](docs/optimization/knowledge-native-loop.zh-CN.md) (this round: triage / preflight / knowledge gate / graph / inspector; zh-CN)
 - [Development plan](docs/optimization/domain-ontology-plan.md) (with real-run evidence from the Hengtong project)
 - [Known gaps](docs/known-gaps.md) · [Authority map](docs/authority-map.md) · [Release verification](docs/release-verification.md)
 

package/README.zh-CN.md

@@ -44,7 +44,7 @@ ClearAI 是一个**本体发现与探索平台**，核心由两个概念支撑
 | 完成 | 模型宣布完成 | 系统按交付的证据算出来 |
 | 裁决 | 谁做的谁说了算 | 分离——超过一定等级，做的人不能判自己 |
 | 失败 | 删掉、重来、忘掉 | 留下：被推翻的命题是结果，不是噪声 |
-| 沉淀 | 一段聊天记录 | **一个本体**：每条边都通过循环挣得 |
+| 沉淀 | 一段聊天记录 | **一个本体**：本体中的每个关系都有来源和验证记录 |
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/epistemic-loop-hero-dark.zh-CN.png">
@@ -59,13 +59,28 @@ ClearAI **不**声称递归自我改进。它提供的是自我改进系统所
 
 ---
 
-## 安装
+## 安装与使用
 
 ```bash
 npx clearai-dsh install
 ```
 
-装完重启 `dsh web`（`npx @deepseek-ai/dsh web`），新建会话选 **ClearAI** 预设。如果 PATH 上没有 pnpm：`npm install -g pnpm`（别用 `corepack enable`——它装的是版本转发器，可能下载一个自己启动不了的 pnpm）。
+安装侧的输出**跟系统语言走**（`--lang zh|en` 可覆盖；`doctor` / `seed` / `unseed` 同样认这个开关）。运行时依赖只有 `zod`——图谱那套栈在构建期就打进客户端半了。
+
+装完重启 `dsh web`（`npx @deepseek-ai/dsh web`），然后**新建会话，在顶部的模式选择器里切换到 `ClearAI`**：
+
+1. 打开 `dsh web`，点「新建会话」；
+2. 点顶部当前的模式名（默认是「标准模式」），展开预设列表；
+3. 选 **ClearAI**——卡片描述就一句:「利用认识论循环构建可信本体。Build a trustworthy ontology through the epistemic loop.」；
+4. 像平常一样提问。普通问答照常走；一旦你立了目标并登记假设，系统自动进入知识模式：预检把已知送上来，缺口如实读出来，结论过证据才准入。
+
+<picture>
+  <img src="docs/shots/zh/jepa-ontology.png" alt="ClearAI 模式下的知识图谱" width="820">
+</picture>
+
+*ClearAI 模式下的本体图——这场真实会话长出 21 个概念、9 条谓词；同一份账本永远得到同一张图。*
+
+如果 PATH 上没有 pnpm：`npm install -g pnpm`（别用 `corepack enable`——它装的是版本转发器，可能下载一个自己启动不了的 pnpm）。
 
 从仓库开发：
 
@@ -84,7 +99,19 @@ node docs/diagrams/build-hero.mjs   # 重画产品主图(需 google-chrome)
 
 中栏两格可切：**产物**与**本体**。右栏：**世界树**与**外脑**。
 
-**本体**——这一格是你的知识主场。顶部是**图带**：本体图（你的领域长什么样）与实体图（已经验证出了什么）一键切换，点概念节点按概念过滤。下面是**本体货架**：已确立的条目，每条带断言芯片（点开看这个词什么意思）、边界与等级；互相矛盾的自动亮出来。词汇维护区收在最底下——语言先于句子时它自动展开。
+**本体**——这一格是你的知识主场。顶部是**图带**：本体图（你的领域长什么样）与实体图（已经验证出了什么）一键切换；点节点或边打开**知识 Inspector**（定义 / 关系 / 断言 / 证据链 / 历史），「按此过滤」是详情里的显式动作。下面是**本体货架**：已确立的条目，每条带断言芯片（点开看这个词什么意思）、边界与等级；互相矛盾的自动亮出来。词汇维护区收在最底下——语言先于句子时它自动展开。
+
+<picture>
+  <img src="docs/shots/zh/jepa-band.png" alt="本体图带：本体图与实体图切换" width="820">
+</picture>
+
+*图带——本体图与实体图共用同一份确定性投影，同一份账本永远得到同一张图；素材来自一场真实会话（21 概念 · 9 谓词）。*
+
+<picture>
+  <img src="docs/shots/zh/jepa-inspector.png" alt="知识 Inspector：定义、关系、断言、证据链" width="820">
+</picture>
+
+*点开任一节点或边：定义、关系、断言、证据链、登记与修订史，一处读完。*
 
 **世界树**——两条路线真的分歧时，各自独立跑、各自带读数；落选的那条留在记录里，采纳是人按的那一下。
 
@@ -107,6 +134,7 @@ node docs/diagrams/build-hero.mjs   # 重画产品主图(需 google-chrome)
 - [定位](docs/positioning.zh-CN.md) · [领域本体设计](docs/domain-ontology.zh-CN.md)
 - [认识论循环](docs/epistemic-loop.zh-CN.md) · [验证本体](docs/verification-loop.zh-CN.md) · [循环哲学](docs/loop-philosophy.zh-CN.md)
 - [设计原则](docs/design-principles.zh-CN.md) · [灵魂映射](docs/soul-map.zh-CN.md) · [术语表](docs/glossary.zh-CN.md)
+- [知识原生循环执行账本](docs/optimization/knowledge-native-loop.zh-CN.md)（本轮：分诊 / 预检 / 知识门 / 图 / Inspector）
 - [开发计划](docs/optimization/domain-ontology-plan.zh-CN.md)（含亨通真跑读数）
 - [已知缺口](docs/known-gaps.zh-CN.md) · [权威归属](docs/authority-map.zh-CN.md) · [发布验收](docs/release-verification.zh-CN.md)
 

package/bin/clearai.mjs

@@ -44,6 +44,143 @@ const value = (name, fallback) => {
 }
 const profile = value('profile', 'web')
 
+/**
+ * 语言:**跟系统走,不猜**。
+ *
+ * 判据顺序:`--lang zh|en` > `CLEARAI_LANG` > `LC_ALL` / `LC_MESSAGES` / `LANG` > ICU 的默认 locale。
+ * `C` / `POSIX` 是「没有语言信息」,按英文处理(它们是 CI 与最小容器的默认值,不代表中文)。
+ * 为什么认不出来时说英文:这是发给陌生人的第一条命令输出,不该假设对方读中文。
+ * 两边的文案**并排放在一张表里**——同一句话的两个版本挨着,改的时候不会只改一边。
+ */
+const lang = (() => {
+	const candidates = [value('lang', null), process.env.CLEARAI_LANG, process.env.LC_ALL, process.env.LC_MESSAGES, process.env.LANG, Intl.DateTimeFormat().resolvedOptions().locale]
+	for (const candidate of candidates) {
+		if (typeof candidate !== 'string' || candidate === '') continue
+		const tag = candidate.toLowerCase()
+		if (tag.startsWith('zh')) return 'zh'
+		if (tag === 'c' || tag === 'posix' || tag.startsWith('en')) return 'en'
+	}
+	return 'en'
+})()
+
+const TEXT = {
+	zh: {
+		pkgDir: '包目录        ',
+		presetSrc: '预设源        ',
+		presetOk: '(agent.cordis.yml ✓)',
+		presetMissing: '(缺 agent.cordis.yml ✗)',
+		dshHome: 'DSH_HOME      ',
+		userRoot: '用户根        ',
+		rosterVisible: '✓ 名册看得见',
+		rosterAbsent: '✗ 还没有(用 seed 播种,或把 root-yaml 那一行粘进 profile)',
+		shadowCopy: '  ⚠️ 影子副本     {path} 与包里的那份**不一致**,而它被包的 root 遮住、永远不会被读到(自检却会优先读它)。删掉它,或用它来承载你自己的改动并换一个 id。',
+		profileRow: 'profile       ',
+		profileAbsent: '(不存在:先跑一次 dsh --profile {profile})',
+		composeRow: '组合          ',
+		composeUnreachable: '(问不到:dsh 不可用或超时 —— 下面两条无法判定)',
+		hostRow: '宿主行        ',
+		hostIn: '在组合里 ✓',
+		hostOut: '不在组合里(先 dsh plugin --profile {profile} add <本包>)',
+		rosterRootRow: '名册 root     ',
+		rosterNoRoots: '组合里没看到 roots(这个部署可能不挂名册)',
+		rosterExpr: '{expr}(dump 打的是表达式原文,求值在装载时)',
+		seedLedgerRow: '播种记账      ',
+		ledgerEmpty: '(空)',
+		ledgerCount: '{count} 个条目 · {path}',
+		doctorHint: '\n提示:doctor 只读;它不会替你改 profile,也不会替你播种。',
+		installHeader: '【安装】{name}@{version}',
+		installWhat: '装什么      ',
+		installWhere: '装到哪      ',
+		installWho: '谁来跑      ',
+		hostRowShort: '宿主行      ',
+		sourceSpec: '你给的 spec',
+		sourceTarball: '本地 tarball',
+		sourceDir: '本地目录',
+		sourceRegistry: 'registry',
+		routeNpx: 'npx --yes @deepseek-ai/dsh(PATH 上没有 dsh)',
+		pnpmMissing: '\n✗ PATH 上没有 pnpm,而 DSH 管理一个 profile 就是靠它:`dsh plugin …` 把参数转发给 pnpm。\n  装一个再来:npm install -g pnpm(或用系统包管理器,如 brew install pnpm)。\n  别用 corepack enable 抄近路 —— 它装的是版本**转发器**而不是 pnpm,而当前 Node 自带的\n  那份 corepack 可能下载一个它自己启动不了的 pnpm。\n  这里刻意不手工改 profile:那等于把宿主的 reconcile 抄成第二份实现,与宿主漂移时坏的是你的部署。',
+		installFailed: '\n✗ 安装失败:见上面的输出。',
+		hostUnknown: '(问不到组合:CLI 不可用或超时 —— 装没装进去,从这里确认不了;用 doctor 再看)',
+		hostAbsent: '**不在组合里** —— 装是装上了,但组合里没看到它(用 doctor 查)',
+		nextStep: '\n  下一步      重启 dsh web(两半都在进程里按模块 URL 缓存,只刷新浏览器不够),然后在预设选择器里选 ClearAI。',
+		uninstall: '  卸载        dsh plugin --profile {profile} remove {name}(同样可以冠 npx)',
+		rootYamlComment1: '# ClearAI 预设的 root(由 clearai-dsh 的 bin 打印,路径已算成绝对路径)',
+		rootYamlComment2: '    # ⚠️ 补丁层会**替换整份 config**:下面这些键必须与你部署里那份一致,否则会丢。',
+		rootYamlComment3: '    #    先 `dsh --profile <p> --dump-config | grep -A 20 agent-presets` 看一眼当前值再粘。',
+		noPresetInPackage: '✗ 包里没有预设:{path}',
+		seededTo: '  播种到        {dest}',
+		seedCounts: '  新增 {seeded} · 刷新 {refreshed}',
+		seedDrifted: ' · **你改过、没覆盖** {count}({list})',
+		seedNext: '  下一步:重启 dsh(或刷新页面)后,预设选择器里应出现「ClearAI」。',
+		noSeedLedger: '  没有播种记账:什么都不做(不知道哪些是我们播的,就不删)。',
+		unseedRemoved: '  删掉 {count} 个「我们播的、没被改过」的文件',
+		unseedKept: '  **保留** {count} 个你改过的文件(它们现在是你的):{list}',
+		unknownCommand: 'unknown command: {command}',
+		usage: '用法:clearai-dsh [doctor|install|root-yaml|seed|unseed] [--profile web] [--home <dir>] [--lang zh|en]\n     install 还可以:--dist <dir> | --tarball <tgz> | --spec <spec>',
+	},
+	en: {
+		pkgDir: 'package       ',
+		presetSrc: 'preset src    ',
+		presetOk: '(agent.cordis.yml ✓)',
+		presetMissing: '(no agent.cordis.yml ✗)',
+		dshHome: 'DSH_HOME      ',
+		userRoot: 'user root     ',
+		rosterVisible: '✓ visible to the roster',
+		rosterAbsent: '✗ not there yet (seed it, or paste the root-yaml line into the profile)',
+		shadowCopy: '  ⚠️ shadow copy  {path} differs from the copy in the package, and the package root shadows it — it will never be read (while the self-check reads it first). Delete it, or keep your changes there under a different id.',
+		profileRow: 'profile       ',
+		profileAbsent: '(does not exist yet: run dsh --profile {profile} once)',
+		composeRow: 'composition   ',
+		composeUnreachable: '(could not ask: dsh unavailable or timed out — the next two rows cannot be decided)',
+		hostRow: 'host row      ',
+		hostIn: 'is in the composition ✓',
+		hostOut: 'is NOT in the composition (run dsh plugin --profile {profile} add <this package>)',
+		rosterRootRow: 'roster root   ',
+		rosterNoRoots: 'no roots in the composition (this deployment may not mount the roster)',
+		rosterExpr: '{expr}(the dump prints the expression verbatim; it is evaluated at load time)',
+		seedLedgerRow: 'seed ledger   ',
+		ledgerEmpty: '(empty)',
+		ledgerCount: '{count} entries · {path}',
+		doctorHint: '\ndoctor only reads. It will not change your profile and will not seed anything for you.',
+		installHeader: '[install] {name}@{version}',
+		installWhat: 'what        ',
+		installWhere: 'where       ',
+		installWho: 'who runs it ',
+		hostRowShort: 'host row    ',
+		sourceSpec: 'the spec you gave',
+		sourceTarball: 'local tarball',
+		sourceDir: 'local directory',
+		sourceRegistry: 'registry',
+		routeNpx: 'npx --yes @deepseek-ai/dsh (no dsh on PATH)',
+		pnpmMissing: '\n✗ pnpm is not on PATH, and it is how DSH manages a profile: `dsh plugin …` forwards to it.\n  Install one and come back: npm install -g pnpm (or your package manager, e.g. brew install pnpm).\n  Do not take the corepack enable shortcut — that installs a version *forwarder*, not pnpm, and the\n  corepack bundled with current Node may fetch a pnpm it is unable to launch.\n  This verb deliberately does not edit the profile by hand: that would be a second implementation of the host\'s reconcile, and yours is the deployment that breaks when it drifts.',
+		installFailed: '\n✗ install failed: see the output above.',
+		hostUnknown: '(could not ask the composition: CLI unavailable or timed out — whether it landed cannot be decided here; run doctor)',
+		hostAbsent: '**NOT in the composition** — it installed, but the composition does not show it (run doctor)',
+		nextStep: '\n  next        restart dsh web (both halves are cached in the running process by module URL, so a browser refresh is not enough), then pick ClearAI in the preset picker.',
+		uninstall: '  uninstall   dsh plugin --profile {profile} remove {name}(npx works too)',
+		rootYamlComment1: '# ClearAI preset root (printed by clearai-dsh; the path is already absolute)',
+		rootYamlComment2: '    # ⚠️ a patch layer **replaces the whole config**: these keys must match the ones in your deployment, or they are lost.',
+		rootYamlComment3: '    #    Run `dsh --profile <p> --dump-config | grep -A 20 agent-presets` first and paste over the current values.',
+		noPresetInPackage: '✗ no preset in the package: {path}',
+		seededTo: '  seeded to   {dest}',
+		seedCounts: '  added {seeded} · refreshed {refreshed}',
+		seedDrifted: ' · **kept your edits** {count}({list})',
+		seedNext: '  next: restart dsh (or refresh the page) — ClearAI should now appear in the preset picker.',
+		noSeedLedger: '  nothing was seeded: doing nothing (without the ledger there is no way to tell which files are ours, so nothing is deleted).',
+		unseedRemoved: '  removed {count} file(s) we seeded and you did not edit',
+		unseedKept: '  **kept** {count} file(s) you edited (they are yours now): {list}',
+		unknownCommand: 'unknown command: {command}',
+		usage: 'usage: clearai-dsh [doctor|install|root-yaml|seed|unseed] [--profile web] [--home <dir>] [--lang zh|en]\n       install also takes: --dist <dir> | --tarball <tgz> | --spec <spec>',
+	},
+}
+
+/** `{name}` 是占位符;需要拼计数与列表的句子写成函数(见 doctor / seed / unseed)。 */
+function t(key, params) {
+	const text = TEXT[lang][key] ?? TEXT.zh[key]
+	if (text === undefined) throw new Error(`missing text: ${key}`)
+	return typeof text === 'function' ? text(params ?? {}) : text.replace(/\{(\w+)\}/g, (_, name) => String(params?.[name] ?? ''))
+}
+
 /** 递归列出文件(相对路径 → sha256 前 16 位)。只为记账,不为校验完整性。 */
 function hashTree(root) {
 	const out = {}
@@ -128,14 +265,14 @@ function composeQuery(profileName, env) {
 
 function doctor() {
 	const rows = []
-	rows.push(`包目录        ${PKG_DIR}`)
-	rows.push(`预设源        ${PRESET_SRC}${existsSync(join(PRESET_SRC, 'agent.cordis.yml')) ? '(agent.cordis.yml ✓)' : '(缺 agent.cordis.yml ✗)'}`)
-	rows.push(`DSH_HOME      ${DSH_HOME}`)
+	rows.push(`${t('pkgDir')}${PKG_DIR}`)
+	rows.push(`${t('presetSrc')}${PRESET_SRC}${existsSync(join(PRESET_SRC, 'agent.cordis.yml')) ? t('presetOk') : t('presetMissing')}`)
+	rows.push(`${t('dshHome')}${DSH_HOME}`)
 	const roots = rosterRoots()
 	for (const root of roots) {
 		const dir = join(root, PRESET_ID)
 		const present = existsSync(join(dir, 'agent.cordis.yml'))
-		rows.push(`用户根        ${dir} ${present ? '✓ 名册看得见' : '✗ 还没有(用 seed 播种,或把 root-yaml 那一行粘进 profile)'}`)
+		rows.push(`${t('userRoot')}${dir} ${present ? t('rosterVisible') : t('rosterAbsent')}`)
 		/**
 		 * 用户根里那份**会不会被包的 root 遮住**。
 		 *
@@ -152,10 +289,10 @@ function doctor() {
 		} catch {
 			same = false
 		}
-		if (!same) rows.push(`  ⚠️ 影子副本     ${theirs} 与包里的那份**不一致**,而它被包的 root 遮住、永远不会被读到(自检却会优先读它)。删掉它,或用它来承载你自己的改动并换一个 id。`)
+		if (!same) rows.push(t('shadowCopy', { path: theirs }))
 	}
 	const profileDir = join(DSH_HOME, 'profiles', profile)
-	rows.push(`profile       ${profileDir}${existsSync(profileDir) ? '' : '(不存在:先跑一次 dsh --profile ' + profile + ')'}`)
+	rows.push(`${t('profileRow')}${profileDir}${existsSync(profileDir) ? '' : t('profileAbsent', { profile })}`)
 	/**
 	 * 宿主行与名册 root **问组合**,不问某个文件(2026-09-11 修:装出来的形态下这两行来自
 	 * **包的补丁层**,不在 profile 的 cordis.patch.yml 里 —— 读文件的写法会误报「还没挂」)。
@@ -163,18 +300,18 @@ function doctor() {
 	 */
 	const composed = composeQuery(profile, { ...process.env, DSH_HOME })
 	if (composed === null) {
-		rows.push('组合          (问不到:dsh 不可用或超时 —— 下面两条无法判定)')
+		rows.push(`${t('composeRow')}${t('composeUnreachable')}`)
 	} else {
 		const rowIds = [...composed.matchAll(/^- id: (\S+)$/gm)].map((match) => match[1])
-		rows.push(`宿主行        ${rowIds.includes('clearai-host') ? '在组合里 ✓' : '不在组合里(先 dsh plugin --profile ' + profile + ' add <本包>)'}`)
+		rows.push(`${t('hostRow')}${rowIds.includes('clearai-host') ? t('hostIn') : t('hostOut', { profile })}`)
 		const roster = /- id: agent-presets[\s\S]{0,600}?\n\s*- path:[^\n]*/.exec(composed)
 		const expr = roster === null ? null : roster[0].split('\n').pop().trim()
-		rows.push(`名册 root     ${expr === null ? '组合里没看到 roots(这个部署可能不挂名册)' : `${expr}(dump 打的是表达式原文,求值在装载时)`}`)
+		rows.push(`${t('rosterRootRow')}${expr === null ? t('rosterNoRoots') : t('rosterExpr', { expr })}`)
 	}
 	const ledger = readLedger()
-	rows.push(`播种记账      ${Object.keys(ledger).length === 0 ? '(空)' : `${Object.keys(ledger).length} 个条目 · ${LEDGER}`}`)
+	rows.push(`${t('seedLedgerRow')}${Object.keys(ledger).length === 0 ? t('ledgerEmpty') : t('ledgerCount', { count: Object.keys(ledger).length, path: LEDGER })}`)
 	for (const row of rows) console.log(`  ${row}`)
-	console.log('\n提示:doctor 只读;它不会替你改 profile,也不会替你播种。')
+	console.log(t('doctorHint'))
 }
 
 /**
@@ -204,28 +341,24 @@ function install() {
 	 * npx 缓存还在。`--dist` / `--tarball` / `--spec` 是给开发与 E2E 用的另一条入口。
 	 */
 	const spec = explicit ?? (tarball !== null ? resolve(tarball) : dist !== null ? `file:${resolve(dist)}` : `${manifest.name}@${manifest.version}`)
-	const source = explicit !== null ? '你给的 spec' : tarball !== null ? '本地 tarball' : dist !== null ? '本地目录' : 'registry'
+	const source = explicit !== null ? t('sourceSpec') : tarball !== null ? t('sourceTarball') : dist !== null ? t('sourceDir') : t('sourceRegistry')
 	/** PATH 上有 `dsh` 就用它;没有就用 npx 取官方 CLI(`--yes`:一键安装不该卡在一个确认提示上)。 */
 	const dshPath = findOnPath('dsh')
-	const route = dshPath === null ? 'npx --yes @deepseek-ai/dsh(PATH 上没有 dsh)' : dshPath
+	const route = dshPath === null ? t('routeNpx') : dshPath
 	/**
 	 * 子进程**继承 stdio**:安装进度、以及 CLI 那句 `initialized profile …` 都如实流到用户眼前;
 	 * 失败时他看到的也是真实报错,而不是我截出来的尾巴。
 	 */
 	const dsh = (args) => (dshPath === null ? spawnSync('npx', ['--yes', '@deepseek-ai/dsh', ...args], { env, stdio: 'inherit', timeout: 900000 }) : spawnSync(dshPath, args, { env, stdio: 'inherit', timeout: 900000 }))
 
-	console.log(`【安装】${manifest.name}@${manifest.version}`)
-	console.log(`  装什么      ${spec}(${source})`)
-	console.log(`  装到哪      ${profileDir}`)
-	console.log(`  谁来跑      ${route}`)
+	console.log(t('installHeader', { name: manifest.name, version: manifest.version }))
+	console.log(`  ${t('installWhat')}${spec}(${source})`)
+	console.log(`  ${t('installWhere')}${profileDir}`)
+	console.log(`  ${t('installWho')}${route}`)
 
 	const pnpmPath = findOnPath('pnpm')
 	if (pnpmPath === null) {
-		console.error('\n✗ PATH 上没有 pnpm,而 DSH 管理一个 profile 就是靠它:`dsh plugin …` 把参数转发给 pnpm。')
-		console.error('  装一个再来:npm install -g pnpm(或用系统包管理器,如 brew install pnpm)。')
-		console.error('  别用 corepack enable 抄近路 —— 它装的是版本**转发器**而不是 pnpm,而当前 Node 自带的')
-		console.error('  那份 corepack 可能下载一个它自己启动不了的 pnpm。')
-		console.error('  这里刻意不手工改 profile:那等于把宿主的 reconcile 抄成第二份实现,与宿主漂移时坏的是你的部署。')
+		console.error(t('pnpmMissing'))
 		process.exit(1)
 	}
 
@@ -238,28 +371,28 @@ function install() {
 	 */
 	const added = dsh(['plugin', '--profile', profile, 'add', spec])
 	if (added.status !== 0) {
-		console.error('\n✗ 安装失败:见上面的输出。')
+		console.error(t('installFailed'))
 		process.exit(1)
 	}
 
 	const composed = composeQuery(profile, env)
 	if (composed === null) {
-		console.log('  宿主行      (问不到组合:CLI 不可用或超时 —— 装没装进去,从这里确认不了;用 doctor 再看)')
+		console.log(`  ${t('hostRowShort')}${t('hostUnknown')}`)
 	} else {
 		const inCompose = /^- id: clearai-host$/m.test(composed)
-		console.log(`  宿主行      ${inCompose ? '在组合里 ✓' : '**不在组合里** —— 装是装上了,但组合里没看到它(用 doctor 查)'}`)
+		console.log(`  ${t('hostRowShort')}${inCompose ? t('hostIn') : t('hostAbsent')}`)
 	}
-	console.log('\n  下一步      重启 dsh web(两半都在进程里按模块 URL 缓存,只刷新浏览器不够),然后在预设选择器里选 ClearAI。')
-	console.log(`  卸载        dsh plugin --profile ${profile} remove ${manifest.name}(同样可以冠 npx)`)
+	console.log(t('nextStep'))
+	console.log(t('uninstall', { profile, name: manifest.name }))
 }
 
 function rootYaml() {
 	const line = [
-		'# ClearAI 预设的 root(由 clearai-dsh 的 bin 打印,路径已算成绝对路径)',
+		t('rootYamlComment1'),
 		'- id: \'@deepseek-ai/dsh-agent-presets\'',
 		'  config:',
-		'    # ⚠️ 补丁层会**替换整份 config**:下面这些键必须与你部署里那份一致,否则会丢。',
-		'    #    先 `dsh --profile <p> --dump-config | grep -A 20 agent-presets` 看一眼当前值再粘。',
+		t('rootYamlComment2'),
+		t('rootYamlComment3'),
 		'    default: standard',
 		'    includeShippedRoot: true',
 		'    includeUserRoot: true',
@@ -272,7 +405,7 @@ function rootYaml() {
 
 function seed() {
 	if (!existsSync(join(PRESET_SRC, 'agent.cordis.yml'))) {
-		console.error(`✗ 包里没有预设:${PRESET_SRC}`)
+		console.error(t('noPresetInPackage', { path: PRESET_SRC }))
 		process.exit(1)
 	}
 	const root = value('root', rosterRoots()[0])
@@ -303,16 +436,16 @@ function seed() {
 	}
 	before[PRESET_ID] = { files: next, at: new Date().toISOString(), dest }
 	writeLedger(before)
-	console.log(`  播种到        ${dest}`)
-	console.log(`  新增 ${seeded.length} · 刷新 ${refreshed.length}${drifted.length === 0 ? '' : ` · **你改过、没覆盖** ${drifted.length}(${drifted.slice(0, 5).join('、')})`}`)
-	console.log('  下一步:重启 dsh(或刷新页面)后,预设选择器里应出现「ClearAI」。')
+	console.log(t('seededTo', { dest }))
+	console.log(`${t('seedCounts', { seeded: seeded.length, refreshed: refreshed.length })}${drifted.length === 0 ? '' : t('seedDrifted', { count: drifted.length, list: drifted.slice(0, 5).join(lang === 'zh' ? '、' : ', ') })}`)
+	console.log(t('seedNext'))
 }
 
 function unseed() {
 	const ledger = readLedger()
 	const entry = ledger[PRESET_ID]
 	if (entry === undefined) {
-		console.log('  没有播种记账:什么都不做(不知道哪些是我们播的,就不删)。')
+		console.log(t('noSeedLedger'))
 		return
 	}
 	const dest = entry.dest ?? join(rosterRoots()[0], PRESET_ID)
@@ -331,8 +464,8 @@ function unseed() {
 	}
 	delete ledger[PRESET_ID]
 	writeLedger(ledger)
-	console.log(`  删掉 ${removed.length} 个「我们播的、没被改过」的文件`)
-	if (kept.length > 0) console.log(`  **保留** ${kept.length} 个你改过的文件(它们现在是你的):${kept.slice(0, 5).join('、')}`)
+	console.log(t('unseedRemoved', { count: removed.length }))
+	if (kept.length > 0) console.log(t('unseedKept', { count: kept.length, list: kept.slice(0, 5).join(lang === 'zh' ? '、' : ', ') }))
 	// 空目录收掉(只收我们知道的那些;非空绝不动)
 	try {
 		if (existsSync(dest) && readdirSync(dest).length === 0) rmSync(dest, { recursive: true })
@@ -348,10 +481,6 @@ else if (command === 'seed') seed()
 else if (command === 'unseed') unseed()
 else if (command === 'version' || flag('version')) console.log(JSON.parse(readFileSync(join(PKG_DIR, 'package.json'), 'utf8')).version)
 else {
-	console.error(
-		`unknown command: ${command}\n` +
-			'用法:clearai-dsh [doctor|install|root-yaml|seed|unseed] [--profile web] [--home <dir>]\n' +
-			'     install 还可以:--dist <dir> | --tarball <tgz> | --spec <spec>',
-	)
+	console.error(`${t('unknownCommand', { command })}\n${t('usage')}`)
 	process.exit(2)
 }