You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by as...@apache.org on 2026/08/22 06:32:37 UTC
(maka) 01/01: docs: simplify CONTRIBUTING and let agents commit and push freely
This is an automated email from the ASF dual-hosted git repository.
Astro-Han pushed a commit to branch docs/contributing-simplify
in repository https://gitbox.apache.org/repos/asf/maka.git
commit 39d72a754e820771e7fcd19000c64c4f042c8de6
Author: AstroHan <le...@outlook.com>
AuthorDate: Sat Aug 22 14:13:49 2026 +0800
docs: simplify CONTRIBUTING and let agents commit and push freely
Cut both CONTRIBUTING files from ~200 lines to under 70:
- Drop the rule that agents may not use ASF credentials or push to ASF
repositories; only the final review and merge decision requires a
human.
- Point questions and early ideas at GitHub Discussions, which reaches
the team by email, alongside issues and pull requests.
- Drop the table of contents and merge Public decisions into Where to
start and Branch naming into Pull requests.
- Condense the attribution, review, and provenance sections to the
rules that actually change behavior.
- Drop the build-order diagram, the per-output desktop build block, and
the Runtime Host archive recipe; compress the requirements table to
one line and flatten the Developing subsections.
Generated-by: DeepSeek Harness (k3-256k)
---
CONTRIBUTING.md | 186 +++++---------------------------------------------
CONTRIBUTING.zh-CN.md | 169 +++++----------------------------------------
2 files changed, 36 insertions(+), 319 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f65e89cbe..1babcbe44 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,81 +2,29 @@
[](./CONTRIBUTING.zh-CN.md)
-- [Where to start](#where-to-start)
-- [Public decisions](#public-decisions)
-- [Human ownership and AI attribution](#human-ownership-and-ai-attribution)
-- [Review](#review)
-- [Provenance and licensing](#provenance-and-licensing)
-- [Quick start](#quick-start)
-- [Developing Maka](#developing-maka)
-- [Branch naming](#branch-naming)
-- [Pull requests](#pull-requests)
-
## Where to start
-These changes merge most readily:
-
-- Bug fixes
-- Model provider support — a new provider, or a fix to an existing one
-- Tests and stability work
-- Performance improvements
-- Documentation
-- Fixes for environment-specific problems
-
-For project direction, governance, or material product decisions, follow the public decision process below before implementing a change.
-
-Looking for something to pick up:
-
-- [`help wanted`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
-- [`good first issue`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [`bug`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
-- [`enhancement`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
-
-To claim one, say so in a comment and a maintainer may assign it to you.
-
-Prefer the **Bug report** or **Feature request** template when opening an issue —
-they ask for the context that makes one actionable. Report security problems through
-the private flow in [SECURITY.md](./SECURITY.md), never as a public issue.
+Bug fixes, model provider support, tests, performance work, and documentation merge most readily. Pick something up from [`help wanted`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) · [`good first issue`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) · [`bug`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3Abug) · [`enhancement`](https://github.com/ [...]
-## Public decisions
-
-Discuss project direction, governance, and material product decisions publicly before implementation, and record the reasoning. Project-level decisions belong on the development list, [`dev@maka.apache.org`](https://lists.apache.org/list.html?dev@maka.apache.org). Implementation-level technical decisions may be discussed in the pull request when the reasoning remains public and reviewable.
+Project direction, governance, and material product decisions are discussed publicly on [`dev@maka.apache.org`](https://lists.apache.org/list.html?dev@maka.apache.org) before implementation; implementation-level decisions may live in the pull request.
## Human ownership and AI attribution
-Every contribution must have a human contributor of record. That person reviews the work, decides to submit it, and accepts responsibility for its accuracy, provenance, licensing, and any applicable ICLA representations. Agents may prepare changes, but they may not use ASF credentials or push commits to ASF repositories.
-
-Disclose generative tooling when it makes a substantive contribution to code, documentation, analysis, or a project position. Disclosure is not required when a human determines the facts and position and the tool only translates, edits wording, autocompletes, or corrects spelling. Automated messages must identify themselves.
+Every contribution has a human contributor of record who reviews the work, decides to submit it, and owns its accuracy, provenance, and licensing. Agents may commit and push freely; the final review and merge decision always belongs to a human.
-Every pull request must state whether generative tooling made a substantive contribution. If it did, name the tool and briefly describe its scope. If it did not, explicitly state that no generative tool made a substantive contribution.
-
-When AI authors a material part of a contribution, Maka project policy requires the final commit on the target branch to name the tool:
-
-```text
-Generated-by: <tool>
-```
-
-Add the trailer to each pull request commit that contains material AI-authored content, and ensure it survives squash or amend in the final commit.
+Each pull request states whether generative tooling contributed substantively, naming the tool if so; translation, wording edits, autocomplete, and spelling correction don't count. Automated messages must identify themselves. When AI authors a material part of a contribution, add a `Generated-by: <tool>` trailer to the final commit and keep it through squash or amend.
## Review
-Every pull request to `main` needs at least one approving review from a committer other than the author, and the required `test` check must pass. Branch protection declared in [`.asf.yaml`](./.asf.yaml) enforces those mechanics, and a new commit dismisses the approvals already given. What GitHub cannot check is that the review is an independent human judgment; that part is project policy, and AI review does not count as independent human review. This is separate from the human contributo [...]
-
-A maintainer decides whether a change is material to user-visible behavior, public contracts, security, licensing, releases, or governance. Material changes do not merge on the mechanics alone: a maintainer also decides whether the review a change received is enough, and project direction, governance, and material product decisions go through the public decision process above before implementation. For everything else the baseline is enough. Tests, CI, documentation, and mechanical chang [...]
+Every pull request to `main` needs an approving review from a committer other than the author and a passing `test` check; branch protection in [`.asf.yaml`](./.asf.yaml) enforces both. The review must be an independent human judgment — AI review does not count. A maintainer decides whether a change is material and whether the review it received is enough.
## Provenance and licensing
-Submit only work that you have the right to contribute. Record third-party sources, licenses, and required attribution. Correctness review does not establish where content came from. For material AI-generated content, check the tool's output terms and scan non-trivial or suspicious output for third-party matches. Follow the current [ASF Generative Tooling Guidance](https://www.apache.org/legal/generative-tooling.html).
-
-By contributing you agree that your contributions are licensed under the [Apache License 2.0](./LICENSE).
+Submit only work you have the right to contribute, and record third-party sources, licenses, and attribution. Contributions are licensed under the [Apache License 2.0](./LICENSE); for material AI-generated content, follow the [ASF Generative Tooling Guidance](https://www.apache.org/legal/generative-tooling.html).
## Quick start
-| Requirement | Value |
-| --- | --- |
-| Node | `>=22.19.0` (`engines`, root `package.json`) |
-| npm | `11.19.0` (`packageManager`) |
-| Platform | macOS Apple Silicon for desktop work. Releases also ship an unsigned Windows x64 build and CI runs a non-blocking `windows_baseline` job, but Windows and Linux are not supported targets yet |
+Requires Node `>=22.19.0` and npm `11.19.0` (root `package.json`); desktop work needs macOS Apple Silicon.
```sh
git clone https://github.com/maka-agent/maka-agent.git
@@ -86,131 +34,33 @@ npm run build # builds every workspace in dependency order
npm --workspace @maka/core test
```
-Architecture is documented in [ARCHITECTURE.md](./ARCHITECTURE.md).
-
## Developing Maka
-### Running
-
```sh
npm run dev # desktop app with HMR
-npm run dev:full # full build, then launch the desktop app
-
-npm run cli:dev # TUI with the Maka Dev profile
-npm run cli:dev -- run "…" # one non-interactive turn
+npm run cli:dev # TUI; `npm run cli:dev -- run "…"` runs one non-interactive turn
+npm test # all workspaces, or: npm --workspace @maka/core test
```
-To exercise Desktop's remote Runtime Host setup with the current worktree, build the same
-self-contained package shape used for releases and opt the development app into that archive:
-
-```sh
-npm run release:cli:pack -- --allow-dirty
-MAKA_RUNTIME_HOST_SETUP_ARCHIVE="$PWD/packages/cli/release/<archive>.tgz" npm run dev
-```
+Building a single workspace only succeeds when its dependencies are already built — when unsure, build from the root. Tests run against compiled output in `dist/`; each workspace's `test` script cleans, builds, then runs `node --test`. Always go through it.
-The development app uploads the temporary archive over SSH. Packaged apps ignore this override.
-
-Evaluation commands and contracts live in [`packages/eval`](./packages/eval).
-
-### Building
-
-`npm run build` builds workspaces in dependency order:
-
-```
-code-mode → core → storage → mcp → runtime → runtime-host
- → computer-use → eval → maka-agent → ui → desktop
-```
-
-Building one workspace only succeeds when its dependencies are already built —
-`@maka/runtime` compiled against a stale `@maka/core` produces type errors that
-look like problems in the code you just wrote. When unsure, build from the root.
-
-The desktop app has four outputs; `build:test` covers the first three:
-
-```sh
-npm --workspace @maka/desktop run build:main # main process
-npm --workspace @maka/desktop run build:preload # preload bridge
-npm --workspace @maka/desktop run build:overlay # overlay windows
-npm --workspace @maka/desktop run build:renderer # renderer
-```
-
-### Testing
-
-Tests run against compiled output in `dist/`. Every workspace's `test` script
-cleans, builds, then runs `node --test`. **Always go through it** — calling
-`node --test` after a bare `build:*` executes orphaned artifacts from older
-trees, which fail on imports that no longer resolve.
+Before pushing, match CI locally:
```sh
-npm test # all workspaces
-npm --workspace @maka/core test # one workspace
-npm --workspace @maka/desktop run e2e # Playwright
-```
-
-### Before pushing
-
-CI runs these; matching them locally avoids a slow round trip.
-
-```sh
-npm run lint # biome lint
-npm run format:check # biome format — separate from lint; passing one proves nothing about the other
+npm run lint
+npm run format:check
npm run build
-npm run typecheck # 4 tsconfig projects for desktop, including renderer and storybook
+npm run typecheck
npx knip --workspace apps/desktop
npx knip --workspace packages/ui
```
-The CI job named `test` runs all of them as separate steps, so read which step
-failed rather than relying on the job name.
-
-## Branch naming
-
-```
-<type>/<description>
-```
-
-`<description>` is lowercase and hyphen-separated. `<type>` must be one of:
-
-| Prefix | Meaning |
-| --- | --- |
-| `feat` | New feature |
-| `fix` | Bug fix |
-| `refactor` | Behavior-preserving restructuring |
-| `test` | Test-only change |
-| `chore` | Build, dependency, and housekeeping work |
-| `perf` | Performance improvement |
-| `docs` | Documentation-only change |
-| `ci` | CI configuration and pipelines |
-| `build` | Build system and artifacts |
+Architecture is documented in [ARCHITECTURE.md](./ARCHITECTURE.md); evaluation commands and contracts live in [`packages/eval`](./packages/eval).
## Pull requests
-Opening a pull request pre-fills
-[`pull_request_template.md`](./.github/pull_request_template.md), which carries
-the required sections and the checklist. Fill it in rather than replacing it.
-
-**Title.** The repository squash-merges, so the title becomes the commit on
-`main`. Follow [Conventional Commits](https://www.conventionalcommits.org/):
-
-```
-<type>(<scope>): <summary>
-```
-
-`<type>` is the set in [branch naming](#branch-naming). `<scope>` is the
-workspace or area — `desktop`, `ui`, `runtime`, `eval`, `settings`,
-`runtime-host`, `storage`, `core`, `cli`, `deps`, `computer-use`, `scripts`,
-`release`, `windows`, `e2e`, `security`, and so on — `git log` shows the set
-in use.
-
-```
-fix(desktop): classify provider action errors from the unwrapped IPC message
-feat(runtime): decouple Swarm with asynchronous wakeups
-test(core): pin the shared validation corpus to every envelope value domain
-```
+Opening a pull request pre-fills [`pull_request_template.md`](./.github/pull_request_template.md); fill it in rather than replacing it.
-**UI changes.** Include before/after screenshots or a recording. A visual change
-cannot be judged from a diff.
+Branches and titles follow [Conventional Commits](https://www.conventionalcommits.org/): branches are `<type>/<description>`, titles are `<type>(<scope>): <summary>`. The repository squash-merges, so the title becomes the commit on `main`; `git log` shows the types and scopes in use.
-**Keep the description short and your own.** Long generated write-ups slow
-review down. Say what changed and why in your own words; if that needs many
-paragraphs, the pull request is probably too large.
+For UI changes, include before/after screenshots or a recording. Keep the description short and your own — if it needs many paragraphs, the pull request is probably too large.
diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md
index 20d8c1b11..ea9c722e4 100644
--- a/CONTRIBUTING.zh-CN.md
+++ b/CONTRIBUTING.zh-CN.md
@@ -2,79 +2,29 @@
[](./CONTRIBUTING.md)
-- [从哪里开始](#从哪里开始)
-- [公开决策](#公开决策)
-- [人类责任与 AI 归因](#人类责任与-ai-归因)
-- [审查](#审查)
-- [来源与许可](#来源与许可)
-- [快速开始](#快速开始)
-- [开发](#开发)
-- [分支命名](#分支命名)
-- [Pull Request](#pull-request)
-
## 从哪里开始
-下列类型的改动最容易被合并：
-
-- 缺陷修复
-- 模型供应商支持——新增一家，或修好已有的
-- 测试补强与稳定性改进
-- 性能优化
-- 文档
-- 环境相关问题的修复
-
-涉及项目方向、治理或重大产品决策时，请在实现前遵循下文的公开决策流程。
-
-想找活干，可以从这些标签入手：
-
-- [`help wanted`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
-- [`good first issue`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [`bug`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
-- [`enhancement`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
-
-想认领某个 issue，在下面留言，维护者可能会指派给你。
-
-提 issue 建议走 **Bug report** 或 **Feature request** 模板——它们会问出让一个 issue 可被处理所需的上下文。安全问题请走 [SECURITY.md](./SECURITY.md) 的私密流程，不要开公开 issue。
+缺陷修复、模型供应商支持、测试、性能优化和文档最容易被合并。想找活干，从 [`help wanted`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) · [`good first issue`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) · [`bug`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3Abug) · [`enhancement`](https://github.com/maka-agent/maka-agent/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement) 里挑一个，留言认领。提 [...]
-## 公开决策
-
-项目方向、治理和重大产品决策应在实施前公开讨论并记录理由。项目级决策在开发邮件列表 [`dev@maka.apache.org`](https://lists.apache.org/list.html?dev@maka.apache.org) 上进行。实现层面的技术决策可以在 PR 中讨论，前提是相关理由公开且可供审查。
+项目方向、治理和重大产品决策在实施前于开发邮件列表 [`dev@maka.apache.org`](https://lists.apache.org/list.html?dev@maka.apache.org) 上公开讨论；实现层面的技术决策可以在 PR 中讨论。
## 人类责任与 AI 归因
-每项贡献都必须有一名 human contributor of record。此人负责审阅工作、决定提交，并对其准确性、来源、许可和任何适用的 ICLA 声明负责。Agent 可以准备改动，但不得使用 ASF 凭据或向 ASF 仓库 push commit。
-
-生成式工具对代码、文档、分析或项目立场作出实质贡献时，必须披露。人类确定事实和立场后，工具仅做翻译、措辞整理、自动补全或拼写修正时，无需披露。自动发送的消息必须表明身份。
+每项贡献都有一名 human contributor of record：审阅工作、决定提交，并对准确性、来源和许可负责。Agent 可以自由 commit 和 push；最终的审查与合并决定始终由人做出。
-每个 PR 都必须说明生成式工具是否作出了实质贡献。如果是，应注明工具名称并简要说明其参与范围；如果不是，应明确说明没有生成式工具作出实质贡献。
-
-AI 创作了贡献中的实质部分时，Maka 项目政策要求在目标分支的最终 commit 中记录工具名称：
-
-```text
-Generated-by: <tool>
-```
-
-每个包含 AI 实质创作内容的 PR commit 都应添加该 trailer，并确保它在 squash 或 amend 后保留于最终 commit 中。
+每个 PR 说明生成式工具是否有实质贡献，有则注明工具名称；翻译、措辞整理、自动补全和拼写修正不算。自动发送的消息必须表明身份。AI 创作了贡献中的实质部分时，在最终 commit 加上 `Generated-by: <tool>` trailer，并确保它在 squash 或 amend 后保留。
## 审查
-向 `main` 提的每个 PR 都需要至少一位作者之外的 committer 给出 approval，并且必需的 `test` 检查通过。[`.asf.yaml`](./.asf.yaml) 里声明的分支保护强制执行这套机制，新推的 commit 会让已有的 approval 失效。GitHub 查不了的是这次审查是否出自独立的人工判断——那部分靠项目政策，AI review 不算独立人工审查。这与每项贡献都必须具备的 human contributor of record 是两回事。
-
-一个改动是否对用户可见行为、公开契约、安全、许可、发布或治理构成重大变更，由维护者认定。重大变更不能只凭这套机制过关：它已获得的审查够不够，同样由维护者认定；涉及项目方向、治理和重大产品决策的，还要先走上文的公开决策流程。其余改动，底线即足够。测试、CI、文档和机械修改不因文件类型而豁免。
+向 `main` 提的每个 PR 都需要一位作者之外的 committer 给出 approval，且必需的 `test` 检查通过；[`.asf.yaml`](./.asf.yaml) 的分支保护强制执行这套机制。审查必须出自独立的人工判断——AI review 不算。一个改动是否重大、获得的审查是否足够，由维护者认定。
## 来源与许可
-只提交你有权贡献的内容。记录第三方来源、许可和必要署名。正确性审查不能证明内容来源。对于 AI 生成的实质内容，应检查工具的输出条款；如果输出较大或来源可疑，还应扫描是否与第三方材料匹配。遵循当前的 [ASF 生成式工具指南](https://www.apache.org/legal/generative-tooling.html)。
-
-提交贡献即表示你同意你的贡献以 [Apache License 2.0](./LICENSE) 授权。
+只提交你有权贡献的内容，记录第三方来源、许可和必要署名。贡献以 [Apache License 2.0](./LICENSE) 授权；AI 生成的实质内容遵循 [ASF 生成式工具指南](https://www.apache.org/legal/generative-tooling.html)。
## 快速开始
-| 要求 | 值 |
-| --- | --- |
-| Node | `>=22.19.0`（根 `package.json` 的 `engines`） |
-| npm | `11.19.0`（`packageManager`） |
-| 平台 | 桌面端开发需要 macOS Apple Silicon。发版也会产出未签名的 Windows x64 构建，CI 有非阻塞的 `windows_baseline` job，但 Windows 和 Linux 目前还不是受支持的目标平台 |
+需要 Node `>=22.19.0` 和 npm `11.19.0`（见根 `package.json`）；桌面端开发需要 macOS Apple Silicon。
```sh
git clone https://github.com/maka-agent/maka-agent.git
@@ -84,116 +34,33 @@ npm run build # 按依赖顺序构建全部 workspace
npm --workspace @maka/core test
```
-架构说明见 [ARCHITECTURE.zh-CN.md](./ARCHITECTURE.zh-CN.md)。
-
## 开发
-### 运行
-
```sh
npm run dev # 带 HMR 的桌面应用
-npm run dev:full # 完整构建后启动桌面应用
-
-npm --workspace maka-agent exec -- maka # TUI
-npm --workspace maka-agent exec -- maka run "…" # 非交互地跑一个 Turn
+npm run cli:dev # TUI；`npm run cli:dev -- run "…"` 非交互地跑一个 Turn
+npm test # 全部 workspace，或：npm --workspace @maka/core test
```
-如需用当前工作区真实验证 Desktop 的远程 Runtime Host setup，可先构建与正式发布相同形态的
-自包含 package，再让开发版应用显式使用该 archive：
-
-```sh
-npm run release:cli:pack -- --allow-dirty
-MAKA_RUNTIME_HOST_SETUP_ARCHIVE="$PWD/packages/cli/release/<archive>.tgz" npm run dev
-```
+只有依赖都已构建好时，单独构建某个 workspace 才会成功——拿不准就从根目录构建。测试跑的是 `dist/` 里的编译产物；每个 workspace 的 `test` 脚本都会先清理、再构建，然后执行 `node --test`。务必走它。
-开发版应用会通过 SSH 上传这个临时 archive；正式打包应用会忽略该覆盖项。
-
-Eval 的命令与 contract 见 [`packages/eval`](./packages/eval)。
-
-### 构建
-
-`npm run build` 按依赖顺序构建各 workspace：
-
-```
-code-mode → core → storage → mcp → runtime → runtime-host
- → computer-use → eval → maka-agent → ui → desktop
-```
-
-只有依赖都已构建好时，单独构建某个 workspace 才会成功——拿过期的 `@maka/core` 去编译 `@maka/runtime`，产生的类型错误看起来会像是你刚写的代码有问题。拿不准就从根目录构建。
-
-桌面应用有四个产物，`build:test` 覆盖前三个：
-
-```sh
-npm --workspace @maka/desktop run build:main # 主进程
-npm --workspace @maka/desktop run build:preload # preload 桥接层
-npm --workspace @maka/desktop run build:overlay # overlay 窗口
-npm --workspace @maka/desktop run build:renderer # 渲染层
-```
-
-### 测试
-
-测试跑的是 `dist/` 里的编译产物。每个 workspace 的 `test` 脚本都会先清理、再构建，然后执行 `node --test`。**务必走它**——在裸跑 `build:*` 之后直接 `node --test`，执行的会是旧代码留下的孤儿产物，它们会在早已不存在的 import 上失败。
+推送前先在本地对齐 CI：
```sh
-npm test # 全部 workspace
-npm --workspace @maka/core test # 单个 workspace
-npm --workspace @maka/desktop run e2e # Playwright
-```
-
-### 推送前
-
-CI 会跑这些；本地先对齐可以省掉一轮漫长往返。
-
-```sh
-npm run lint # biome lint
-npm run format:check # biome format —— 与 lint 相互独立，过了一个不代表另一个也过
+npm run lint
+npm run format:check
npm run build
-npm run typecheck # desktop 有 4 个 tsconfig project，含 renderer 和 storybook
+npm run typecheck
npx knip --workspace apps/desktop
npx knip --workspace packages/ui
```
-CI 里名为 `test` 的 job 会把上面这些命令作为独立 step 依次执行，第一个失败会中止其余——要看是哪个 step 失败，别看 job 名字。
-
-## 分支命名
-
-```
-<type>/<描述>
-```
-
-`<描述>` 用小写，单词间以短横线分隔。`<type>` 只能是下列之一：
-
-| 前缀 | 含义 |
-| --- | --- |
-| `feat` | 新功能 |
-| `fix` | 缺陷修复 |
-| `refactor` | 不改变行为的重构 |
-| `test` | 仅测试改动 |
-| `chore` | 构建、依赖与杂项维护 |
-| `perf` | 性能优化 |
-| `docs` | 仅文档改动 |
-| `ci` | CI 配置与流水线 |
-| `build` | 构建系统与产物 |
+架构说明见 [ARCHITECTURE.zh-CN.md](./ARCHITECTURE.zh-CN.md)；Eval 的命令与 contract 见 [`packages/eval`](./packages/eval)。
## Pull Request
-开 PR 时会自动填充 [`pull_request_template.md`](./.github/pull_request_template.md)，
-其中已包含必填小节和检查清单。请在它的基础上填写，不要整段替换。
-
-**标题。** 本仓库用 squash 合并，标题会成为落到 `main` 上的提交信息。遵循 [Conventional Commits](https://www.conventionalcommits.org/)：
-
-```
-<type>(<scope>): <summary>
-```
-
-`<type>` 就是[分支命名](#分支命名)那一套。`<scope>` 是改动的 workspace 或区域——`desktop`、`ui`、`runtime`、`eval`、`settings`、`runtime-host`、`storage`、`core`、`cli`、`deps`、`computer-use`、`scripts`、`release`、`windows`、`e2e`、`security` 等——`git log` 里能看到实际在用的集合。
-
-```
-fix(desktop): classify provider action errors from the unwrapped IPC message
-feat(runtime): decouple Swarm with asynchronous wakeups
-test(core): pin the shared validation corpus to every envelope value domain
-```
+开 PR 时会自动填充 [`pull_request_template.md`](./.github/pull_request_template.md)；请在它的基础上填写，不要整段替换。
-**界面改动。** 请附改动前后的截图或录屏。视觉变化没法从 diff 判断。
+分支名和标题遵循 [Conventional Commits](https://www.conventionalcommits.org/)：分支是 `<type>/<描述>`，标题是 `<type>(<scope>): <summary>`。本仓库用 squash 合并，标题会成为落到 `main` 上的提交信息；`git log` 里能看到实际在用的 type 和 scope。
-**描述写短，用你自己的话。** 长篇的生成式说明会拖慢评审。用自己的话说清改了什么、为什么；如果这需要很多段落，多半是这个 PR 太大了。
+界面改动请附改动前后的截图或录屏。描述写短，用你自己的话——如果需要很多段落，多半是这个 PR 太大了。
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org