feat: 完成首次贡献指南及三项任务修复

[masher-pp]

本次PR完成了三项任务修复和贡献指南的文档改进：

1. fix: 版本更新通知设计杂乱 #1005 - 优化了Windows版本更新通知的UI设计
2. fix: 欢迎页语言切换器无效 #448 - 修复了语言切换器的race condition问题
3. fix: 更新通知横幅遮挡侧边栏 #859 - 调整了更新横幅位置避免遮挡
4. docs: 在README中添加贡献指南提示 - 引导用户查看贡献指南

影响范围：

• Desktop app (Electron shell)
• Web dashboard (React UI)
• Documentation

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR introduces a substantial new controller runtime/API layer (Hono + OpenAPI routes), runtime orchestration helpers for OpenClaw (health/sync/auth profiles/plugin/config writers), and adds/updates repo-level documentation and GitHub automation files.

Changes:

• Add a new apps/controller service with runtime state tracking, health/sync loops, proxy-aware fetch, and multiple API route modules.
• Add OpenClaw runtime writers (config, plugins, auth profiles, model state, credit-guard state) and supporting utilities (URL resolution, path helpers).
• Add/expand repository docs and automation (SECURITY/CONTRIBUTING/CODE_OF_CONDUCT/ARCHITECTURE, GitHub workflows/templates, editor settings).

Reviewed changes

Copilot reviewed 98 out of 1332 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
apps/controller/src/runtime/state.ts	Adds runtime state types, initializer, and aggregate status recomputation.
apps/controller/src/runtime/runtime-health.ts	Adds gateway health probing via proxy-aware fetch.
apps/controller/src/runtime/openclaw-watch-trigger.ts	Adds filesystem “touch” triggers for config/skill watch reloads.
apps/controller/src/runtime/openclaw-runtime-plugin-writer.ts	Ensures runtime plugins are materialized into extensions dir.
apps/controller/src/runtime/openclaw-runtime-model-writer.ts	Writes authoritative runtime model state JSON.
apps/controller/src/runtime/openclaw-gateway-url.ts	Adds helpers to resolve HTTP/WS gateway URLs.
apps/controller/src/runtime/openclaw-config-writer.ts	Writes OpenClaw config, de-dupes writes, syncs weixin account index.
apps/controller/src/runtime/openclaw-auth-profiles-writer.ts	Writes/merges auth profiles for agent workspaces.
apps/controller/src/runtime/openclaw-auth-profiles-store.ts	Adds auth profiles store with serialized per-file update queue and OAuth connection state aggregation.
apps/controller/src/runtime/loops.ts	Adds sync/health/analytics background loops and status updates.
apps/controller/src/runtime/gateway-client.ts	Adds thin JSON client wrapper over proxy-aware fetch.
apps/controller/src/runtime/credit-guard-state-writer.ts	Writes desktop locale state for credit guard.
apps/controller/src/routes/workspace-template-routes.ts	Adds workspace template list/snapshot/upsert routes.
apps/controller/src/routes/user-routes.ts	Adds /me profile and auth-source routes.
apps/controller/src/routes/session-routes.ts	Adds internal session create/update and public session list/details/history/delete routes.
apps/controller/src/routes/runtime-config-routes.ts	Adds get/set runtime config endpoints.
apps/controller/src/routes/provider-oauth-routes.ts	Adds provider OAuth start/status/provider-status/disconnect endpoints.
apps/controller/src/routes/model-routes.ts	Adds model/provider registry/config/validate and quota fallback routes.
apps/controller/src/routes/integration-routes.ts	Adds integration list/connect/refresh/delete routes.
apps/controller/src/routes/desktop-routes.ts	Adds desktop internal routes including shell-open/ready/fallback events/preferences + compaction notify endpoint.
apps/controller/src/routes/desktop-rewards-routes.ts	Adds desktop rewards status/session/claim/set-balance routes.
apps/controller/src/routes/bot-routes.ts	Adds bot CRUD + pause/resume endpoints.
apps/controller/src/routes/artifact-routes.ts	Adds artifact CRUD/list/stats endpoints.
apps/controller/src/lib/v8-coverage.ts	Adds optional v8 coverage flush for desktop e2e.
apps/controller/src/lib/secrets.ts	Adds secret presence check + redaction helper.
apps/controller/src/lib/proxy-fetch.ts	Adds proxy-aware fetch with NO_PROXY merging, timeouts, and safe error redaction.
apps/controller/src/lib/provider-base-url.ts	Adds base URL normalization helper.
apps/controller/src/lib/path-utils.ts	Adds home expansion and relative child path validation helper.
apps/controller/src/lib/openclaw-config-serialization.ts	Adds deterministic OpenClaw config normalization/serialization.
apps/controller/src/lib/model-provider-runtime.ts	Adds runtime descriptors + model ref building/parsing helpers.
apps/controller/src/lib/managed-models.ts	Adds managed cloud model resolver + predicate.
apps/controller/src/lib/logger.ts	Adds structured JSON logger.
apps/controller/src/lib/channel-connect-error.ts	Adds typed ChannelConnectError helper.
apps/controller/src/index.ts	Adds controller entrypoint w/ graceful shutdown and optional coverage flush.
apps/controller/src/app/env.ts	Adds env loading/parsing with workspace-root .env support.
apps/controller/src/app/create-app.ts	Adds Hono app wiring, CORS, route registration, and /health endpoint.
apps/controller/src/app/container.ts	Adds DI container wiring for controller services and runtime subsystems.
apps/controller/src/app/bootstrap.ts	Adds controller bootstrap sequence and WS/run-loop wiring.
apps/controller/scripts/generate-openapi.ts	Adds script to generate OpenAPI doc JSON from app routes.
apps/controller/scripts/bundle-runtime-plugins.mjs	Adds script to bundle runtime plugins + dependencies into .dist-runtime.
apps/controller/package.json	Adds controller package scripts/deps.
apps/controller/.env.example	Adds controller env example + GitHub token note.
SECURITY.md	Adds security policy and reporting instructions (EN/zh).
LICENSE	Adds MIT license file.
CONTRIBUTING.md	Adds comprehensive contributing guide (EN) + links.
CODE_OF_CONDUCT.md	Adds Contributor Covenant CoC.
CLAUDE.md	Adds pointer to AGENTS instructions file.
ARCHITECTURE.md	Adds architecture overview doc.
.well-known/bothub-verify.txt	Adds verification token file.
.vscode/settings.json	Adds markdown paste image path setting.
.vscode/extensions.json	Recommends markdown paste image extension.
.vaunt/config.yml	Adds Vaunt achievements configuration.
.npmrc	Adds npm config (shamefully-hoist=true).
.nexu-dev/skills/nano-banana/scripts/file-upload.js	Adds Gemini Files API upload/list/get/delete helper script.
.github/workflows/nexu-pal-triage-command.yml	Adds workflow to process triage commands on issue comments.
.github/workflows/nexu-pal-needs-triage-notify.yml	Adds workflow to notify on needs-triage label.
.github/workflows/nexu-pal-issue-opened.yml	Adds workflow to welcome + auto-process new issues.
.github/workflows/github-metrics.yml	Adds daily GitHub metrics SVG generation workflow.
.github/workflows/feishu-pr-notify.yml	Adds Feishu notification for fork PR opens.
.github/workflows/feishu-issue-notify.yml	Adds Feishu notification for new issues.
.github/workflows/feishu-discussion-notify.yml	Adds Feishu notification for new discussions.
.github/workflows/docs-ci.yml	Adds docs build workflow with change detection.
.github/workflows/desktop-prepare-release.yml	Adds desktop release PR preparation workflow.
.github/workflows/desktop-ci-dist-lite.yml	Adds macOS dist-lite desktop CI workflow.
.github/workflows/desktop-ci-dev.yml	Adds desktop dev CI workflow (macOS + Windows).
.github/workflows/desktop-beta.yml	Adds scheduled/manual desktop beta build + publish pipeline.
.github/workflows/desktop-auto-tag.yml	Adds auto-tag + release creation on release PR merge.
.github/workflows/ci.yml	Adds CI workflow (typecheck/lint/test/build/lockfile/esm checks).
.github/workflows/cancel-closed-pr-desktop-e2e.yml	Adds workflow to cancel stale desktop e2e runs when PR closes.
.github/pull_request_template.md	Adds PR template.
.github/ISSUE_TEMPLATE/improvement.yml	Adds improvement issue template.
.github/ISSUE_TEMPLATE/feature_request.yml	Adds feature request issue template.
.github/ISSUE_TEMPLATE/config.yml	Configures issue templates + disables blank issues.
.github/ISSUE_TEMPLATE/bug_report.yml	Adds bug report template.
.github/CODEOWNERS	Adds CODEOWNERS entry.
.gitattributes	Adds default LF normalization + Windows script CRLF rules.
.dockerignore	Adds docker ignore patterns.
.agents/skills/process-pr-reviews/SKILL.md	Adds skill doc for processing PR reviews.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The PR description is focused on three UI fixes (Windows update notification UI, welcome page language switcher, update banner layout) plus a README contribution-guide hint, but the diff primarily adds a large new controller service (runtime orchestration, API routes, scripts, workflows, and multiple repo governance docs). Please update the PR description to match the actual scope, or split this into smaller PRs aligned to the stated fixes to keep review/rollback risk manageable.

[Copilot]

As written, getOAuthConnectionState() only recognizes providers that exist in OAUTH_PROVIDER_ID_MAP. If typed.provider is already canonical (e.g. "openai"), providerId becomes undefined and the connection is ignored. Consider mapping via OAUTH_PROVIDER_ID_MAP[provider] ?? provider so unmapped providers still count, while preserving special-case remaps.

[Copilot]

This async sync path uses readdirSync/rmSync, which will block the Node.js event loop while scanning/deleting files. Since this executes during config writes (potentially frequent), prefer fs/promises.readdir + fs/promises.rm (or batch deletes) to avoid blocking controller request handling.

[Copilot]

This async sync path uses readdirSync/rmSync, which will block the Node.js event loop while scanning/deleting files. Since this executes during config writes (potentially frequent), prefer fs/promises.readdir + fs/promises.rm (or batch deletes) to avoid blocking controller request handling.

[Copilot]

The change detection compares mergedIds vs existingIds via JSON.stringify, which is sensitive to ordering and also compares against the unfiltered existingIds (so removing internal IDs will always look like a change). If the goal is: (a) avoid unnecessary writes and (b) keep a stable canonical file, consider normalizing both sides (e.g., filter out internal IDs and sort) before comparing, or compare as sets and write a deterministic sorted list.

Suggested change

	const configIdSet = new Set(accountIds);
	const mergedIds = [
	...new Set([
	...existingIds.filter((id) => configIdSet.has(id)),
	...accountIds,
	]),
	].filter((id) => !id.startsWith(NEXU_INTERNAL_ACCOUNT_PREFIX));
	// Only write if changed
	if (JSON.stringify(mergedIds) === JSON.stringify(existingIds)) {
	return;
	}
	await mkdir(indexDir, { recursive: true });
	await writeFile(indexPath, JSON.stringify(mergedIds, null, 2), "utf8");
	// Remove orphan credential/sync files for accounts no longer in the
	// authoritative set. This prevents listStoredWeixinAccountIds() from
	// resurrecting stale accounts that were removed from config.
	const accountsDir = path.join(indexDir, "accounts");
	try {
	const validIds = new Set(mergedIds);
	const normalizeAccountIds = (ids: string[]): string[] =>
	[...new Set(ids.filter((id) => !id.startsWith(NEXU_INTERNAL_ACCOUNT_PREFIX)))].sort();
	const configIdSet = new Set(accountIds);
	const mergedIds = [
	...new Set([
	...existingIds.filter((id) => configIdSet.has(id)),
	...accountIds,
	]),
	];
	const normalizedExistingIds = normalizeAccountIds(existingIds);
	const normalizedMergedIds = normalizeAccountIds(mergedIds);
	// Only write if changed
	if (
	JSON.stringify(normalizedMergedIds) ===
	JSON.stringify(normalizedExistingIds)
	) {
	return;
	}
	await mkdir(indexDir, { recursive: true });
	await writeFile(indexPath, JSON.stringify(normalizedMergedIds, null, 2), "utf8");
	// Remove orphan credential/sync files for accounts no longer in the
	// authoritative set. This prevents listStoredWeixinAccountIds() from
	// resurrecting stale accounts that were removed from config.
	const accountsDir = path.join(indexDir, "accounts");
	try {
	const validIds = new Set(normalizedMergedIds);

[Copilot]

Using new URL(...).pathname can produce incorrect paths on Windows (leading /, URL decoding issues). Prefer converting the file URL to a real filesystem path (e.g., via fileURLToPath) before writing, so generate-openapi works cross-platform.

[Copilot]

The new proxy/NO_PROXY matching + timeout/abort behavior is non-trivial and security/ops sensitive. Add unit tests covering: (1) mergeNoProxyEntries dedupe + loopback injection, (2) shouldBypassProxy hostname matching edge cases (leading dot, wildcard, IPv6 bracket form), and (3) proxyFetch timeout vs caller-abort error shaping and message redaction.

[Copilot]

The new proxy/NO_PROXY matching + timeout/abort behavior is non-trivial and security/ops sensitive. Add unit tests covering: (1) mergeNoProxyEntries dedupe + loopback injection, (2) shouldBypassProxy hostname matching edge cases (leading dot, wildcard, IPv6 bracket form), and (3) proxyFetch timeout vs caller-abort error shaping and message redaction.

[Copilot]

The new proxy/NO_PROXY matching + timeout/abort behavior is non-trivial and security/ops sensitive. Add unit tests covering: (1) mergeNoProxyEntries dedupe + loopback injection, (2) shouldBypassProxy hostname matching edge cases (leading dot, wildcard, IPv6 bracket form), and (3) proxyFetch timeout vs caller-abort error shaping and message redaction.

[Copilot]

Errors from the watch-trigger are silently swallowed. If the touch fails (permissions, missing parent dir, invalid path), OpenClaw watchers may not reload and this will be hard to diagnose. Consider logging at least a debug/warn message with a redacted path + error code so operational issues can be triaged.

Suggested change

	} catch {
	return;
	}
	}
	} catch (error) {
	console.warn(
	`[OpenClawWatchTrigger] Failed to touch watch-trigger file "${this.redactPath(filePath)}"${
	this.getErrorCode(error) ? ` (code: ${this.getErrorCode(error)})` : ""
	}`,
	);
	return;
	}
	}
	private redactPath(filePath: string): string {
	return path.basename(filePath);
	}
	private getErrorCode(error: unknown): string | undefined {
	if (
	typeof error === "object" &&
	error !== null &&
	"code" in error &&
	typeof error.code === "string"
	) {
	return error.code;
	}
	return undefined;
	}