clearai-dsh 0.1.0

package/bin/clearai.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * clearai-dsh 的安装侧工具:**只做三件事,而且都不改别人的东西**。
+ *
+ * 分包的三样东西落在三个平面:
+ *   · 宿主半(`lib/host.js`)—— 由包自带的 `cordis.patch.yml` 在 profile 层插一行,`dsh plugin add` 自动生效;
+ *   · 浏览器半(`lib/client.js`)—— 同一份清单里的 `dsh.client`,浏览器 Loader 自己扫;
+ *   · agent 预设(`presets/clearai/`)—— **名册(roster)只从 root 目录扫**,包没法直接声明,
+ *     所以要么把 root 指进包里,要么把它播种到用户根。这一件就是本工具存在的理由。
+ *
+ * 三种处理方式(按「原生程度」排序,默认只**打印**不改):
+ *   doctor      看现状:包在哪、预设在哪、名册能不能看见它、探测到的 dsh / profile 是什么
+ *   root-yaml   打印**可以直接粘进 profile 的 `cordis.patch.yml`** 的那一行(路径已算成绝对路径)
+ *   seed        把预设**播种**到用户根 `~/.dsh/.agent-presets/<id>`(带哈希记账:改过的不覆盖)
+ *   unseed      撤掉播种:只删「我们播的、且没被改过」的文件;用户 fork 的 id 一律不碰
+ *
+ * 纪律(与内核播种模板技能同一条):**改过的东西不覆盖,只如实报漂移**;删东西之前先看哈希。
+ * 不改用户的 `cordis.patch.yml` —— 那一行的内容由人自己粘(工具只负责把绝对路径算对)。
+ */
+
+import { createHash } from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const PKG_DIR = resolve(HERE, '..')
+const PRESET_ID = 'clearai'
+const PRESET_SRC = join(PKG_DIR, 'presets', PRESET_ID)
+const DSH_HOME = process.env.DSH_HOME ?? join(homedir(), '.dsh')
+const LEDGER = join(DSH_HOME, '.clearai-dsh.json')
+
+const argv = process.argv.slice(2)
+const command = argv[0] ?? 'doctor'
+const flag = (name) => argv.includes(`--${name}`)
+const value = (name, fallback) => {
+	const index = argv.indexOf(`--${name}`)
+	return index >= 0 && argv[index + 1] !== undefined ? argv[index + 1] : fallback
+}
+const profile = value('profile', 'web')
+
+/** 递归列出文件(相对路径 → sha256 前 16 位)。只为记账,不为校验完整性。 */
+function hashTree(root) {
+	const out = {}
+	const walk = (dir) => {
+		let entries = []
+		try {
+			entries = readdirSync(dir, { withFileTypes: true })
+		} catch {
+			return
+		}
+		for (const entry of entries) {
+			const full = join(dir, entry.name)
+			if (entry.isDirectory()) walk(full)
+			else if (entry.isFile()) out[relative(root, full)] = createHash('sha256').update(readFileSync(full)).digest('hex').slice(0, 16)
+		}
+	}
+	walk(root)
+	return out
+}
+
+function readLedger() {
+	try {
+		const parsed = JSON.parse(readFileSync(LEDGER, 'utf8'))
+		return parsed !== null && typeof parsed === 'object' ? parsed : {}
+	} catch {
+		return {}
+	}
+}
+
+function writeLedger(next) {
+	try {
+		mkdirSync(dirname(LEDGER), { recursive: true })
+		writeFileSync(LEDGER, `${JSON.stringify(next, null, 2)}\n`, 'utf8')
+		return true
+	} catch {
+		return false
+	}
+}
+
+/** 名册会扫哪些 root —— 与 `@deepseek-ai/dsh-agent-presets` 的规则同形(自带 → 配置 → 用户根)。 */
+function rosterRoots() {
+	return [join(DSH_HOME, '.agent-presets')]
+}
+
+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}`)
+	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)'}`)
+	}
+	const profileDir = join(DSH_HOME, 'profiles', profile)
+	rows.push(`profile       ${profileDir}${existsSync(profileDir) ? '' : '(不存在:先跑一次 dsh --profile ' + profile + ')'}`)
+	/**
+	 * 宿主行与名册 root **问组合**,不问某个文件(2026-09-11 修:装出来的形态下这两行来自
+	 * **包的补丁层**,不在 profile 的 cordis.patch.yml 里 —— 读文件的写法会误报「还没挂」)。
+	 * 事实在组合里;问不到就如实说问不到,不猜。
+	 */
+	const composed = (() => {
+		try {
+			return execFileSync('npx', ['--no-install', '@deepseek-ai/dsh', '--profile', profile, '--dump-config'], { encoding: 'utf8', env: { ...process.env, DSH_HOME }, timeout: 120000, stdio: ['ignore', 'pipe', 'ignore'] })
+		} catch {
+			return null
+		}
+	})()
+	if (composed === null) {
+		rows.push('组合          (问不到:dsh 不可用或超时 —— 下面两条无法判定)')
+	} else {
+		const rowIds = [...composed.matchAll(/^- id: (\S+)$/gm)].map((match) => match[1])
+		rows.push(`宿主行        ${rowIds.includes('clearai-host') ? '在组合里 ✓' : '不在组合里(先 dsh plugin --profile ' + profile + ' add <本包>)'}`)
+		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 打的是表达式原文,求值在装载时)`}`)
+	}
+	const ledger = readLedger()
+	rows.push(`播种记账      ${Object.keys(ledger).length === 0 ? '(空)' : `${Object.keys(ledger).length} 个条目 · ${LEDGER}`}`)
+	for (const row of rows) console.log(`  ${row}`)
+	console.log('\n提示:doctor 只读;它不会替你改 profile,也不会替你播种。')
+}
+
+function rootYaml() {
+	const line = [
+		'# ClearAI 预设的 root(由 clearai-dsh 的 bin 打印,路径已算成绝对路径)',
+		'- id: \'@deepseek-ai/dsh-agent-presets\'',
+		'  config:',
+		'    # ⚠️ 补丁层会**替换整份 config**:下面这些键必须与你部署里那份一致,否则会丢。',
+		'    #    先 `dsh --profile <p> --dump-config | grep -A 20 agent-presets` 看一眼当前值再粘。',
+		'    default: standard',
+		'    includeShippedRoot: true',
+		'    includeUserRoot: true',
+		'    roots:',
+		`      - path: '${join(PKG_DIR, 'presets')}'`,
+		'        trust: system',
+	].join('\n')
+	console.log(line)
+}
+
+function seed() {
+	if (!existsSync(join(PRESET_SRC, 'agent.cordis.yml'))) {
+		console.error(`✗ 包里没有预设:${PRESET_SRC}`)
+		process.exit(1)
+	}
+	const root = value('root', rosterRoots()[0])
+	const dest = join(root, PRESET_ID)
+	const next = hashTree(PRESET_SRC)
+	const before = readLedger()
+	const previous = before[PRESET_ID]?.files ?? {}
+	const seeded = []
+	const refreshed = []
+	const drifted = []
+	for (const [rel, hash] of Object.entries(next)) {
+		const target = join(dest, rel)
+		const onDisk = existsSync(target) ? createHash('sha256').update(readFileSync(target)).digest('hex').slice(0, 16) : null
+		if (onDisk === null) {
+			mkdirSync(dirname(target), { recursive: true })
+			cpSync(join(PRESET_SRC, rel), target)
+			seeded.push(rel)
+			continue
+		}
+		if (onDisk === hash) continue
+		// 改过的不覆盖:与内核播种模板技能同一条纪律
+		if (previous[rel] !== undefined && onDisk !== previous[rel]) {
+			drifted.push(rel)
+			continue
+		}
+		cpSync(join(PRESET_SRC, rel), target)
+		refreshed.push(rel)
+	}
+	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」。')
+}
+
+function unseed() {
+	const ledger = readLedger()
+	const entry = ledger[PRESET_ID]
+	if (entry === undefined) {
+		console.log('  没有播种记账:什么都不做(不知道哪些是我们播的,就不删)。')
+		return
+	}
+	const dest = entry.dest ?? join(rosterRoots()[0], PRESET_ID)
+	const removed = []
+	const kept = []
+	for (const [rel, hash] of Object.entries(entry.files ?? {})) {
+		const target = join(dest, rel)
+		if (!existsSync(target)) continue
+		const onDisk = createHash('sha256').update(readFileSync(target)).digest('hex').slice(0, 16)
+		if (onDisk === hash) {
+			rmSync(target)
+			removed.push(rel)
+		} else {
+			kept.push(rel)
+		}
+	}
+	delete ledger[PRESET_ID]
+	writeLedger(ledger)
+	console.log(`  删掉 ${removed.length} 个「我们播的、没被改过」的文件`)
+	if (kept.length > 0) console.log(`  **保留** ${kept.length} 个你改过的文件(它们现在是你的):${kept.slice(0, 5).join('、')}`)
+	// 空目录收掉(只收我们知道的那些;非空绝不动)
+	try {
+		if (existsSync(dest) && readdirSync(dest).length === 0) rmSync(dest, { recursive: true })
+	} catch {
+		/* 收不掉就算了,不影响判定 */
+	}
+}
+
+if (command === 'doctor') doctor()
+else if (command === 'root-yaml') rootYaml()
+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|root-yaml|seed|unseed] [--profile web] [--root <dir>]`)
+	process.exit(2)
+}

package/brand/README.md

@@ -0,0 +1,41 @@
+# ClearAI brand mark
+
+**The mark is one glyph: the opening of a `c`, plus one fact.**
+
+```
+c        = Clear (say it clearly)
+opening  = it does not close — completion passes admission, it is not declared by the model
+solid dot = a fact (the emerald used in the world tree when a branch is adopted)
+```
+
+Three meanings in one shape, nothing spare. That is why it was chosen.
+
+## Files
+
+| File | What it is | Used by |
+|---|---|---|
+| `logo.svg` | **the single master** (1024 grid; the main stroke is `currentColor`) | every bitmap is generated from it |
+| `logo-wordmark.svg` | the wordmark `clearai` (`clear` in ink, `ai` in brand teal); typeset, not outlined | lockups |
+| `logo-lockup.svg` | mark + wordmark, horizontally locked | README, package page, documents |
+| `logo-512.png` · `logo-512-dark.png` | the mark, transparent, ink / inverted | README (light / dark) |
+| `logo-lockup.png` · `logo-lockup-dark.png` | the lockup, ink / inverted | README, npm page |
+| `build-icons.mjs` | **the generator**: master → the four bitmaps above | re-run it after any change to the master |
+
+Bitmaps are never hand-edited: `build-icons.mjs` regenerates the whole set in one command, and a hand-exported file would be a second ledger for the brand.
+
+```bash
+node brand/build-icons.mjs      # needs google-chrome on PATH (headless rasteriser)
+```
+
+## Rules
+
+- **Minimum size 16px.** The 16px column is the only judge; test any new proposal there first.
+- **One source, two themes.** The main stroke is `currentColor`; colour comes from context, so it is never hard-coded in the master.
+- **The dot stays emerald `#10B981`.** It is a product-semantic colour (the world tree's "adopted / settled"), and does not follow the theme.
+- **Do not move the dot back to the centre.** A dot at the centre is © and CircleCI (ring plus centre dot — same structure); our dot sits **in the opening**.
+- **Do not straighten the opening.** An opening pointing due right is just a `c`; angled up-right (centred on −35°) is what makes it recognisable.
+- Backgrounds: light `#FBFAF7` (warm paper) / dark `#1C1A18` (warm ink); brand teal `#3E8E7A`.
+
+## What was removed
+
+Only the chosen brand assets and their generator belong to this repository. The master artwork is the sole source for generated bitmaps; no external archive or prior design process is required to interpret the brand.

package/brand/logo-lockup.svg

@@ -0,0 +1,12 @@
+<!-- 组合标:主标 + 字标(横向锁定;间距 = 主标宽度的 18%) -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1088 240" width="1088" height="240" fill="none">
+  <g transform="translate(0,20) scale(0.1953)">
+  <circle cx="512" cy="512" r="326" stroke="currentColor" stroke-width="118" pathLength="360"
+          stroke-dasharray="270 90" stroke-linecap="round" transform="rotate(10 512 512)"/>
+  <circle cx="792" cy="308" r="104" fill="#10B981"/>
+</g>
+  <g transform="translate(268,0)">
+  <text x="0" y="178" font-family="Helvetica Neue, Helvetica, Arial, 'Liberation Sans', 'DejaVu Sans', sans-serif"
+        font-size="196" font-weight="560" letter-spacing="-7" fill="currentColor">clear<tspan fill="#3E8E7A">ai</tspan></text>
+</g>
+</svg>

package/brand/logo-wordmark.svg

@@ -0,0 +1,6 @@
+<!-- 字标(排版示意;真做要转曲或定制字形):clear 用墨色,ai 用品牌青。
+     它只与主标**组合**使用,不单独当应用图标(16px 下字母没意义)。 -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 240" width="880" height="240" fill="none">
+  <text x="0" y="178" font-family="Helvetica Neue, Helvetica, Arial, 'Liberation Sans', 'DejaVu Sans', sans-serif"
+        font-size="196" font-weight="560" letter-spacing="-7" fill="currentColor">clear<tspan fill="#3E8E7A">ai</tspan></text>
+</svg>

package/brand/logo.svg

@@ -0,0 +1,19 @@
+<!--
+  ClearAI 主标 —— 「c 的开口 + 一颗事实点」(定稿,w2c)。
+
+  为什么长这样(三件语义一个字形):
+    · c        = Clear(说清楚)
+    · 开口     = 不闭合:完成要过观测准入,不由模型宣布(缺口**故意**留在右上,不是正右)
+    · 实心点   = 事实(世界树里「采纳/落定」那枚 emerald)
+
+  结构上与已知标记刻意错开:©(C 在圈里)、CircleCI(环 + **圆心**点)、Coda(C 在方块里)——
+  我们的点**不在圆心**,而在**开口里**;开口**斜朝右上**,不是正右。
+
+  几何(1024 网格):环心线 R=326,笔画 118,开口 90° 以 -35° 为中心;点 r=104,坐在开口的角平分线上。
+  主笔是 currentColor(深浅两版同一份源),点固定 emerald(产品里「采纳/落定」的颜色)。
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" width="1024" height="1024" fill="none">
+  <circle cx="512" cy="512" r="326" stroke="currentColor" stroke-width="118" pathLength="360"
+          stroke-dasharray="270 90" stroke-linecap="round" transform="rotate(10 512 512)"/>
+  <circle cx="792" cy="308" r="104" fill="#10B981"/>
+</svg>

package/cordis.patch.yml

@@ -0,0 +1,39 @@
+# clearai-dsh 的 bundle patch:宿主平面的一行。
+#
+# 为什么宿主半必须在**补丁层**而不是 agent 预设里:
+# 客户端模块扫描只扫宿主 Loader 的行 —— 预设里的行浏览器看不见,面板就长不出来。
+# 而投影单元 `clearai`(把工具写下的变更记录折成视图)也是宿主平面的:它在会话日志上注册一个投影,
+# 多个会话共享同一个注册表。
+#
+# 行名用**包名**(不是文件路径):Loader 从组合自身的 base 解析它,也就是装进 profile 的那份包。
+# 打包纪律④:发行物里不出现任何绝对路径,也不出现仓库结构。
+
+- insert:
+    - id: clearai-host
+      name: 'clearai-dsh'
+
+# 预设(agent.cordis.yml)不在补丁层 —— 它由名册(roster)从 preset root 扫描。
+# 预设的注册方式有三种候选(补丁层重述名册行 / 播种到用户根 / 打印待粘贴的行),
+# 由 S2 的干净 profile 探针决定,不在这里拍脑袋。
+
+# ── 预设的 root:现场算出来,零安装期写入(S2 探针的结论)──────────────────────
+#
+# 名册(roster)只从 **root 目录**扫预设,而后端包没法自己声明一个 root —— 这是整个打包里
+# 唯一没有现成通道的一环。S2 在干净 profile 上把三件事都量过了:
+#   · `!!js` 在**补丁行**里确实会被求值(与自带补丁用 `!!js dshHomePath(...)` 同一条路);
+#   · 但 `baseUrl` 在补丁层里是**profile 目录**,不是本包目录(`resolvedRoots` 实测:
+#     `path:"BASEURL=file:///…/profiles/clearai-test/"`)——所以「拿 baseUrl 当包目录」不成立;
+#   · 而包在 profile 里的位置是**可预测的**:`dsh plugin add` 就是把它装进 profile 的
+#     `node_modules/`。于是 root 可以现场算出来:`<profile>/node_modules/clearai-dsh/presets/`。
+#
+# 于是不需要任何安装期写入(不改用户的文件、不需要 bin 先跑一遍),归属也落在 system 信任层。
+# 想改预设的人仍然有两条路:`clearai-dsh seed`(播种到用户根,可改可回滚)或复制成新 id。
+- id: agent-presets
+  config:
+    # ⚠️ 补丁层替换**整份** config:下面这些键要与部署里那份保持一致(上游将来加字段要跟上)。
+    default: standard
+    includeShippedRoot: true
+    includeUserRoot: true
+    roots:
+      - path: !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('node_modules/clearai-dsh/presets/', baseUrl))"
+        trust: system