docs: 文档改为英文,并修正过时内容
Some checks failed
Tests / test (push) Has been cancelled

不是翻译 —— 多数文档描述的行为已经不存在了。

先修一个更基本的问题:我们不拥有 u-claw.org 域名,那是上游的。所以之前写在
README、诊断包提示、联系方式里的 help@u-claw.org 全都会把用户的问题发给
上游 —— 一个没有理由回复的人。改为指向我们自己的 issue tracker,并加断言
禁止再出现指向该域名的支持入口。

重写(内容过时,不是语言问题):
- install/README.md —— 还写着 10 个中国技能、DeepSeek 优先、国内镜像。
  现在按实际流程写:技能读 manifest、模型菜单 Gemini 优先、bundle 有
  SHA256 校验。并如实写明 curl|bash 在受管企业电脑上会被 EDR 拦。
- CLAUDE.md 的模型配置整节 —— 还在描述虾盘云首选卡片和 12 个 provider,
  那个界面已经换成单框 Key 输入了。
- SECURITY.md —— 安全报告原本指向上游维护者个人邮箱。fork 之后那条路由
  是错的:漏洞会发给写不了这份代码、也修不了的人。
- CONTRIBUTING.md —— 补上 fork 关系、pre-push 钩子怎么装、以及
  `node --test tests/` 为什么不能用。

翻译并保留:
- bootable/README.md、TROUBLESHOOTING.md —— 面向用户,顺带把
  「国内镜像」「小米/华为 BIOS 按键」等换成目标市场的实际情况

HANDOFF.md 重写为一份事故复盘:原文一半是过时的一次性交接笔记(引用的
website/guide.html 已不在本仓库),另一半是 persistence.dat 未格式化导致
启动失败的排查记录 —— 后者有长期价值,尤其是「读 offset 1080 的两字节
验证 ext4」这个判断方法,已同时写进 bootable/README.md。

bootable/IMPROVEMENTS_SUMMARY.md 保留中文,加了说明:它是上游 fork 前的
历史改进记录,没人引用,描述的是已完成的工作而非当前行为。翻译它反而会
让人误以为是现行文档。

新增 skills/en/uclaw-help —— 把「怎么用、东西在哪、出问题怎么办」做成
内置知识,每个角色都装。方案 C10.8:能问的产品才是不需要学的产品。
This commit is contained in:
2026-08-17 19:12:07 +08:00
parent 46a1218fc8
commit 3221856d50
20 changed files with 937 additions and 883 deletions

View File

@@ -110,11 +110,11 @@ test('install-skills.mjs reads origin.json rather than hardcoding the host', ()
assert.equal(fallback, origin.urls.rawTemplate, 'the fallback template disagrees with origin.json');
});
test('every u-claw.org address in the tree is one origin.json accounts for', () => {
// Not "all the same" — they legitimately differ by role. The point is that no
// address exists that nobody has thought about, because on a fork some of
// these route to the upstream maintainer rather than to us.
const known = new Set(Object.values(origin.support).filter((v) => /@/.test(v)));
test('we do not tell users to email a domain we do not own', () => {
// u-claw.org is the upstream project's domain. Any address on it reaches them,
// not us — so a support line pointing there sends our users' problems to
// someone with no reason to answer.
const OURS = new Set(Object.values(origin.upstream?.addresses ?? {}).filter((v) => /@/.test(v)));
const offenders = [];
for (const file of walk(repoRoot)) {
if (!SCANNED.has(extname(file))) continue;
@@ -122,23 +122,22 @@ test('every u-claw.org address in the tree is one origin.json accounts for', ()
if (rel === 'origin.json' || SKIPPED_FILES.has(rel.split('/').pop())) continue;
readFileSync(file, 'utf8').split(/\r?\n/).forEach((line, i) => {
for (const [found] of line.matchAll(/[\w.+-]+@u-claw\.org/g)) {
if (!known.has(found)) offenders.push(`${rel}:${i + 1} uses ${found}`);
// Upstream's own addresses may appear where the text is about upstream.
if (OURS.has(found)) continue;
offenders.push(`${rel}:${i + 1} offers ${found}, a domain we do not control`);
}
});
}
assert.deepEqual(offenders, [], `addresses origin.json does not account for:\n${offenders.join('\n')}`);
assert.deepEqual(offenders, [], offenders.join('\n'));
});
test('origin.json flags the addresses that still belong to upstream', () => {
// This is the thing that is easy to ship without noticing: a fork whose
// SECURITY.md sends vulnerability reports to someone who did not write the
// code, and cannot fix it.
assert.ok(origin.support.note, 'origin.json should say which addresses are not ours yet');
assert.match(origin.support.note, /security/i);
const security = readFileSync(join(repoRoot, 'SECURITY.md'), 'utf8');
test('support routes somewhere we actually control', () => {
assert.match(origin.support.issues, /^https:\/\//, 'there has to be a working support route');
assert.ok(
security.includes(origin.support.security),
'SECURITY.md and origin.json disagree about where to report a vulnerability',
origin.support.issues.includes(origin.repo.host),
'support should point at our own host, not the upstream project',
);
// Until we have an address of our own, saying so beats leaving a stale one.
assert.ok('email' in origin.support, 'origin.json should record whether we have an address yet');
assert.match(origin.support.note, /do not own u-claw\.org/i);
});

View File

@@ -135,6 +135,11 @@ test('startup heals before it complains, and never dead-ends', () => {
assert.match(start, /start\.diagnostics_written/, 'the user should be told where the report is');
const en = JSON.parse(readFileSync(join(repoRoot, 'portable', 'lib', 'messages', 'en.json'), 'utf8'));
assert.match(en['start.diagnostics_hint'], /help@u-claw\.org/, 'the report needs somewhere to go');
const origin = JSON.parse(readFileSync(join(repoRoot, 'origin.json'), 'utf8'));
// A report with nowhere to go is just a file on a drive.
assert.ok(
en['start.diagnostics_hint'].includes(origin.support.issues),
'the report should point at the support route origin.json declares',
);
assert.match(en['start.diagnostics_hint'], /removed/i, 'say that keys were stripped, or nobody will send it');
});

View File

@@ -145,7 +145,7 @@ test('message catalogues have no untranslated leftovers', () => {
assert.deepEqual(extra, [], `zh-CN.json has keys English does not: ${extra.join(', ')}`);
// Product names and technical identifiers are the same in every language.
// Everything else being identical means a string was copied, not translated.
const NOT_TRANSLATED_BY_DESIGN = new Set(['start.node_version']);
const NOT_TRANSLATED_BY_DESIGN = new Set(['start.node_version', 'cat.uclaw']);
const identical = Object.keys(en).filter(
(key) =>
!NOT_TRANSLATED_BY_DESIGN.has(key) &&