From abbe338378beb79f77627312c3026e2a951eff75 Mon Sep 17 00:00:00 2001 From: Qiyuanqiii <267806965+Qiyuanqiii@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:10:59 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=EF=BB=BFdocs:=20overhaul=20repository=20do?= =?UTF-8?q?cumentation=20and=20expand=20badge=20matrix?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Humanize README.md & README.en.md: elevate Quick Start, clarify core features, add browser ChatGPT sign-in, restore full documentation navigation index and third-party font compliance notices. - Upgrade README badge matrix: include CI build status, latest release, license, platform compatibility, Go 1.26+, Node.js 24+, React 18, PRs welcome, and community GitHub metrics. - Refactor CONTRIBUTING.md: remove bureaucratic machine legalese, document Go OpenAPI DTO generation pipeline, credentials/test isolation guidelines, and desktop test flags. - Overhaul web/README.md: replace internal machine log dump with structured functional view matrix, dual execution modes (Vite proxy vs Go hosted), and bilingual developer guidance. - Align v1.0.0 release notes with the Universal-Code brand. Co-authored-by: Google Gemini Code Assist Co-authored-by: Gemini Code Assist --- CONTRIBUTING.md | 295 ++++++++++++++++------------------------ README.en.md | 133 +++++++++++------- README.md | 135 ++++++++++-------- docs/releases/v1.0.0.md | 6 +- web/README.md | 232 ++++++++++++++----------------- 5 files changed, 387 insertions(+), 414 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a3682d03e..54721a462 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,252 +1,199 @@ -# 为 Universal Code 贡献 / Contributing to Universal Code +# 为 Universal-Code 贡献代码 (Contributing Guide) -感谢你参与 Universal Code。这个仓库把“可恢复、可审计、默认关闭高权限能力”视为产品合同，而不只是实现细节。请优先提交范围清晰、可以独立验证的纵向切片；涉及执行权、凭证、网络、持久化或信任边界的改动，应先把威胁模型和失败语义写清楚。 +感谢你对 Universal-Code 的关注与支持！我们欢迎社区提交 Bug 修复、功能增强、文档优化以及用户体验改进。 -Thank you for contributing to Universal Code. Resumability, auditability, and fail-closed authority are product contracts here. Prefer small, independently verifiable vertical slices. Changes involving execution, credentials, networking, persistence, or trust boundaries need an explicit threat model and failure semantics. +为了让开发与审查流程更顺畅高效，请在提交代码前阅读本指南。 -## 开始之前 / Before you start +--- -1. 阅读 [架构说明](docs/architecture.md)、[项目状态](docs/PROJECT_STATUS.md) 和与改动最接近的 [ADR](docs/adr/)。长期任务还应核对 [任务书](docs/TASK_BOOK.md) 与 [项目记忆](docs/PROJECT_MEMORY.md)，避免重复已完成的切片或把历史计划当成当前能力。 -2. 对行为变化先开 Issue 或 Draft PR，说明用户目标、信任边界、最小验收条件和明确不在范围内的事项。新增控制平面、授权路径、数据库状态机或跨语言所有权时，先新增 ADR；沿用既有决策的小修复可以在 PR 中引用相关 ADR。 -3. 不要把公开百分比、历史测试记录或 `release_ready` 文案当成验证结果。PR 只声明你在当前提交上实际运行过的检查。 +## 🛠️ 开发环境要求 -## 控制器装配契约 / Controller assembly contracts +在本地搭建开发环境前，请确保已安装以下基础工具： -HTTP 控制器窄接口增加方法时，同步更新 `httpapi.New` 的能力开关校验和真实生产控制器的装配、路由或能力投影测试。启用的已发布能力缺接口时应在构造期返回明确错误，不能通过运行时类型断言静默变成 404/503 或 false。关闭的可选能力仍可使用最小控制器；凭据等后端是否可用由显式能力方法表达。Toolgateway 的可选 Script Process 存储通过 `ScriptProcessCapabilities` 返回缺失契约原因，生产 SQLite 装配测试必须保证其能力仍完整。 +| 工具 | 推荐版本 | 来源与用途 | +| :--- | :--- | :--- | +| **Go** | 1.26+ | 核心控制平面、CLI、TUI、HTTP API 与 SQLite 状态机 | +| **Node.js** | 24+ | 前端管理界面（`web/` 目录下的 React 18 + Vite） | +| **Git** | 2.41+ | 源码版本管理 | +| **Rust** *(可选)* | 1.97.1+ | 仅在修改或验证 `analyzers/` 目录下的 WASI 代码分析器时需要 | -When extending a narrow HTTP controller interface, update the capability-gated checks in `httpapi.New` and tests using concrete production controllers. An enabled published capability must reject a missing contract during construction rather than silently projecting 404/503 or false. Keep minimal controllers valid for disabled optional capabilities and express backend availability explicitly. Toolgateway reports optional Script Process storage contracts through `ScriptProcessCapabilities`; its production SQLite assembly test must retain complete support. +> **提示**：普通的前后端功能开发不需要真实云端模型凭据；未配置外部模型时，系统将自动使用内置的 Mock Provider 供本地联调。 -## 开发环境 / Development environment +--- -仓库和 CI 当前固定以下主版本： +## 💻 本地开发工作流 -| 工具 | 版本 | 来源与用途 | -|---|---:|---| -| Go | 1.26.9 | [`go.mod`](go.mod)；唯一控制平面、CLI、TUI、HTTP API 与持久化 | -| Node.js | 24 | [CI](.github/workflows/ci.yml)；`web/` 下的 React/Vite 控制台 | -| Rust | 1.97.1 | [`analyzers/rust-toolchain.toml`](analyzers/rust-toolchain.toml)；确定性 Analyzer 夹具 | - -Git 需要 2.41+；修改 Analyzer 时另需 rustup。普通 Go/Web 开发不要求 Docker、真实 Provider 或 API key；未配置外部模型时使用 Mock Provider。`configs/models.yaml` 是无秘密的示例，不是运行时配置源。 - -Go 构建使用 `go.mod` 中的精确补丁版本；本机安装其他版本时，设置 -`GOTOOLCHAIN=go1.26.9`。较新的 Go 发布分支也可能尚未修复同一漏洞，不能只按版本大小判断安全性。 - -首次检出后，按你要修改的表面准备依赖： +### 1. 检出仓库与准备依赖 ```bash -# Go control plane -go mod verify +# 克隆代码库 +git clone https://github.com/CWNU-Open-Source-Community/Universal-Code.git +cd Universal-Code -# React/Vite console +# 安装前端依赖 cd web npm ci cd .. -# Rust analyzer fixtures -rustup toolchain install 1.97.1 --profile minimal --component rustfmt --component clippy -rustup target add wasm32-wasip1 --toolchain 1.97.1 +# 校验并同步 Go 模块依赖 +go mod verify ``` -### Windows Desktop +### 2. 启动前端热重载开发服务器 -桌面开发和便携构建必须在 Windows 10/11 上进行，并安装 Microsoft Edge WebView2 Evergreen Runtime `94.0.992.31` 或更新版本。还需要上表中的 Go 1.26.9、Node.js 24 和 PowerShell；Rust 只在修改或完整验证 Analyzer 路径时需要。应用会在打开 SQLite 前检查 WebView2，缺失或过旧时失败关闭，不会自行下载或安装。 +在 `web` 目录下运行： -```powershell -# 在仓库根目录构建未签名的本地测试包 -./scripts/build-desktop.ps1 - -# 发布候选验证会连续构建并比较 SHA-256 -./scripts/build-desktop.ps1 -VerifyReproducible +```bash +cd web +npm run dev +# 默认开发地址为 http://127.0.0.1:5173 ``` -产物位于忽略的 `build/desktop/`。它不是已签名发行版；自动检查通过也不能替代待完成的 Windows 10/WebView2/显示缩放人工矩阵。更多边界见 [Desktop Plan](docs/DESKTOP_PLAN.md) 和包内使用的 [本地测试说明](packaging/windows/LOCAL-TEST-GUIDE.txt)。 +前端开发服务器已配置自动反向代理，会自动将 `/api` 请求转发到本地运行的 Go 后端服务（默认目标为 `http://127.0.0.1:8765`）。 -### macOS Desktop +### 3. 运行 Go 后端 API 服务 -macOS 便携构建需要 macOS 12+（Monterey）与 Xcode 命令行工具（codesign），以及上表中的 Go 1.26.9、Node.js 24；WKWebView 随系统提供，不需要 WebView2 式预检。前端测试环境固定在 Node.js 24 基线：本地 Node 版本不符时脚本会在前端检查前明确报错（可用 `nvm use 24` 切换，或 `-SkipFrontend` 跳过已构建好的 web/dist）。 +在仓库根目录下运行： ```bash -# 在仓库根目录构建未签名、ad-hoc 签名的本地测试包 -./scripts/build-desktop-darwin.sh - -# 发布候选验证会连续构建并比较 SHA-256 -./scripts/build-desktop-darwin.sh -VerifyReproducible - -open build/desktop/TraverseBoard.app +go run ./cmd/cyberagent api serve --listen 127.0.0.1:8765 ``` -产物位于忽略的 `build/desktop/`。它不是已签名/已公证发行版；系统凭证库、ConPTY 用户终端、受限浏览器与完整 CDP 在 macOS 保持关闭或失败关闭，凭证使用环境变量。更多边界见 [ADR 0097](docs/adr/0097-macos-desktop-portable-build.md) 和包内使用的 [本地测试说明](packaging/macos/LOCAL-TEST-GUIDE.txt)。 - -## 从源码运行 / Run from source - -```powershell -git clone https://github.com/CWNU-Open-Source-Community/Universal-Code.git -cd "Universal-Code" +如需配置只读访问 Token 或控制 Token，可在启动前注入环境变量： +```bash +# Windows PowerShell +$env:CYBERAGENT_API_TOKEN = "local-read-token" +$env:CYBERAGENT_API_CONTROL_TOKEN = "local-control-token" -go run ./cmd/cyberagent version -go run ./cmd/cyberagent provider list -go run ./cmd/cyberagent workspace init demo -go run ./cmd/cyberagent workspace list -go run ./cmd/cyberagent tui +# Linux / macOS +export CYBERAGENT_API_TOKEN="local-read-token" +export CYBERAGENT_API_CONTROL_TOKEN="local-control-token" ``` -默认配置使用确定性的 Mock Provider，不需要 API key。接入外部模型前，请先阅读 [Provider 与模型配置](docs/usage.md#model-and-provider-commands)；凭证应进入系统凭证存储或进程环境，不能提交到仓库。 +### 4. 运行桌面版客户端 -OpenAI-compatible 连接使用独立的 `CYBERAGENT_OPENAI_API_KEY`、 -`CYBERAGENT_OPENAI_BASE_URL` 与 `CYBERAGENT_OPENAI_MODEL` 环境变量；后两项默认分别为 -`https://api.openai.com` 和 `gpt-4.1-mini`。仓库内的 `configs/models.yaml` -只是无秘密示例，不会作为运行时配置源。 +- **Windows 桌面端 (需要 Edge WebView2 Runtime)**： + ```powershell + # 本地构建未签名测试包 + ./scripts/build-desktop.ps1 -本地 Ollama 是唯一无凭证 Provider，只在显式设置 `CYBERAGENT_OLLAMA_BASE_URL`（仅 -loopback `http`，默认 `http://127.0.0.1:11434`）与 `CYBERAGENT_OLLAMA_MODEL` 时启用； -非 loopback、HTTPS、redirect 与代理绕过一律拒绝。tools/vision/JSON/context 能力按 -`/api/show` 探测结果失败关闭，不自动安装 Ollama、不 pull 模型、不扫描局域网。 + # 运行可复现验证构建 + ./scripts/build-desktop.ps1 -VerifyReproducible + ``` +- **macOS 桌面端**： + ```bash + # 本地构建测试包 + ./scripts/build-desktop-darwin.sh + ``` -The default configuration uses the deterministic Mock Provider and requires no API key. Read [Model and Provider Commands](docs/usage.md#model-and-provider-commands) before connecting an external model. Credentials belong in the OS credential store or process environment, never in the repository. +--- -Local Ollama is the only keyless Provider and enables only when `CYBERAGENT_OLLAMA_BASE_URL` (loopback `http` only, default `http://127.0.0.1:11434`) and `CYBERAGENT_OLLAMA_MODEL` are set explicitly. Non-loopback hosts, HTTPS, redirects, and proxy bypasses are rejected; tools/vision/JSON/context capabilities fail closed from `/api/show` probing, and Traverse Board never installs Ollama, pulls a model, or scans the LAN. +## 🔄 OpenAPI 契约与 DTO 代码生成 -## Repository layout / 项目结构 +Universal-Code 以 **Go 结构体与路由定义作为 API 的唯一真相来源 (Single Source of Truth)**。 -| Path | Purpose | -|---|---| -| `cmd/cyberagent` | CLI, TUI, and API entry point | -| `cmd/cyberagent-desktop` | Windows/macOS Desktop shell | -| `internal/` | Go domain, application, Policy, Store, Tool, Sandbox, and HTTP control plane | -| `web/` | React/Vite operator UI; owns no authority, secrets, or executor | -| `analyzers/` | Deterministic Rust Analyzer and shared vectors | -| `configs/` | Secret-free configuration templates | -| `docs/` | Architecture, usage, status ledgers, ADRs, and product scope | -| `packaging/` | Local portable preview and test guidance | - -## 设计与实现原则 / Design and implementation principles - -### 提交一个纵向切片 - -一个功能切片通常应同时覆盖： - -1. Go 领域合同和状态转换； -2. SQLite 约束、迁移与恢复/重放语义（如有持久状态）； -3. Policy、Scope、Approval、Budget、Capability 和执行租约中适用的门禁； -4. CLI、HTTP/OpenAPI、Web 或 Desktop 中真正需要的最小产品入口； -5. 正常、拒绝、取消、超时、不确定提交和重启恢复测试； -6. 对应 ADR、使用说明和项目状态更新。 - -不要只在 React 中模拟 Go 状态，也不要让 Rust、浏览器或桌面原生绑定形成第二套控制平面。允许的方向始终是 `TypeScript -> Go -> Rust/Docker/LLM`；授权、凭证、持久化和工作区权限由 Go 拥有。 - -### 保持安全不变量 - -- 默认失败关闭。配置档位、界面选项或模型输出都不能自行授予执行、网络、文件写入或安装权限。 -- 把仓库内容、模型文本、Tool 输出、外部 Skill、Analyzer 结果和网络内容视为不可信证据，而不是指令或验证事实。 -- 高权限动作继续经过独立的 Scope、Policy、人工确认、预算、Capability、幂等/恰好一次与租约检查；不能通过新增旁路“临时”绕过。 -- 用户可见状态必须来自持久事实。模型声称“完成”不能替代 Finding、Evidence、Verification、Receipt 或测试结果。 -- 新的 mutation 必须定义重放键、冲突、取消、崩溃和恢复行为。对外 DTO 不暴露 lease/fencing identity、operation key/digest、原始 Tool 参数或私有生命周期。 -- 变更执行权限、信任边界、跨语言所有权、对外协议或不可逆迁移时，提交新的顺序编号 ADR，并写清备选方案、拒绝路径和剩余未授权能力。 - -数据库迁移必须只向前、可在现有数据库上重放，并同时在 Go 与 SQLite 层保留关键不变量。不要手工改写用户数据库，也不要通过迁移猜测过去不存在的授权事实。 - -## OpenAPI 与生成文件 / OpenAPI and generated files - -Go DTO 和显式路由目录是 API 的唯一来源。修改 HTTP 路由或 DTO 后，从仓库根目录重新生成并提交这两个受测快照： +当你修改了 Go HTTP 控制器、路由或对外 DTO 时，必须从仓库根目录重新生成接口定义并提交受测快照： ```bash +# 1. 由 Go 导出最新的 OpenAPI 3.1 规范文档 go run ./cmd/cyberagent api openapi --output docs/openapi.json + +# 2. 重新生成前端 TypeScript 类型定义 cd web npm run generate:api cd .. + +# 3. 检查是否存在类型或接口漂移 +cd web +npm run check:api +cd .. ``` -不要手工编辑 `docs/openapi.json` 或 `web/src/api/schema.d.ts`。`npm run check:api` 会重新生成 TypeScript 类型并在存在漂移时失败。生成的 DTO 仍须排除凭证、Workspace 绝对根路径、Artifact/Session 私有正文、模型原始输出、Tool 参数以及 lease/fencing 标识。 +> **注意**：请勿手动编辑 `docs/openapi.json` 或 `web/src/api/schema.d.ts`。所有 DTO 生成物在 CI 中均会通过 `npm run check:api` 严格校验一致性。 -## 验证 / Validation +--- -先运行与改动最接近的聚焦检查，再在提交前扩大范围。以下命令均来自当前仓库脚本或 CI；不要在 PR 中勾选未实际运行的项目。 +## 🧪 运行测试与质量检查 -### 聚焦检查 +在提交 Pull Request 前，请确保相关测试均能本地通过： -```bash -# Go：以下为 HTTP/OpenAPI 改动的示例；换成实际受影响包 -go test -count=1 ./internal/httpapi -go test -count=1 ./internal/httpapi -run '^TestOpenAPIDocumentIsDeterministicCapabilitySeparatedAndSecretFree$' +### 前端测试与类型检查 (web/) -# Web +```bash cd web -npm test -- src/api/client.test.ts -npm run typecheck -# Rust analyzer -cd analyzers -cargo fmt --all -- --check -cargo test --locked -cargo clippy --locked --all-targets -- -D warnings -``` +# 运行 TypeScript 静态类型检查 +npm run typecheck -如改动影响并发、恢复、状态机或跨进程边界，应对受影响 Go 包增加 `go test -race -count=1 ...`。如改动影响 Desktop，至少运行 CI 使用的安全 tag 边界： +# 运行 Vitest 单元与集成测试套件 +npm test -```powershell -# Windows -go test -tags "desktop,wv2runtime.error" -count=1 ./cmd/cyberagent-desktop ./internal/desktop ./internal/webui +# 验证生产打包构建 +npm run build ``` +### 后端单元与集成测试 (根目录) + ```bash -# macOS +# Go 静态分析 +go vet ./... + +# 运行全量单元测试 +go test -count=1 ./... + +# 运行桌面端专属集成测试 (Windows / macOS) go test -tags "desktop" -count=1 ./cmd/cyberagent-desktop ./internal/desktop ./internal/webui ``` -### 提交前检查 - -对跨层功能或准备合并的改动，运行适用的完整检查： +### Rust 分析器测试 (仅涉及 analyzers/ 时) ```bash -# Go -go mod verify -go test -timeout 20m -count=1 ./... -go vet ./... - -# Web -cd web -npm ci -npm run check:api -npm test -npm run build - -# Rust cd analyzers cargo fmt --all -- --check cargo test --locked cargo clippy --locked --all-targets -- -D warnings -cargo build --locked --bin cyberagent-analyzer-fixture -cargo +1.97.1 build --locked --target wasm32-wasip1 --package cyberagent-analyzer-fixture --release +cd .. ``` -完整 `go test -race -timeout 20m -count=1 ./...`、`staticcheck ./...`、`govulncheck ./...`、依赖审计和 Windows 可复现构建适合权限/持久化/并发边界、累计发布门或维护者要求的改动。它们可能较慢或需要额外工具；如果本机无法运行，请在 PR 中明确列为“未运行”并依赖相应 CI/维护者门禁，不要把缺失工具写成通过。 +--- -最后运行： +## 🔐 敏感数据隔离与测试安全守则 -```bash -git diff --check -git status --short -``` +- **严禁提交机密凭据**：绝不要将真实 API Key、Bearer/Control Token、Cookie、`.env` 文件、真实的供应商请求日志或敏感数据提交到 Git 仓库。 +- **本地临时数据隔离**：请勿将本地生成的 `.cyberagent-workbench/`、`cyberagent.db`、SQLite WAL 文件或 `build/`、`dist/` 产物提交到版本库中。 +- **测试环境纯净**：单元测试与 CI 流程默认使用 Mock Provider，切勿在自动化测试中对公网产生真实计费或未授权的网络流量。 -确认生成文件已提交、没有意外构建产物，且所有测试结果都对应当前提交。 +--- -## 数据、凭证与测试隔离 / Data, secrets, and test isolation +## 📐 设计哲学与工程规范 -- 绝不要提交 API key、Bearer/control token、Cookie、凭证截图、`.env`、Provider 原始响应或真实模型 Prompt/Tool payload。 -- 不要提交 `CYBERAGENT_HOME` 中的数据、`.cyberagent-workbench/`、`cyberagent.db`、SQLite/WAL 文件、`build/`、`web/dist/`、`node_modules/` 或 Rust `target/`。 -- 手工/集成测试应使用独立临时目录或专用 `CYBERAGENT_HOME`，并默认使用 Mock Provider。不要在测试中扫描公网、产生攻击流量、启动未授权 Docker/LocalRunner，或读取系统凭证。 -- Fixture 应最小化、确定、去标识化。日志、错误、Artifact 和快照必须经过现有脱敏边界；不要为了测试方便降低上限或把私有正文写入公开投影。 -- Store 迁移测试使用 `openHistoricalTestDatabase(t, path, version)` 准备所需历史版本，在独立副本中写入旧数据，再通过 `Open` 或被测迁移执行升级。该 helper 复用真实历史迁移生成的数据库，不共享连接或测试数据；准备失败由 helper 直接报告。 -- 检验迁移引擎、事务回滚及历史 schema 的独立对照测试仍从空数据库逐步执行迁移。新增升级测试直接选择所需历史起点，避免先建到较新版本再维护一串反向删除语句；原有数据保留、约束、拒绝及恢复断言应随测试保留。 +1. **安全第一与最小特权原则**： + - 所有的代码读写、终端命令执行和网络访问都具备明确的审计边界。 + - 文件删除、覆盖式重命名或危险命令必须经过人工弹窗确认，绝不允许静默越权。 +2. **前后端职责分明**： + - **Go 控制面** 拥有完整的数据持久化、状态转换、权限门禁和执行调度能力。 + - **React 前端** 负责用户交互呈现与视觉效果，不私自推导或伪造未经后端确认的状态。 +3. **纯 CSS 现代性能标准**： + - 界面视觉效果优先使用现代纯 CSS 属性（如 `backdrop-filter`、多层 `box-shadow` 内阴影、`linear-gradient`）。 + - 避免引入高开销的 SVG 位移滤镜（如 `feTurbulence`）或全屏 WebGL Canvas，确保在展示大量代码和日志输出时保持 120fps 丝滑滚动。 +4. **统一规范的产品命名**： + - 所有面向用户的标题、文案、关于页面与文档中，产品官方名称一律统一为 **`Universal-Code`**。 -如果误提交了秘密，请立即停止推送并轮换凭证；仅从 Git 历史删除并不能撤销已经泄露的值。不要在公开 Issue 中粘贴可利用细节、可用凭证或敏感主机数据；如果尚无私密报告渠道，只提供最小、脱敏的影响说明，并请求维护者建立私密沟通。 +--- -## 提交与 PR / Commits and pull requests +## 🚀 提交 Pull Request (PR) -- 从最新 `main` 创建主题分支，每个 PR 保持一个可审阅的目标；不要夹带格式化、依赖升级或历史状态重写。 -- 使用简短、祈使语气的提交标题。正文解释行为、边界或迁移理由，而不是逐文件复述 diff。 -- 完整填写 [PR 模板](.github/PULL_REQUEST_TEMPLATE.md)：说明改了什么、为什么现在需要、用户/开发者影响、实际验证和未运行的检查。 -- 行为或进度变化时更新相应使用文档、ADR 和当前状态，但不要重写历史 ADR/Progress 记录来伪造连续性。 -- 明确列出安全审计结果：是否新增权限、网络、进程、文件写入、凭证、持久化或外部输入；如果答案是否，也应说明如何保持现有不变量。 +1. 从 `main` 分支切出具名分支，例如： + ```bash + git checkout -b fix/sidebar-docking + # 或 + git checkout -b feat/support-deepseek-r1 + ``` +2. 保持 Commit 粒度清晰，提交信息简明扼要。 +3. 在本地完整运行并通过 `npm test` 和 `go test`。 +4. 在 GitHub 上发起 Pull Request，简要说明： + - **改动背景**：解决了什么问题或增加了什么特性。 + - **关键设计**：采用了什么样的架构思路。 + - **验证方式**：在本地如何复现并验证了修复效果。 -小而完整的 PR 比跨越多个信任边界的大改写更容易验证和恢复。遇到不确定的授权设计时，请先提交 ADR 或 Draft PR 讨论。 +再次感谢你为 Universal-Code 做出的贡献！🎉 diff --git a/README.en.md b/README.en.md index e25a50793..b3f60d847 100644 --- a/README.en.md +++ b/README.en.md @@ -1,89 +1,118 @@
- Universal-Code icon + Universal-Code Logo

Universal-Code

-

Work with AI in your local project: edit code, run commands, research, and review results.

+

Open-source AI coding workbench for local projects

+

Connect cloud or local LLMs to read and edit code, run terminal commands, research docs, and review diffs with safety controls.

+

简体中文 | English

+ +

+ CI + Release + License + Platform + Go + Node + React + PRs Welcome +

- CI - License + Stars + Forks + Issues

-Universal-Code is a desktop AI coding workbench. Connect your chosen model and move a project forward in one conversation, with file changes, command results, and sources available for review. - -**v1.0.0 “First Voyage” is being prepared for release.** The [release notes](docs/releases/v1.0.0.md) record verified scope and remaining work. Public downloads still include older previews; new Mac packages are unnotarized previews. - -## Why Universal-Code? - -- **Work on a real project**: read and edit files, run builds, and inspect the resulting changes. -- **Fewer interruptions, with control**: select Full Access for a task to allow ordinary file changes and network commands to proceed automatically; file deletion still requires confirmation. -- **Keep research traceable**: prefer native search when the provider supports it, read GitHub, Hacker News, and RSS/Atom sources, and retain page snapshots and citations. -- **Continue existing work**: task history, tool records, and checkpoints stay on your machine so you can inspect progress and continue the conversation. +--- -## Appearance +## 🌟 Highlights -Choose **System, Light, Dark, or Mist** in **Settings → Appearance**. System follows your device’s light or dark setting. Mist uses a muted blue-gray canvas and light frosted surfaces, with adjustable blur, opacity, and brightness. +- 🛠️ **Built for Local Repositories**: Read, inspect, and edit local codebases with built-in line-by-line diff inspection and auditable checkpoints (Rewind). +- 🛡️ **Transparent Permission Control**: Choose between read-only analysis, approval-gated runs, and automated Full Access. High-risk actions (file deletion, unlisted commands) always require manual confirmation. +- 🧠 **Ready for Any Model**: Native support for OpenAI, Anthropic Claude, DeepSeek, Kimi, local Ollama models, and custom OpenAI-compatible endpoints with on-the-fly model switching. Also supports quick browser-based **ChatGPT account sign-in**. +- 🔍 **Traceable Web Research**: Prioritizes provider-hosted native search, fetches GitHub Issues/PRs, Hacker News, and RSS/Atom feeds, and keeps source snapshots and citations. +- 💎 **Modern Liquid Glass Aesthetic**: Crafted with pure CSS optical refraction (macOS / VisionOS acrylic style), supporting Dark, Light, and Mist frosted themes at a responsive 120fps. -![The same Universal-Code conversation in Light and Dark, split diagonally](docs/images/appearance/light-dark.png) +--- -Captured from a production build of the current source using a local demo project and offline sample replies. Light is on the left; Dark is on the right. +## 🚀 Quick Start -
-View theme options and Mist +### Option 1: Download Pre-built Binaries -![System, Light, Dark, and Mist theme options](docs/images/appearance/theme-options.png) +| OS | Instructions | +| :--- | :--- | +| **Windows 10/11** | Download `Universal-Code.exe` from [Releases](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases) and launch (requires Edge WebView2 Runtime). See the [Windows release guide](docs/windows-release.md). | +| **macOS (Apple Silicon / Intel)** | Download `.dmg` or `.zip` from [Releases](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases), unpack, and move to Applications. See the [macOS release guide](docs/macos-release.md). | -![Universal-Code in Mist](docs/images/appearance/conversation-mist.png) +### Option 2: Build from Source -
+Make sure you have **Go 1.26+** and **Node.js 24+** installed: -See the [appearance guide](docs/usage.md#外观--appearance) for details. +```bash +# 1. Clone the repository +git clone https://github.com/CWNU-Open-Source-Community/Universal-Code.git +cd Universal-Code -## Quick start +# 2. Build the web frontend +cd web +npm ci +npm run build +cd .. -### 1. Open the app +# 3. Launch the desktop application +go run ./cmd/cyberagent-desktop +``` -| Platform | Start here | -| --- | --- | -| Windows 10/11 | Download `TraverseBoard.exe` from a [published release](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases) and double-click it. WebView2 is required. [Download details](docs/windows-release.md) | -| macOS | Get an [Apple Silicon / Intel preview](docs/macos-release.md), extract it, and open `TraverseBoard.app`. Packages are unnotarized; model credential setup still has platform limitations. | +--- -The Windows steps below describe the current v1.0.0 source. Older preview interfaces may differ. To try current source, see the [local build instructions](CONTRIBUTING.md#开发环境--development-environment). +## ⚙️ Connecting Models -### 2. Connect a model +When opening the app or starting a new thread, click the model selector above the composer: -Create a conversation and select a project folder. Follow the first-conversation prompt to select a provider and enter its API key, model name, and service URL where needed. Choose **保存并检查 / Save and check**. A successful check returns to your draft with that model selected; configured models can be switched in the composer. +1. **Cloud Providers (OpenAI, Claude, DeepSeek, Kimi, etc.)**: + - Pick your provider, enter your API Key, model identifier, and service Base URL if needed. + - Click **Save and Check** to verify credentials and quota. +2. **ChatGPT Account Sign-in (No API Key Required)**: + - Select **ChatGPT** in model settings and click **Continue with ChatGPT**. + - Authorize in your default system browser to use your account's available models. +3. **Local Ollama (Offline / Private)**: + - Ensure Ollama is running locally (default: `http://127.0.0.1:11434`). + - Select **Ollama** in the provider list, enter the model name (e.g. `qwen2.5-coder:7b`, `deepseek-r1:8b`), and start querying. -You need valid model-service credentials and available quota; signing into the app does not connect a model. Checks call the selected service and may incur charges. Native search also requires provider support. +--- -### 3. Start a task +## 🖼️ Interface Preview -In that conversation, try a request whose result is easy to review: +| Light & Dark Split | Mist Frosted Glass | +| :---: | :---: | +| ![Light and Dark comparison](docs/images/appearance/light-dark.png) | ![Mist appearance](docs/images/appearance/conversation-mist.png) | -> Read this project, explain how to run it and its main directories, then suggest one improvement. +Switch between **System, Light, Dark, and Mist** under **Settings → Appearance**. -Choose the appropriate task permission before making changes. Review file diffs, command output, and citations, then send follow-up requests in the same conversation. +--- -## Explore when needed +## 📚 Documentation Index -| I want to… | Documentation | -| --- | --- | -| Configure models or use the CLI | [Usage guide](docs/usage.md) | -| Configure search, inspect sources, or diagnose failures | [Search and citations](docs/web-evidence.md) | -| Inspect or restore file changes | [Workspace checkpoints](docs/workspace-checkpoints.md) | -| Add MCP, plugins, or code intelligence | [Extensions](docs/extensions.md) · [LSP](docs/code-intelligence.md) | -| Develop from source or understand the design | [Contributing](CONTRIBUTING.md) · [Architecture](docs/architecture.md) | -| Browse all documentation and development history | [Documentation index](docs/README.md) · [History](docs/development-history.md) | +| Topic | Document | Description | +| :--- | :--- | :--- | +| **User Guide** | [Usage Guide](docs/usage.md) | Client walkthrough, CLI commands, and typical workflows | +| **Web Research** | [Search & Citations](docs/web-evidence.md) | Search setup, snapshot storage, URL provenance, and diagnostics | +| **Code Auditing** | [Workspace Checkpoints](docs/workspace-checkpoints.md) | Line-by-line diff review, snapshots, and safe Rewind | +| **Extensions** | [Extensions & MCP](docs/extensions.md) | Integrating Model Context Protocol (MCP) and custom skills | +| **Code Intelligence** | [LSP Support](docs/code-intelligence.md) | Symbol jump, type inference, and repository index | +| **Architecture** | [Architecture Specs](docs/architecture.md) | Go control plane, execution state machines, and security policies | +| **Changelog** | [Release Notes](docs/releases/v1.0.0.md) | v1.0.0 verified scope, compatibility, and milestone records | -## Feedback and contributions +--- -Use [Issues](https://github.com/CWNU-Open-Source-Community/Universal-Code/issues) for bugs and suggestions, and read the [contribution guide](CONTRIBUTING.md) before developing. The active focus is general AI coding workflows; see [Product scope](docs/PRODUCT_SCOPE.md). +## 🤝 Contributing -## License +Contributions, issues, and feature requests are welcome! Check out our [Contributing Guide](CONTRIBUTING.md) to get started. -[Apache License 2.0](LICENSE). +## 📄 License & Font Compliance -**Third-party font notice:** the Chinese interface uses HarmonyOS Sans Fonts by Huawei Device Co., Ltd. The full [font license](web/public/licenses/HarmonyOS-Sans.txt) ships with the app; [provenance and hashes](web/src/assets/fonts/PROVENANCE.md) are available for inspection. +- Distributed under the [Apache License 2.0](LICENSE). +- **Third-party Font Notice**: The Chinese UI bundles HarmonyOS Sans Fonts licensed by Huawei Device Co., Ltd. The complete [font license](web/public/licenses/HarmonyOS-Sans.txt) is shipped with the app; see [font provenance and hashes](web/src/assets/fonts/PROVENANCE.md) for details. diff --git a/README.md b/README.md index 9bb213e4c..1ab35b7e2 100644 --- a/README.md +++ b/README.md @@ -1,91 +1,118 @@
- Universal-Code 图标 + Universal-Code Logo

Universal-Code

-

在本地项目中，让 AI 帮你改代码、运行命令、查资料并审阅结果。

+

面向本地项目的开源 AI 编程工作台

+

连接云端与本地大模型，在同一工作流中读写代码、运行终端命令、查阅资料并实时审阅 Diff 改动。

+

简体中文 | English

+ +

+ CI + Release + License + Platform + Go + Node + React + PRs Welcome +

- CI - License + Stars + Forks + Issues

-Universal-Code 是一个桌面 AI 编程工作台。连接你选择的模型，在同一段对话中推进项目，查看文件改动、命令结果和资料来源。 - -**v1.0.0「启航」正在准备发布。** [发布说明](docs/releases/v1.0.0.md)记录已验证范围和待完成事项；目前公开下载仍有历史预览，Mac 新包为未公证预览。 - -## 为什么选择 Universal-Code - -- **围绕真实项目工作**：阅读和修改文件、运行构建、查看差异，把任务结果落到工作区。 -- **少打断，保留控制**：选择当前任务的 Full Access 后，普通文件修改与联网命令可自动执行；文件删除仍需确认。 -- **查资料时保留来源**：优先使用供应商支持的原生搜索，也能读取 GitHub、Hacker News 和 RSS/Atom，并保留网页快照与引用。 -- **继续已有工作**：任务历史、工具记录和检查点保存在本机，可回看进度、检查改动和继续对话。 - -## 外观 +--- -在 **设置 → 外观** 中选择 **系统、浅色、深色、雾透**。系统模式随设备设置切换浅深；雾透使用灰蓝底色与轻盈的磨砂材质，还可调整模糊度、磨砂度和亮度。 +## 🌟 核心特性 -![Universal-Code 同一段对话的浅色与深色外观，左浅右深斜向分割](docs/images/appearance/light-dark.png) +- 🛠️ **深度聚焦本地项目**：直接阅读、分析与修改本地代码库，内置 Diff 逐行审阅与可信撤销（Rewind / Checkpoints）能力。 +- 🛡️ **透明可控的安全策略**：支持只读分析、交互审批（Approval Mode）与全自动（Full Access）权限分级，高危操作（文件删除、非白名单命令）严格阻断并要求人工确认。 +- 🧠 **主流模型即开即用**：原生接入 OpenAI、Anthropic Claude、DeepSeek、Kimi、Ollama 本地模型与任何兼容 OpenAI 的第三方 API，支持单会话内即时热切，并支持通过系统浏览器快速完成 **ChatGPT 账户授权登录**。 +- 🔍 **真实来源的网络检索**：优先调用供应商原生搜索，支持直接抓取 GitHub PR/Issue、Hacker News 与 RSS/Atom 资讯，自动附带快照存证与引用出处。 +- 💎 **现代苹果液态玻璃美学**：采用纯 CSS 物理折射模型（macOS / VisionOS 亚克力液态玻璃风格），提供深色、浅色与雾透磨砂质感，兼具 120fps 极速渲染。 -截图来自当前源码的生产构建，使用本地演示项目与离线示例回复。左侧为浅色，右侧为深色。 +--- -
-查看主题选项与雾透外观 +## 🚀 快速开始 -![系统、浅色、深色、雾透四个主题选项](docs/images/appearance/theme-options.png) +### 方式一：下载预编译客户端 -![Universal-Code 雾透外观](docs/images/appearance/conversation-mist.png) +| 平台 | 下载与运行说明 | +| :--- | :--- | +| **Windows 10/11** | 前往 [Releases](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases) 下载 `Universal-Code.exe`，双击即可运行（需系统安装 WebView2 Runtime）。详见 [Windows 安装说明](docs/windows-release.md)。 | +| **macOS (Apple Silicon / Intel)** | 前往 [Releases](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases) 下载 `.dmg` 或 `.zip`，解压并拖入 Applications。详见 [macOS 安装说明](docs/macos-release.md)。 | -
+### 方式二：从源码构建运行 -更多设置见[外观说明](docs/usage.md#外观--appearance)。 +确保本地已安装 **Go 1.26+** 与 **Node.js 24+**： -## 快速开始 +```bash +# 1. 克隆代码仓库 +git clone https://github.com/CWNU-Open-Source-Community/Universal-Code.git +cd Universal-Code -### 1. 打开应用 +# 2. 构建前端控制台 +cd web +npm ci +npm run build +cd .. -| 平台 | 从这里开始 | -| --- | --- | -| Windows 10/11 | [下载已发布版本](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases)中的 `TraverseBoard.exe`，双击打开；需要 WebView2。[下载说明](docs/windows-release.md) | -| macOS | [获取 Apple Silicon / Intel 预览包](docs/macos-release.md)，解压并打开 `TraverseBoard.app`。当前未公证，模型凭据配置仍有平台限制。 | +# 3. 启动桌面应用或服务 +go run ./cmd/cyberagent-desktop +``` -下面是当前 v1.0.0 源码中的 Windows 上手流程；历史预览的界面可能不同。需要试用最新源码时，见[本地构建](CONTRIBUTING.md#开发环境--development-environment)。 +--- -### 2. 连接模型 +## ⚙️ 模型配置与连接 -新建对话并选择项目文件夹。首次对话按提示连接模型，选择供应商并填写 API Key、模型名称及必要的服务地址，点击 **保存并检查**。检查通过后会回到原草稿并选中该模型；已有模型可在输入区切换。 +首次打开客户端或新建对话时，点击输入区上方的模型选择器进行配置： -桌面版也可在模型设置中选择 **ChatGPT**，点击 **Continue with ChatGPT** 在系统浏览器授权，然后选择账户模型并完成检查。支持刷新模型、重新登录和退出；[实现与验收记录](docs/acceptance/2026-10-15-chatgpt-sign-in.md)注明了当前验证范围。 +1. **云端 API（OpenAI / Claude / DeepSeek / Kimi 等）**： + - 选择对应提供商，填入你的 API Key、模型标识符及服务 Base URL（如适用）。 + - 点击 **保存并检查**，系统将发起一次轻量调用以验证额度与连通性。 +2. **ChatGPT 账户浏览器授权（无需 API Key）**： + - 在模型配置中选择 **ChatGPT**，点击 **Continue with ChatGPT**。 + - 系统将唤起系统浏览器完成授权，随后可直接选择账户可用模型。 +3. **本地 Ollama（零门槛离线运行）**： + - 本地启动 Ollama 服务（默认 `http://127.0.0.1:11434`）。 + - 在提供商列表选择 **Ollama**，输入模型名称（如 `qwen2.5-coder:7b`、`deepseek-r1:8b`）即可直接调用。 -需要模型服务的可用凭据和额度。检查会实际调用所选服务，消耗对应订阅额度或产生 API 费用；原生搜索也取决于该服务是否支持。 +--- -### 3. 发出第一条任务 +## 🖼️ 界面预览 -在这段对话中，先试一个容易核对结果的请求： +| 浅色与深色对比 | 雾透磨砂玻璃 (Mist) | +| :---: | :---: | +| ![浅色与深色界面对比](docs/images/appearance/light-dark.png) | ![雾透外观](docs/images/appearance/conversation-mist.png) | -> 阅读这个项目，说明启动方式和主要目录，再指出一处值得改进的地方。 +可在客户端 **设置 → 外观** 中自由切换 **系统跟随、浅色、深色、雾透玻璃**。 -需要执行修改时，在当前任务选择合适的权限档。完成后查看文件差异、命令输出和引用；有后续要求，直接在同一对话继续。 +--- -## 按需了解更多 +## 📚 详细文档导航 -| 想做什么 | 文档 | -| --- | --- | -| 配置模型或使用 CLI | [使用手册](docs/usage.md) | -| 配置搜索、查看来源与排查失败 | [搜索与引用](docs/web-evidence.md) | -| 检查或恢复文件改动 | [工作区检查点](docs/workspace-checkpoints.md) | -| 接入 MCP、插件或代码智能 | [扩展](docs/extensions.md) · [LSP](docs/code-intelligence.md) | -| 从源码开发，了解设计 | [贡献指南](CONTRIBUTING.md) · [架构](docs/architecture.md) | -| 查看全部文档和开发历史 | [文档导航](docs/README.md) · [历史索引](docs/development-history.md) | +| 领域 | 文档链接 | 描述 | +| :--- | :--- | :--- | +| **使用指南** | [用户手册 (Usage Guide)](docs/usage.md) | 完整客户端使用、CLI 命令与常见工作流 | +| **搜索与取证** | [网络检索与快照 (Web Evidence)](docs/web-evidence.md) | 检索配置、快照存储、URL 溯源与失败诊断 | +| **改动审计** | [工作区检查点 (Checkpoints)](docs/workspace-checkpoints.md) | 逐行 Diff 审阅、快照保存与安全恢复 (Rewind) | +| **生态扩展** | [扩展与 MCP 协议 (Extensions)](docs/extensions.md) | 接入 Model Context Protocol (MCP) 与外部 Skill | +| **代码智能** | [LSP 语言服务器 (Code Intelligence)](docs/code-intelligence.md) | 符号跳转、类型推断与代码索引支持 | +| **系统架构** | [架构设计方案 (Architecture)](docs/architecture.md) | Go 控制面、执行状态机与安全策略实现 | +| **发布日志** | [版本发布说明 (Release Notes)](docs/releases/v1.0.0.md) | v1.0.0 验证范围、兼容性与更新记录 | -## 反馈与贡献 +--- -通过 [Issues](https://github.com/CWNU-Open-Source-Community/Universal-Code/issues)反馈问题或建议，参与开发请阅读[贡献指南](CONTRIBUTING.md)。当前核心方向是通用 AI 编程工作流，详见[产品范围](docs/PRODUCT_SCOPE.md)。 +## 🤝 参与贡献 -## 许可证 +欢迎提交 Issue 与 Pull Request！在开始开发前，请先阅读我们的 [贡献指南 (CONTRIBUTING.md)](CONTRIBUTING.md)。 -[Apache License 2.0](LICENSE)。 +## 📄 开源许可证与字体合规 -**第三方字体声明：** 中文界面使用 Huawei Device Co., Ltd. 的 HarmonyOS Sans Fonts，完整[字体许可](web/public/licenses/HarmonyOS-Sans.txt)随软件发布；[来源与哈希](web/src/assets/fonts/PROVENANCE.md)可供核对。 +- 本项目基于 [Apache License 2.0](LICENSE) 协议开源。 +- **第三方字体声明**：中文界面包含华为技术有限公司授权的 HarmonyOS Sans Fonts，完整 [字体许可文本](web/public/licenses/HarmonyOS-Sans.txt) 随软件一并分发；字体源文件与校验哈希详见 [字体出处说明](web/src/assets/fonts/PROVENANCE.md)。 diff --git a/docs/releases/v1.0.0.md b/docs/releases/v1.0.0.md index 0d453ca68..1e02b039b 100644 --- a/docs/releases/v1.0.0.md +++ b/docs/releases/v1.0.0.md @@ -1,8 +1,8 @@ -# Traverse Board · 针路簿 v1.0.0「启航」 +# Universal-Code v1.0.0「启航」发布说明 -首个正式版的源码与发布准备，2026-09-21。英文称号：**First Voyage**。 +首个正式版本的源码与发布准备。英文称号：**First Voyage**。 -本版本以已合并 PR #200 的主线为基础，整合后续 Full Access、模型接入、搜索、恢复和设置排版改动。产品名保持 Traverse Board · 针路簿，Windows 主程序统一为 `TraverseBoard.exe`；历史调试包名称不作为正式版名称。 +本版本以主线为基础，整合了 Full Access 权限分级、主流大模型接入、网络搜索取证、工作区检查点快照与苹果液态玻璃视觉系统。产品官方全称已统一为 **Universal-Code**。 ## 当前下载与验证状态（2026-09-21） diff --git a/web/README.md b/web/README.md index 785127539..5ef7aefbc 100644 --- a/web/README.md +++ b/web/README.md @@ -1,150 +1,120 @@ -# Traverse Board · 针路簿 Web Console - -## 中文 - -schema v42 的 Run 概览显示三个 Plan 方向、已选方向、切片数量与是否仍需显式切换到 Deliver。D1-P1 在独立 capability 下增加“方向三选一”和“进入 Deliver”两个显式操作；选择不改阶段，Deliver 不启动/恢复执行，`capability_grant` 始终为 `false`。 - -schema v45-v46 的 Run 概览显示操作者引导队列的 pending/prepared/committed/cancelled 计数和有界元数据。D1-S1/S2 通过两个独立 capability 增加现有 Run-bound Session 的 enqueue/replay 和 pending-only 取消；`prepared=true` 时 UI 不提供取消。schema v73 再增加独立的 Run start/pause/resume 和最多八条冻结输入的显式 RunSupervisor 交接。浏览器不接收消息/模型正文、工具参数、operation 或 lease 身份，也不能编辑、重排或后台唤醒队列。 - -schema v71 的 External Skills 面板只读显示 Run 固定选择的 surface/profile、版本、信任类别、token 上界、声明工具数量以及 root/Specialist 准备/提交计数。它不接收 Skill 正文、路径、字节数、hash/digest/fingerprint、安装/选择 ID、operation key 或操作者/agent 身份，也没有 Run 选择、授权或执行按钮。D1-B1 仅在 Desktop 原生预览后提供另一次显式惰性安装确认；它不自动改变该面板对应的 Run 选择。 - -这是针路簿的本地 read-mostly 运维界面。React/Vite 只消费 Go 生成的 OpenAPI 3.1 DTO 和 `api.v1`，不会重新实现 Policy、审批、工作区权限、Shell、Docker、模型路由或 SQLite 逻辑。当前窄 mutation 包括非授权档位、受控 Run/Session/Plan/审批、Go-issued FileEdit 提案/审阅/apply、不可变操作者验证、显式 plan-item/evidence 关联、record-only 快照回执及其不授权元数据复核、status-only Provider 凭证设置、wake 意图/前台消费，以及 Desktop 确认式惰性 Skill 安装。FileEdit 恢复、Repository Diff/History/Exact Commit/Comparison 键盘可访问成对预览、逐检查项验证快照下载/回执历史、带复核元数据和精确 Verify 导航的 Code Handoff、带有界审计事实的 Code Journey 和 runtime capability/worker health 是只读投影；wake worker 只能由 Go 进程启动参数开启，TypeScript 没有运行时启用入口。 - -## 针路簿桌面界面 / Traverse Board Desktop Surface - -D1-UX1/UX2/UX3 建立了最初的双表面工作台；D1-UX10/UX11 已用原生 Acrylic 和组件令牌替代 -旧背景与艺术字。当前 `PrayuBrand` 使用维护者批准的 `traverse-board-mark.png` 规范图片派生资产， -不读取截图或旧字标图片。品牌、标题、导航和正文统一使用平台比例 UI 字体，中英文按同一语义 -层级设置字重与颜色；JetBrains Mono 只保留给代码、终端、Diff、指纹、精确标识和快捷键。 -任务、Run、设置导航和分段控制共享苹果风液态玻璃语义：空闲态透明、悬停态半透明、选中态为 -纯白不透明圆角表面和深色图标文字。旧橙色笔刷的渐变、裁切与伪元素已从源码删除。设置页显示 -真实 API、schema、版本、surface 与 capability 投影，只持久化外观和紧凑度，不保存凭证或 -授权结果。 - -D1-UX4/UX5/UX6 增加 Wails 无边框窗口和原生最小化/最大化/关闭控制、默认 286 px 且可在 -232-420 px 内拖拽/键盘调整并本地记忆的侧栏，以及 Agent 输入区的附件/工作区、目标模式、计划模式、 -插件/Skill、模型、推理强度和上下文占用控件。侧栏拖拽热区保持透明，不显示橙色分隔线。模型列表 -按需读取 Go API 的真实可用性并沿用既有路由 mutation；当前 Provider 合同没有 -`reasoning_effort`，所以“高/最高”只展示为禁用能力，不会伪造已生效状态。桌面与移动布局都保持 -无横向溢出。 - -The current Traverse Board shell uses the maintainer-approved `traverse-board-mark.png` image -derivative rather than a screenshot or legacy wordmark asset. Task, Run, Settings, and segmented -selections share one Apple-inspired liquid-glass language: transparent at rest, translucent on -hover, and opaque white with dark ink when selected. The legacy orange-brush gradients, clipping -paths, and pseudo-elements have been deleted. D1-UX4/UX5/UX6 add a frameless Wails window, -native window controls, -a bounded and persisted resizable sidebar with a transparent drag target, and composer -controls for attachments, target/plan modes, installed Skills, lazy Go-backed model routing, -truthful reasoning capability state, and conservative context usage. Settings remains a -read-only projection of Go-owned runtime facts. Established `CYBERAGENT_*`, HTTP, API, and -CLI identifiers remain for backward compatibility. - -D1-UX11 adds `浅色`, `深色`, and `透明玻璃` as persisted appearance choices. The third mode -uses the native Windows Acrylic compositor in Desktop and a readable translucent dark -fallback in ordinary browsers. The three-way picker remains within a 390 px viewport without -horizontal overflow. Appearance changes never alter Go permissions or runtime capabilities. - -D1-G1/I3/F1 进一步增加只读 Repository 页、metadata-only 多文件 change-set 摘要和 Code-only Journey。Repository 不执行 `git`、网络或 hook，也不返回 host root/body/remote；change set 不提供 Apply All，所有 mutation 仍是逐文件独立 Go route；Journey 的导航组件自身没有 API client，D1-V12 仅由父级传入既有严格 Handoff 查询中的最多三条非授权审计事实。 - -schema v78 / D1-G2/V1/F2 增加有界脱敏 Repository Diff、独立 Verify 与 Code Handoff。Diff 最多 50 项、单项 64 KiB、总计 512 KiB；Verify 只记录操作者 `pass|fail|unknown` 观察，不运行命令或授予权限；Handoff 只汇总持久化 Plan/Queue/ChangeSet/Verification/Actions/Reports，并通过 Go event high-water 拒绝撕裂快照。三者都不提供 Git mutation、批量 apply、自动恢复或复合执行。 - -Windows Desktop 与普通 `api serve` 现在都读取 Go 的 -`runtime_capabilities.v1`。React 只据此显示 FileEdit、系统凭证和 wake worker 状态； -health 不含 token、owner、lease、Run 或私有错误，不能运行时启用 worker、安装服务 -或授予 mutation。每条控制 route 仍独立执行 control-token 与 capability 检查。 - -当前界面提供： - -- Run 列表、状态过滤、目标/预算/租约摘要； -- 注册 Workspace 选择，以及 Profile/Code-Cyber/Plan-Deliver 配置下的受控 Run 创建； -- 有界 root/Specialist Agent 图、operator-gated delegation 审查/应用/调度摘要； -- 只读 Fan-out 计划与最新 execution/shard 元数据； -- Finding/Report 严重度、来源、Artifact metadata 与生命周期时间线； -- 带 `Last-Event-ID` 恢复的鉴权 SSE 事件流； -- WorkItem、Note、Artifact descriptor 和 Supervisor ToolRound 视图； -- 操作者引导队列计数、顺序与状态元数据； -- 外部 Skill 的有界来源、预算与交付状态元数据； -- Session 列表、绑定 Run 和包含压缩状态的消息历史； -- capability 开启且 Run 为 running/paused 时的 Session composer；成功只显示排队 sequence/status； -- 未 prepared 的 pending 消息取消、Run Start/Pause/Resume 和 `maxSteps=1..8` 的 Run Queue 控件； -- 只读脱敏 Provider/模型路由对话框、显式 Plan 选择/Deliver 控件和 metadata-only Approvals 页； -- Windows Credential Manager 的 Provider 设置/删除入口；密码只驻留输入与单次请求，响应固定不回读明文且当前提示重启； -- Diff 审阅后独立 apply、wake schedule/cancel 后一次前台 consume，以及 Desktop 原生 Skill 预览后的惰性安装确认； -- Go-owned Files 页：只浏览注册 Workspace 的 canonical 相对路径、脱敏有界 UTF-8 与 non-authorizing provenance； -- Go-owned Repository 页：只读 exact-root Git 状态、200 项输出上限、无父发现/重定向 metadata/进程/网络/hook； -- Repository Local history：最多 50 个 first-parent commit、64 个本地 branch，主题脱敏且不返回 author/email/body/remote/root； -- Repository Exact commit/comparison：只接受精确 object ID，最多显示 200 条 changed path/status/mode metadata；比较行可分别预览或在同一可聚焦只读区域成对显示既有 base/head 脱敏 regular-file preview，并用按钮或普通左右方向键在有界变化集合内导航；Escape/关闭图标会恢复精确触发焦点；不显示 author/email/body/blob/remote/root，不 checkout 或修改 ref； -- Repository Diff：最多 50 项 secret-redacted patch、单项 64 KiB/总计 512 KiB，非文本内容闭集显示且无 mutation； -- 本地 lazy Monaco/Diff editor：只编辑 Go 发放的完整安全 UTF-8 source，并用短期 handle 创建待审 proposal；过期 handle 仅在旧 hash 仍匹配时换发，durable pending proposal 只恢复成不可编辑 Diff；不接收 host path、不直接写文件、无 CDN fallback； -- 多文件 change-set 摘要：最多 100 项，只显示状态/字节/独立 action readiness，partial apply 可见且没有 batch/atomic mutation； -- Code-only Journey：Scope、Plan、Queue and execute、Review、Verify and report 只导航既有视图，并显示最多三条 metadata-only/non-authorizing receipt-review 审计事实； -- Go-owned Actions 页：聚合最多 100 条 pending steering/approval/FileEdit/due-wake metadata，只导航到既有视图，不自动处理； -- Evidence 页：只列 exact Run/Session 已附加来源/hash/time 与固定 false instruction authority，source navigation 复用既有 Files 边界； -- Verify 页：独立 capability 下记录/列出不可变 `pass|fail|unknown` 操作者观察，明确不是命令、模型断言、审批或授权； -- Verify plan：单独记录最多 32 项 immutable operator checklist，固定 guidance-only，不执行检查、不推导结果； -- Verify association：操作者显式把一条 later evidence 关联到一个 earlier plan item；每项只显示 pass/fail/unknown 计数与 frozen snapshot-keyset 分页，并可下载 digest-bound Markdown/JSON metadata snapshot、显式记录不可变 metadata receipt，再单独确认或质疑其元数据；回执/复核历史不含正文/操作者身份且固定不是 snapshot/result acceptance、approval 或 execution，矛盾证据保留且不推导整份计划通过； -- Handoff 页：可重建显示 Plan/Queue/ChangeSet/Verification/Actions/Reports 有界摘要，以及最多 20 条 receipt-review metadata 与 confirmed/disputed 计数，并下载带 event high-water/byte count/SHA-256 的 Markdown/JSON；复核引用只有在 Verify 独立匹配 review/receipt/plan/item digest 后才聚焦，漂移不 fallback；不复制 reviewer identity/private body，不接受结果或启动/恢复执行； -- `Ctrl+K` 命令面板：只导航既有 Run 页签或刷新当前查询，不提交 mutation、路径、正文、审批、进程或 capability； -- apply/wake/install 的统一 durable operation receipt，严格显示 replay/retry/cleanup 状态； -- `preview|docker|local` 执行档位、固定门禁与 false authority 状态； -- 只驻留页面内存的 read bearer token 和可选 distinct control token。 - -浏览器不持久化 token，也不把 token 放入 URL、body 或静态资源请求。可选 control token 只驻留页面内存；Go 决定 Workspace/Run/Session 绑定、默认预算、backend、scope、审批、风险、门禁和全部权限位。不确定失败后的 operation key 只在同一未改变意图下复用；消息、lifecycle action、`maxSteps`、Diff 或 wake 意图改变都会轮换 key。除独立 Explorer 返回的有界、脱敏、明确非授权 Workspace 文本外，Artifact/Skill/Session 正文、模型输出、工具参数、私有叙述、lease/fencing token 和宿主/容器进程启动仍不向 Web 开放；FileEdit apply 和 Skill Registry 写入只能走各自的窄 Go control。事件 envelope 版本由 Go/OpenAPI/TypeScript 共用 literal `v1`；SSE 在 parse/transport failure 后先 cancel reader 再重连，避免遗留响应占满浏览器连接。 - -同一 bundle 也被 Desktop 编译进 Wails v2.13.0 Windows 壳。React 通过四个方法的严格 native bridge 取得内存连接材料、选择/预览 Skill，并消费一次性安装确认句柄；不监听端口、不使用 Local Storage。Desktop 通过同一高水位 cursor 轮询事件，Skill picker 不向 React 暴露路径或 bytes。Actions、Evidence 和命令面板只消费 read bearer/本地导航。New Run、Session、Plan、Approval、FileEdit proposal/review/apply、Provider credential 和 wake mutation 始终走进程内 Go HTTP Handler，并且只在各自 capability 开启时出现。Monaco 及五类 worker 均从本地 bundle 惰性加载；Provider 修改由 Go 原子 reload generation，`--enable-wake-worker` 只在 Go 启动时生效，UI 只显示其 1 x 1-step health/drain。 - -### 生产式本地运行 - -```powershell -# repository root +# Universal-Code Web Console + +本目录包含 **Universal-Code** 的前端桌面与 Web 用户界面，基于 React 18、TypeScript 与 Vite 构建。 + +--- + +## 🛠️ 技术栈 (Tech Stack) + +- **核心框架**：React 18 + TypeScript + Vite +- **代码与 Diff 编辑器**：Monaco Editor (本地离线打包，支持按需加载与 Proposal 恢复) +- **视觉与样式系统**：纯 CSS 苹果液态玻璃（Apple Liquid Glass Acrylic）+ Tailwind CSS 工具类 +- **测试框架**：Vitest + React Testing Library +- **数据协议**：基于 OpenAPI 3.1 强类型 DTO，通过 Server-Sent Events (SSE) 接收实时流式执行日志 + +--- + +## 🚀 本地开发与联调模式 (Getting Started) + +### 方式一：Vite 独立开发代理模式 (推荐日常前端开发) + +该模式支持热模块替换 (HMR)，修改代码后浏览器即时更新： + +```bash +# 终端 1：在仓库根目录启动 Go API 核心服务 +go run ./cmd/cyberagent api serve --listen 127.0.0.1:8765 + +# 终端 2：启动前端 Vite 开发服务器 cd web npm ci -npm run check:api -npm run build -cd .. -$env:CYBERAGENT_API_TOKEN = "" -$env:CYBERAGENT_API_CONTROL_TOKEN = "" -go run ./cmd/cyberagent api serve --listen 127.0.0.1:8765 --ui-dir web/dist +npm run dev ``` -打开 `http://127.0.0.1:8765`，输入同一个 read token；需要切换档位或创建 Run 时再输入 distinct control token。`--ui-dir` 必须指向 Vite 生产输出；Go 会在启动时校验并读入不可变快照。HTML 不缓存，带哈希的静态资源使用 immutable 缓存，未知资源与不安全 fallback fail closed。静态请求匿名可读，但携带 `Authorization`、query、body 或非 GET/HEAD 方法会被拒绝，避免 bearer 意外发送给资源处理器。 +开发服务器默认监听 `http://127.0.0.1:5173`，已内置代理将 `/api` 请求自动转发至 `http://127.0.0.1:8765`。 -### Vite 开发模式 +### 方式二：生产打包与 Go 统一托管模式 (验证构建与最终交付) -```powershell -# terminal 1: repository root -$env:CYBERAGENT_API_TOKEN = "" -$env:CYBERAGENT_API_CONTROL_TOKEN = "" -go run ./cmd/cyberagent api serve --listen 127.0.0.1:8765 +该模式直接由 Go 进程提供生产静态资源服务，测试最真实的桌面打包环境： -# terminal 2 +```bash cd web npm ci -npm run check:api -npm run dev +npm run build +cd .. + +# 启动 Go 服务托管前端产物 +go run ./cmd/cyberagent api serve --listen 127.0.0.1:8765 --ui-dir web/dist ``` -打开 `http://127.0.0.1:5173`。默认代理目标为 `http://127.0.0.1:8765`；需要改端口时设置 `CYBERAGENT_API_TARGET`，该值仍必须是 HTTP(S) 回环 URL。 +访问 `http://127.0.0.1:8765` 即可使用。如配置了 API Token，需在首次加载时输入对应凭证。 + +--- + +## 🖥️ 核心业务功能视图 (Key Views & Components) + +| 核心视图 | 对应模块路径 | 功能说明 | +| :--- | :--- | :--- | +| **会话舞台 (Stage)** | `src/v2/components/conversation.tsx` | 连续任务对话流、消息卡片、工具调用状态呈现与响应流式打字机。 | +| **伴侣停靠坞 (Companion Dock)** | `src/v2/styles.css` (`.v2-companion-dock`) | 智能对齐右侧的工作流面板，支持检查点、代码审查与工具箱原生平移停靠。 | +| **任务输入舱 (Composer)** | `src/v2/components/composer.tsx` | 任务指令输入、文件/图片附件上传、模型选择器与权限档位切换。 | +| **代码 Diff 与编辑** | `src/components/unified-diff.tsx` / `monaco/` | 逐行差异对比、待审提案（Proposal）接受/驳回与本地 Monaco 编辑。 | +| **网络检索存证** | `src/components/safe-markdown.tsx` / `evidence/` | 网页快照渲染、GitHub/HN/RSS 来源标注与点击溯源。 | +| **系统设置与外观** | `src/v2/components/provider-settings.tsx` | 多模型凭据配置、系统/浅色/深色/雾透磨砂玻璃外观实时切换。 | + +--- + +## 📁 目录结构 (Directory Layout) + +```text +web/ +├── src/ +│ ├── api/ # Go 后端 API 客户端、OpenAPI 生成的 DTO (schema.d.ts) +│ ├── assets/ # 字体（HarmonyOS Sans SC）、图标与图片静态资源 +│ ├── components/ # 通用基础 UI 组件（按钮、模态框、Diff 视图、状态卡片等） +│ ├── hooks/ # 通用 React Hooks（流式读取、按键绑定、焦点捕获等） +│ ├── lib/ # 格式化、剪贴板、剪裁等纯函数工具库 +│ ├── v2/ # V2 双列会话舞台与伴侣停靠面板 (Companion Dock) +│ │ ├── components/ # V2 核心组件（会话流、输入区、工作台、停靠抽屉） +│ │ └── styles.css # V2 苹果液态玻璃控件与弹性停靠样式 +│ ├── App.tsx # 前端根组件与顶层路由调度 +│ └── styles.css # 全局样式、设计令牌与主题光场定义 +├── package.json +└── vite.config.ts +``` -## English +--- -This is the local read-mostly operations UI for CyberAgent Workbench. React/Vite consumes the Go-generated OpenAPI 3.1 DTOs and `api.v1`; it does not reimplement policy, approvals, workspace authorization, Shell, Docker, model routing, or SQLite behavior. Its narrow mutations include controlled Run/Session/Plan/approval operations, Go-issued FileEdit propose/review/apply, immutable operator verification evidence, guidance-only checklists, explicit plan-item/evidence associations, record-only snapshot receipts, and non-authorizing receipt-metadata review, status-only Provider credential setting, wake intent/foreground consumption, and Desktop-confirmed inert Skill installation. FileEdit recovery, exact-root Repository state/redacted Diff/local history/exact-commit comparison with keyboard-accessible paired base/head previews, deterministic verification snapshot download/history, independent multi-file summaries, Code Handoff/export with exact review navigation, bounded Code Journey audit facts, and runtime capability/worker health are read-only projections. Journey navigation itself has no API client; its parent passes only the existing strict Handoff facts. TypeScript has no runtime endpoint that can enable the wake worker or batch-apply files. +## 🧪 常用脚本与检查指令 -The current UI includes controlled Run/Session/Plan/approval workflows, Agent/delegation/Fan-out/Finding views, resumable events, Workspace Files/search, repository state/redacted Diffs/local history/exact-commit comparison with keyboard-accessible paired base/head previews, evidence/actions/verification plans/outcomes/explicit associations with frozen pagination, digest-bound snapshot downloads, immutable metadata receipt history, and one non-authorizing review per receipt, regenerable Code Handoff export with exact fail-closed Verify navigation, bounded Journey audit facts, durable receipts, a navigation/refresh-only `Ctrl+K` palette, a locally bundled lazy Monaco proposal/recovery/Diff editor, and status-only system-credential controls with Registry generation status. Bearers, retry keys, source handles, review navigation targets, and password inputs stay in page memory and never enter a URL or browser storage. TypeScript submits no backend, scope, gate, private lease, host path, tool argument, or authority field; a proposal submission contains only a Go-issued handle and replacement text and cannot write the file. Verification plans are guidance, outcomes remain explicit operator observations, associations preserve contradictory evidence and never infer an overall pass, and snapshot download, record-only receipt/review, Handoff export, and review navigation cannot accept a result, resume, or mutate a Run. Go/OpenAPI/TypeScript share event-envelope literal `v1`, and failed SSE streams are cancelled before reconnect so abandoned responses cannot consume browser connection slots. +| 命令 | 用途 | +| :--- | :--- | +| `npm run dev` | 启动 Vite 热重载开发服务器 | +| `npm run typecheck` | 执行 TypeScript 全量静态类型检查 (`tsc -b`) | +| `npm test` | 运行 Vitest 全量单元与集成测试套件 | +| `npm run build` | 编译打包前端生产静态资源到 `dist/` | +| `npm run check:api` | 检查前端 DTO 与 `docs/openapi.json` 是否存在接口漂移 | +| `npm run generate:api`| 基于 `docs/openapi.json` 重新生成 `src/api/schema.d.ts` | -For the production-style local path, run `npm run build`, then start `cyberagent api serve --ui-dir web/dist`. Go validates and snapshots the bundle at startup, serves it from the same loopback origin as `api.v1`, applies a strict CSP, disables HTML caching, and gives only hashed assets immutable caching. Static requests are anonymous but reject authorization headers, queries, bodies, and methods other than GET/HEAD. For frontend development, Vite can still proxy same-origin `/api` requests to a loopback Go service and rejects non-loopback targets. +--- -Desktop compiles the same bundle into a Wails v2.13.0 Windows shell. React obtains ephemeral connection material through a strict four-method native bridge and calls the Go API in process without a listening port or browser storage. Desktop consumes `run-event-poll.v1` with the same Run-bound high-water cursor as SSE, while WebView2 and renderer-origin/navigation gates fail closed. Monaco uses only local bundled assets/workers. FileEdit proposal/recovery, Provider credential/generation, and wake controls/health remain independent Go HTTP capabilities; the optional worker can be enabled only at process startup and stays capped at one intent/one step. +## 💎 纯 CSS 视觉与设计规范 (Design Language) -Open `http://127.0.0.1:8765` for the Go-hosted build or `http://127.0.0.1:5173` for Vite development, then enter the same read token shown or configured for the Go process. Enter the distinct control token only for a narrow mutation. Bounded execution may call the configured model and approved structured tools through Go, but no Web control can start a Shell, Local, Docker, or other host/container process. +- **纯 CSS 物理光学折射**：采用由 GreyD097 纯 CSS 方案启发的双向对角内阴影 (`inset 1.5px -1.5px` 与 `inset -1.5px 1.5px`)，在按钮和面板边缘模拟凸透镜全反射效果。 +- **环境底光网格**：注入多点离散光场 (`--prayu-ambient-radial`) 搭配 `backdrop-filter: blur(34px) saturate(190%) contrast(102%)`，确保在深色模式下呈现透亮亚克力质感，杜绝普通黑底导致的色彩发灰坍塌。 +- **极致渲染性能**：绝不使用高开销的 SVG 滤镜（`feTurbulence`）或全屏 WebGL Canvas，确保承载数千行代码与终端滚动输出时维持 120fps 丝滑帧率。 -## Checks +--- -```powershell -npm run check:api -npm run typecheck -npm test -npm run build -npm audit --audit-level=low -``` +## English Overview + +Universal-Code Web Console is the desktop and web operator interface for Universal-Code, built with **React 18**, **TypeScript**, and **Vite**. + +### Quick Start +1. Run backend: `go run ./cmd/cyberagent api serve --listen 127.0.0.1:8765` +2. Run frontend: `npm ci && npm run dev` +3. Open `http://127.0.0.1:5173` (requests to `/api` are automatically proxied). + +### Key Features +- **Fluid Companion Dock**: A docked assistant panel alongside the main conversation stage without overlapping content. +- **Monaco Diff Viewer**: Line-by-line inspection and auditable rollback. +- **Pure CSS Apple Liquid Glass**: Acrylic blur and specular rim sheen with zero WebGL/SVG performance overhead. From 2fe206b8b7ad9d4189df501f1f6a2861eda71af3 Mon Sep 17 00:00:00 2001 From: Qiyuanqiii <267806965+Qiyuanqiii@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:18:38 +0800 Subject: [PATCH 2/2] =?UTF-8?q?=EF=BB=BFdocs:=20strip=20decorative=20emoji?= =?UTF-8?q?s=20from=20headings=20for=20professional=20typography?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove emoji prefixes across all section titles and lists in README.md, README.en.md, CONTRIBUTING.md, and web/README.md. - Maintain sober, clean, and developer-first documentation aesthetics. Co-authored-by: Google Gemini Code Assist Co-authored-by: Gemini Code Assist --- CONTRIBUTING.md | 16 ++++++++-------- README.en.md | 24 ++++++++++++------------ README.md | 24 ++++++++++++------------ web/README.md | 12 ++++++------ 4 files changed, 38 insertions(+), 38 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 54721a462..4faa0e49f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ --- -## 🛠️ 开发环境要求 +## 开发环境要求 在本地搭建开发环境前，请确保已安装以下基础工具： @@ -21,7 +21,7 @@ --- -## 💻 本地开发工作流 +## 本地开发工作流 ### 1. 检出仓库与准备依赖 @@ -88,7 +88,7 @@ export CYBERAGENT_API_CONTROL_TOKEN="local-control-token" --- -## 🔄 OpenAPI 契约与 DTO 代码生成 +## OpenAPI 契约与 DTO 代码生成 Universal-Code 以 **Go 结构体与路由定义作为 API 的唯一真相来源 (Single Source of Truth)**。 @@ -113,7 +113,7 @@ cd .. --- -## 🧪 运行测试与质量检查 +## 运行测试与质量检查 在提交 Pull Request 前，请确保相关测试均能本地通过： @@ -157,7 +157,7 @@ cd .. --- -## 🔐 敏感数据隔离与测试安全守则 +## 敏感数据隔离与测试安全守则 - **严禁提交机密凭据**：绝不要将真实 API Key、Bearer/Control Token、Cookie、`.env` 文件、真实的供应商请求日志或敏感数据提交到 Git 仓库。 - **本地临时数据隔离**：请勿将本地生成的 `.cyberagent-workbench/`、`cyberagent.db`、SQLite WAL 文件或 `build/`、`dist/` 产物提交到版本库中。 @@ -165,7 +165,7 @@ cd .. --- -## 📐 设计哲学与工程规范 +## 设计哲学与工程规范 1. **安全第一与最小特权原则**： - 所有的代码读写、终端命令执行和网络访问都具备明确的审计边界。 @@ -181,7 +181,7 @@ cd .. --- -## 🚀 提交 Pull Request (PR) +## 提交 Pull Request (PR) 1. 从 `main` 分支切出具名分支，例如： ```bash @@ -196,4 +196,4 @@ cd .. - **关键设计**：采用了什么样的架构思路。 - **验证方式**：在本地如何复现并验证了修复效果。 -再次感谢你为 Universal-Code 做出的贡献！🎉 +感谢你为 Universal-Code 做出的贡献。 diff --git a/README.en.md b/README.en.md index b3f60d847..029850ad0 100644 --- a/README.en.md +++ b/README.en.md @@ -28,17 +28,17 @@ --- -## 🌟 Highlights +## Highlights -- 🛠️ **Built for Local Repositories**: Read, inspect, and edit local codebases with built-in line-by-line diff inspection and auditable checkpoints (Rewind). -- 🛡️ **Transparent Permission Control**: Choose between read-only analysis, approval-gated runs, and automated Full Access. High-risk actions (file deletion, unlisted commands) always require manual confirmation. -- 🧠 **Ready for Any Model**: Native support for OpenAI, Anthropic Claude, DeepSeek, Kimi, local Ollama models, and custom OpenAI-compatible endpoints with on-the-fly model switching. Also supports quick browser-based **ChatGPT account sign-in**. -- 🔍 **Traceable Web Research**: Prioritizes provider-hosted native search, fetches GitHub Issues/PRs, Hacker News, and RSS/Atom feeds, and keeps source snapshots and citations. -- 💎 **Modern Liquid Glass Aesthetic**: Crafted with pure CSS optical refraction (macOS / VisionOS acrylic style), supporting Dark, Light, and Mist frosted themes at a responsive 120fps. +- **Built for Local Repositories**: Read, inspect, and edit local codebases with built-in line-by-line diff inspection and auditable checkpoints (Rewind). +- **Transparent Permission Control**: Choose between read-only analysis, approval-gated runs, and automated Full Access. High-risk actions (file deletion, unlisted commands) always require manual confirmation. +- **Ready for Any Model**: Native support for OpenAI, Anthropic Claude, DeepSeek, Kimi, local Ollama models, and custom OpenAI-compatible endpoints with on-the-fly model switching. Also supports quick browser-based ChatGPT account sign-in. +- **Traceable Web Research**: Prioritizes provider-hosted native search, fetches GitHub Issues/PRs, Hacker News, and RSS/Atom feeds, and keeps source snapshots and citations. +- **Modern Liquid Glass Aesthetic**: Crafted with pure CSS optical refraction (macOS / VisionOS acrylic style), supporting Dark, Light, and Mist frosted themes at a responsive 120fps. --- -## 🚀 Quick Start +## Quick Start ### Option 1: Download Pre-built Binaries @@ -68,7 +68,7 @@ go run ./cmd/cyberagent-desktop --- -## ⚙️ Connecting Models +## Connecting Models When opening the app or starting a new thread, click the model selector above the composer: @@ -84,7 +84,7 @@ When opening the app or starting a new thread, click the model selector above th --- -## 🖼️ Interface Preview +## Interface Preview | Light & Dark Split | Mist Frosted Glass | | :---: | :---: | @@ -94,7 +94,7 @@ Switch between **System, Light, Dark, and Mist** under **Settings → Appearance --- -## 📚 Documentation Index +## Documentation Index | Topic | Document | Description | | :--- | :--- | :--- | @@ -108,11 +108,11 @@ Switch between **System, Light, Dark, and Mist** under **Settings → Appearance --- -## 🤝 Contributing +## Contributing Contributions, issues, and feature requests are welcome! Check out our [Contributing Guide](CONTRIBUTING.md) to get started. -## 📄 License & Font Compliance +## License & Font Compliance - Distributed under the [Apache License 2.0](LICENSE). - **Third-party Font Notice**: The Chinese UI bundles HarmonyOS Sans Fonts licensed by Huawei Device Co., Ltd. The complete [font license](web/public/licenses/HarmonyOS-Sans.txt) is shipped with the app; see [font provenance and hashes](web/src/assets/fonts/PROVENANCE.md) for details. diff --git a/README.md b/README.md index 1ab35b7e2..953769ad2 100644 --- a/README.md +++ b/README.md @@ -28,17 +28,17 @@ --- -## 🌟 核心特性 +## 核心特性 -- 🛠️ **深度聚焦本地项目**：直接阅读、分析与修改本地代码库，内置 Diff 逐行审阅与可信撤销（Rewind / Checkpoints）能力。 -- 🛡️ **透明可控的安全策略**：支持只读分析、交互审批（Approval Mode）与全自动（Full Access）权限分级，高危操作（文件删除、非白名单命令）严格阻断并要求人工确认。 -- 🧠 **主流模型即开即用**：原生接入 OpenAI、Anthropic Claude、DeepSeek、Kimi、Ollama 本地模型与任何兼容 OpenAI 的第三方 API，支持单会话内即时热切，并支持通过系统浏览器快速完成 **ChatGPT 账户授权登录**。 -- 🔍 **真实来源的网络检索**：优先调用供应商原生搜索，支持直接抓取 GitHub PR/Issue、Hacker News 与 RSS/Atom 资讯，自动附带快照存证与引用出处。 -- 💎 **现代苹果液态玻璃美学**：采用纯 CSS 物理折射模型（macOS / VisionOS 亚克力液态玻璃风格），提供深色、浅色与雾透磨砂质感，兼具 120fps 极速渲染。 +- **深度聚焦本地项目**：直接阅读、分析与修改本地代码库，内置 Diff 逐行审阅与可信撤销（Rewind / Checkpoints）能力。 +- **透明可控的安全策略**：支持只读分析、交互审批（Approval Mode）与全自动（Full Access）权限分级，高危操作（文件删除、非白名单命令）严格阻断并要求人工确认。 +- **主流模型即开即用**：原生接入 OpenAI、Anthropic Claude、DeepSeek、Kimi、Ollama 本地模型与任何兼容 OpenAI 的第三方 API，支持单会话内即时热切，并支持通过系统浏览器快速完成 ChatGPT 账户授权登录。 +- **真实来源的网络检索**：优先调用供应商原生搜索，支持直接抓取 GitHub PR/Issue、Hacker News 与 RSS/Atom 资讯，自动附带快照存证与引用出处。 +- **现代苹果液态玻璃美学**：采用纯 CSS 物理折射模型（macOS / VisionOS 亚克力液态玻璃风格），提供深色、浅色与雾透磨砂质感，兼具 120fps 极速渲染。 --- -## 🚀 快速开始 +## 快速开始 ### 方式一：下载预编译客户端 @@ -68,7 +68,7 @@ go run ./cmd/cyberagent-desktop --- -## ⚙️ 模型配置与连接 +## 模型配置与连接 首次打开客户端或新建对话时，点击输入区上方的模型选择器进行配置： @@ -84,7 +84,7 @@ go run ./cmd/cyberagent-desktop --- -## 🖼️ 界面预览 +## 界面预览 | 浅色与深色对比 | 雾透磨砂玻璃 (Mist) | | :---: | :---: | @@ -94,7 +94,7 @@ go run ./cmd/cyberagent-desktop --- -## 📚 详细文档导航 +## 详细文档导航 | 领域 | 文档链接 | 描述 | | :--- | :--- | :--- | @@ -108,11 +108,11 @@ go run ./cmd/cyberagent-desktop --- -## 🤝 参与贡献 +## 参与贡献 欢迎提交 Issue 与 Pull Request！在开始开发前，请先阅读我们的 [贡献指南 (CONTRIBUTING.md)](CONTRIBUTING.md)。 -## 📄 开源许可证与字体合规 +## 开源许可证与字体合规 - 本项目基于 [Apache License 2.0](LICENSE) 协议开源。 - **第三方字体声明**：中文界面包含华为技术有限公司授权的 HarmonyOS Sans Fonts，完整 [字体许可文本](web/public/licenses/HarmonyOS-Sans.txt) 随软件一并分发；字体源文件与校验哈希详见 [字体出处说明](web/src/assets/fonts/PROVENANCE.md)。 diff --git a/web/README.md b/web/README.md index 5ef7aefbc..e92b939ac 100644 --- a/web/README.md +++ b/web/README.md @@ -4,7 +4,7 @@ --- -## 🛠️ 技术栈 (Tech Stack) +## 技术栈 (Tech Stack) - **核心框架**：React 18 + TypeScript + Vite - **代码与 Diff 编辑器**：Monaco Editor (本地离线打包，支持按需加载与 Proposal 恢复) @@ -14,7 +14,7 @@ --- -## 🚀 本地开发与联调模式 (Getting Started) +## 本地开发与联调模式 (Getting Started) ### 方式一：Vite 独立开发代理模式 (推荐日常前端开发) @@ -50,7 +50,7 @@ go run ./cmd/cyberagent api serve --listen 127.0.0.1:8765 --ui-dir web/dist --- -## 🖥️ 核心业务功能视图 (Key Views & Components) +## 核心业务功能视图 (Key Views & Components) | 核心视图 | 对应模块路径 | 功能说明 | | :--- | :--- | :--- | @@ -63,7 +63,7 @@ go run ./cmd/cyberagent api serve --listen 127.0.0.1:8765 --ui-dir web/dist --- -## 📁 目录结构 (Directory Layout) +## 目录结构 (Directory Layout) ```text web/ @@ -84,7 +84,7 @@ web/ --- -## 🧪 常用脚本与检查指令 +## 常用脚本与检查指令 | 命令 | 用途 | | :--- | :--- | @@ -97,7 +97,7 @@ web/ --- -## 💎 纯 CSS 视觉与设计规范 (Design Language) +## 纯 CSS 视觉与设计规范 (Design Language) - **纯 CSS 物理光学折射**：采用由 GreyD097 纯 CSS 方案启发的双向对角内阴影 (`inset 1.5px -1.5px` 与 `inset -1.5px 1.5px`)，在按钮和面板边缘模拟凸透镜全反射效果。 - **环境底光网格**：注入多点离散光场 (`--prayu-ambient-radial`) 搭配 `backdrop-filter: blur(34px) saturate(190%) contrast(102%)`，确保在深色模式下呈现透亮亚克力质感，杜绝普通黑底导致的色彩发灰坍塌。