Skip to content

Commit 9158796

Browse files
westngwestng
committed
docs: enforce Chinese markdown documentation
Summary: - Make Chinese the only Markdown documentation language except README.en.md. - Update firmware release notes generation to use Chinese CHANGELOG content only. Details: - Convert CHANGELOG, license notes, compatibility matrix, and hook README files to Chinese-only content. - Keep README.en.md as the sole English Markdown document and update its changelog description. - Add bridge verification rules that reject obvious English Markdown sections outside README.en.md. - Update firmware CI verification for Chinese-only release-body generation.
1 parent adee144 commit 9158796

25 files changed

Lines changed: 202 additions & 273 deletions

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ This file is part of AgentLight.
6464
- Python：使用类型注解，结构化领域数据使用 dataclass/enum，4 空格缩进，导入路径不产生隐藏全局副作用。
6565
- Shell：使用 `set -euo pipefail`，变量必须加引号，仓库相对路径必须显式解析。
6666
- PowerShell：使用 `$ErrorActionPreference = "Stop"`，服务名必须带 `whalesky-labs-AgentLight` 前缀。
67-
- Markdown：中英双语内容并存时，中文在前。
67+
- Markdown：除 `README.en.md` 外，所有 Markdown 文档正文必须使用中文。
6868

6969
## 验证要求
7070

‎CHANGELOG.md‎

Lines changed: 3 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,10 @@
11
# CHANGELOG
22

3-
## 中文
4-
53
本文件记录 AgentLight 的版本发布说明。CI 构建 GitHub Release 时会读取本文件内容，并优先使用当前版本号对应的章节；如果没有找到对应章节，则使用 `Unreleased` 章节内容生成本次版本的发布说明。
64

7-
### Unreleased
5+
## Unreleased
86

9-
#### 新增
7+
### 新增
108

119
- 支持 ESP32-C3 SuperMini 固件构建。
1210
- 支持 USB Serial、Bluetooth LE、Wi-Fi HTTP 三种控制通道。
@@ -17,33 +15,8 @@
1715
- 支持 `v1.<Year>.<DayOfYear>+<BuildNumber>` CalVer 版本规则，并在 CI 自动模式下递增构建号。
1816
- 在 CI 中启用 Node.js 24 Actions 运行时，并将预览构建的版本更新说明输出到 Actions Summary。
1917

20-
#### 说明
18+
### 说明
2119

2220
- 默认 Wi-Fi AP：`WHALESKY-LABS-AGENTLIGHT`
2321
- 默认 Wi-Fi 密码：`agentlight`
2422
- 默认 BLE 名称：`WHALESKY-LABS-AGENTLIGHT`
25-
26-
## English
27-
28-
This file records AgentLight release notes. CI reads this file when building
29-
GitHub Releases. It first uses the section matching the current version; if no
30-
matching section exists, it uses the `Unreleased` section for the current build.
31-
32-
### Unreleased
33-
34-
#### Added
35-
36-
- Support ESP32-C3 SuperMini firmware builds.
37-
- Support USB Serial, Bluetooth LE, and Wi-Fi HTTP control channels.
38-
- Support solid, blinking, and breathing red / yellow / green light commands.
39-
- Support multi-agent status event normalization and background Agent services.
40-
- Support stable and preview CI builds, with firmware assets published directly to GitHub Releases.
41-
- Use the 4MB flash huge-app partition scheme so the USB, BLE, and Wi-Fi firmware fits the App partition.
42-
- Support the `v1.<Year>.<DayOfYear>+<BuildNumber>` CalVer rule, with CI-generated build numbers increasing automatically.
43-
- Enable the Node.js 24 Actions runtime in CI and print preview-build version notes to GitHub Actions Summary.
44-
45-
#### Notes
46-
47-
- Default Wi-Fi AP: `WHALESKY-LABS-AGENTLIGHT`
48-
- Default Wi-Fi password: `agentlight`
49-
- Default BLE name: `WHALESKY-LABS-AGENTLIGHT`

‎README.en.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -422,10 +422,10 @@ for ESP32-C3 SuperMini boards with 4MB flash. The single App partition is 3MB
422422
so the combined USB, BLE, and Wi-Fi firmware fits without removing control
423423
channels.
424424

425-
Release notes are maintained in [CHANGELOG.md](./CHANGELOG.md). CI reads the
426-
matching version section from both the Chinese and English changelog blocks; if
427-
no matching section exists, it uses each block's `Unreleased` section and
428-
appends the build channel, environment, Git commit, build time, and asset list.
425+
Release notes are maintained in the Chinese [CHANGELOG.md](./CHANGELOG.md). CI
426+
reads the matching version section; if no matching section exists, it uses the
427+
`Unreleased` section and appends the build channel, environment, Git commit,
428+
build time, and asset list.
429429
`manifest.json` includes the version, build channel, Git commit, SHA256 values,
430430
and flash offsets. When a `v*` tag is pushed, or when manual release publishing
431431
is enabled, CI creates a GitHub Release and uses the generated notes as the
@@ -457,4 +457,4 @@ It checks:
457457

458458
AgentLight is released under the [MIT License](./LICENSE), with SPDX identifier `MIT`.
459459

460-
A Chinese-first license explanation is available in [docs/license.md](./docs/license.md). The repository root [LICENSE](./LICENSE) file is authoritative.
460+
A Chinese license explanation is available in [docs/license.md](./docs/license.md). The repository root [LICENSE](./LICENSE) file is authoritative.

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -396,7 +396,7 @@ CI 会生成并发布这些独立资产，不再额外打包 zip：
396396

397397
固件使用 Arduino ESP32 内置的 `huge_app.csv` 分区方案，面向 4MB Flash 的 ESP32-C3 SuperMini，单个 App 分区大小为 3MB，用于容纳 USB、BLE、Wi-Fi 三通道一体固件。
398398

399-
`manifest.json` 包含版本、构建通道、Git 提交、SHA256 和烧录 offset。版本发布说明维护在 [CHANGELOG.md](./CHANGELOG.md)，CI 会分别读取中文和英文中当前版本号对应的章节；如果没有对应章节，则读取 `Unreleased` 章节，并自动追加构建通道、构建环境、Git 提交、构建时间和资产清单。推送 `v*` tag 或手动触发时勾选发布，会自动创建 GitHub Release 并把生成后的发布说明写入 Release body。
399+
`manifest.json` 包含版本、构建通道、Git 提交、SHA256 和烧录 offset。版本发布说明维护在 [CHANGELOG.md](./CHANGELOG.md)，CI 会读取当前版本号对应的中文章节；如果没有对应章节，则读取 `Unreleased` 章节，并自动追加构建通道、构建环境、Git 提交、构建时间和资产清单。推送 `v*` tag 或手动触发时勾选发布，会自动创建 GitHub Release 并把生成后的发布说明写入 Release body。
400400

401401
预览构建不会默认创建 GitHub Release，但 CI 会把从 `CHANGELOG.md` 读取并生成的 Release body 输出到构建日志和 GitHub Actions Summary，便于直接查看本次版本更新说明；该 Release body 只作为 CI 临时内容，不作为固件资产发布。
402402

‎docs/agent-platform-compatibility.md‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -15,21 +15,21 @@
1515

1616
| 平台 | supportMode | AgentLight 当前支持方式 | 证据文件 | 当前限制 |
1717
| --- | --- | --- | --- | --- |
18-
| Claude Code | `event-entrypoint-or-wrapper` | 统一事件入口 + hook/wrapper 文档 | `hooks/claude/README.md`、`hooks/agents/generic-wrapper.sh` | No automatic Claude configuration writes; permission handling remains in Claude Code. |
19-
| Codex CLI | `session-jsonl-monitor-and-event-entrypoint` | session JSONL 监听 + 统一事件入口 + wrapper 文档 | `scripts/codex-session-monitor`、`hooks/codex/README.md` | Session monitoring is read-only and depends on Codex local JSONL records. |
20-
| Codex Desktop | `session-jsonl-monitor-and-event-entrypoint` | session JSONL 监听 + 统一事件入口 | `scripts/codex-session-monitor`、`hooks/codex/README.md` | Does not control Codex Desktop UI; only observes visible local Codex session records. |
21-
| GitHub Copilot CLI | `generic-wrapper` | 通用 wrapper 入口 | `hooks/copilot/README.md`、`hooks/agents/generic-wrapper.sh` | No automatic ~/.copilot/hooks/hooks.json writes. |
22-
| Gemini CLI | `generic-wrapper-or-configurable-monitor` | 通用 wrapper 入口 + 可配置日志/命令监听 | `hooks/gemini/README.md`、`scripts/multi-agent-monitor`、`config/agent-monitors.example.json` | No automatic ~/.gemini/settings.json writes. |
23-
| Antigravity CLI | `generic-wrapper-or-event-entrypoint` | 通用 wrapper 入口 | `hooks/antigravity/README.md`、`hooks/agents/generic-wrapper.sh` | Status synchronization only; Antigravity terminal handles permission menus. |
24-
| Cursor Agent | `hook-template` | Cursor Hook 模板 | `hooks/cursor/README.md`、`hooks/cursor/hooks.json.snippet`、`hooks/cursor/agent-light.sh` | User must merge the snippet into Cursor hook configuration. |
25-
| CodeBuddy | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/codebuddy/README.md` | No automatic CodeBuddy configuration writes; permission handling remains in CodeBuddy. |
26-
| Kiro CLI | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/kiro/README.md` | No automatic Kiro agent configuration creation. |
27-
| Kimi Code CLI | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/kimi/README.md` | No automatic ~/.kimi/config.toml writes. |
28-
| Qwen Code | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/qwen/README.md` | No automatic ~/.qwen/settings.json writes; permission handling remains in Qwen. |
29-
| opencode | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/opencode/README.md` | No automatic opencode plugin configuration writes. |
30-
| Pi | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/pi/README.md` | Only synchronizes lifecycle/tool activity that can be connected through callbacks, logs, or wrappers. |
31-
| OpenClaw | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/openclaw/README.md` | Status synchronization only; no permission bubbles or terminal focus. |
32-
| Hermes Agent | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/hermes/README.md` | Only synchronizes lifecycle/tool activity that can be connected through callbacks, logs, or wrappers. |
18+
| Claude Code | `event-entrypoint-or-wrapper` | 统一事件入口 + hook/wrapper 文档 | `hooks/claude/README.md`、`hooks/agents/generic-wrapper.sh` | 不自动写入 Claude 配置；权限处理仍由 Claude Code 负责。 |
19+
| Codex CLI | `session-jsonl-monitor-and-event-entrypoint` | session JSONL 监听 + 统一事件入口 + wrapper 文档 | `scripts/codex-session-monitor`、`hooks/codex/README.md` | session 监听只读，依赖 Codex 本地 JSONL 记录。 |
20+
| Codex Desktop | `session-jsonl-monitor-and-event-entrypoint` | session JSONL 监听 + 统一事件入口 | `scripts/codex-session-monitor`、`hooks/codex/README.md` | 不控制 Codex Desktop 界面，只观察本地可见的 Codex session 记录。 |
21+
| GitHub Copilot CLI | `generic-wrapper` | 通用 wrapper 入口 | `hooks/copilot/README.md`、`hooks/agents/generic-wrapper.sh` | 不自动写入 `~/.copilot/hooks/hooks.json`。 |
22+
| Gemini CLI | `generic-wrapper-or-configurable-monitor` | 通用 wrapper 入口 + 可配置日志/命令监听 | `hooks/gemini/README.md`、`scripts/multi-agent-monitor`、`config/agent-monitors.example.json` | 不自动写入 `~/.gemini/settings.json`。 |
23+
| Antigravity CLI | `generic-wrapper-or-event-entrypoint` | 通用 wrapper 入口 | `hooks/antigravity/README.md`、`hooks/agents/generic-wrapper.sh` | 只同步状态；Antigravity 终端仍负责权限菜单。 |
24+
| Cursor Agent | `hook-template` | Cursor Hook 模板 | `hooks/cursor/README.md`、`hooks/cursor/hooks.json.snippet`、`hooks/cursor/agent-light.sh` | 需要用户自行把配置片段合并到 Cursor Hook 配置。 |
25+
| CodeBuddy | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/codebuddy/README.md` | 不自动写入 CodeBuddy 配置；权限处理仍由 CodeBuddy 负责。 |
26+
| Kiro CLI | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/kiro/README.md` | 不自动创建 Kiro Agent 配置。 |
27+
| Kimi Code CLI | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/kimi/README.md` | 不自动写入 `~/.kimi/config.toml`。 |
28+
| Qwen Code | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/qwen/README.md` | 不自动写入 `~/.qwen/settings.json`；权限处理仍由 Qwen 负责。 |
29+
| opencode | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/opencode/README.md` | 不自动写入 opencode 插件配置。 |
30+
| Pi | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/pi/README.md` | 只同步能够通过回调、日志或 wrapper 接入的生命周期和工具活动。 |
31+
| OpenClaw | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/openclaw/README.md` | 只同步状态，不提供权限气泡或终端聚焦。 |
32+
| Hermes Agent | `event-entrypoint-or-wrapper` | 统一事件入口 + 通用 wrapper 文档 | `hooks/hermes/README.md` | 只同步能够通过回调、日志或 wrapper 接入的生命周期和工具活动。 |
3333

3434
## Codex 状态监听
3535

‎docs/code-standards.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,3 +134,9 @@ Details:
134134
```
135135

136136
推送 GitHub 时必须使用本机 VPN 代理。
137+
138+
## Markdown 文档规范
139+
140+
- 除 [README.en.md](../README.en.md) 外，所有 Markdown 文档正文必须使用中文。
141+
- 技术专有名词、命令、文件名、路径、协议名和配置键可以保留英文原文。
142+
- CI 生成的 `release-body.md` 也必须是中文发布说明。

‎docs/license.md‎

Lines changed: 1 addition & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,10 @@ AgentLight 使用 MIT License 开源，SPDX 标识为 `MIT`。
44

55
完整协议原文见根目录 [LICENSE](../LICENSE)。当本文说明与 `LICENSE` 原文存在差异时，以 `LICENSE` 为准。
66

7-
## 中文说明
7+
## 协议说明
88

99
MIT License 是宽松型开源协议。你可以在遵守协议条件的前提下使用、复制、修改、合并、发布、分发、再授权或销售本项目的软件和文档。
1010

1111
使用或分发本项目时，需要保留版权声明和 MIT License 协议文本。
1212

1313
本项目按原样提供，不提供任何明示或暗示担保。作者或版权持有人不对因使用本项目产生的索赔、损害或其他责任负责。
14-
15-
## English
16-
17-
AgentLight is released under the MIT License, with the SPDX identifier `MIT`.
18-
19-
The full license text is available in the repository root [LICENSE](../LICENSE). If this explanation differs from the license text, the `LICENSE` file controls.
20-
21-
The MIT License is a permissive open source license. You may use, copy, modify, merge, publish, distribute, sublicense, or sell copies of this project's software and documentation, as long as the required copyright and license notices are preserved.
22-
23-
The project is provided as is, without warranties. The authors or copyright holders are not liable for claims, damages, or other liability arising from use of the project.

‎hooks/agents/README.md‎

Lines changed: 38 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,16 @@
1-
# Multi-Agent Integration
1+
# 多 Agent 接入说明
22

3-
AgentLight uses one normalized event entrypoint for all AI agents:
3+
AgentLight 为所有 AI Agent 提供一个统一的状态事件入口：
44

55
```bash
66
scripts/agentlight-event --agent <agent> --event <event>
77
```
88

9-
By default it only prints normalized status. Add `--send` or set
10-
`AGENTLIGHT_EVENT_SEND=1` to forward the event to `scripts/agentlight-gate` and
11-
then to the light.
9+
默认情况下，该命令只打印归一化后的状态。需要把事件继续发送到硬件灯时，增加 `--send`，或设置 `AGENTLIGHT_EVENT_SEND=1`，事件会进入 `scripts/agentlight-gate` 并转换为灯光状态。
1210

13-
## Supported Agent Names
11+
## 支持的 Agent 名称
1412

15-
| Agent | Accepted names |
13+
| Agent | 可接受名称 |
1614
| --- | --- |
1715
| Codex | `codex`, `codex-cli`, `codex-desktop` |
1816
| Claude Code | `claude`, `claude-code` |
@@ -29,55 +27,51 @@ then to the light.
2927
| Hermes | `hermes` |
3028
| Pi | `pi` |
3129

32-
## Normalized Events
30+
## 归一化事件
3331

34-
| Event | Meaning |
32+
| 事件 | 含义 |
3533
| --- | --- |
36-
| `prompt` | User prompt submitted |
37-
| `start` | Agent turn/task started |
38-
| `thinking` | Model reasoning or generating |
39-
| `tool` | Tool call, shell command, web search, or function call |
40-
| `typing` | Agent response text is being produced |
41-
| `done` | Turn/task completed successfully |
42-
| `waiting` | Permission, approval, or human input required |
43-
| `error` | Abort or failure |
44-
| `idle` | Agent is idle or ready |
45-
46-
## Examples
34+
| `prompt` | 用户提交提示词 |
35+
| `start` | Agent 回合或任务开始 |
36+
| `thinking` | 模型正在推理或生成 |
37+
| `tool` | 工具调用、Shell 命令、网页搜索或函数调用 |
38+
| `typing` | Agent 正在输出回复文本 |
39+
| `done` | 回合或任务成功完成 |
40+
| `waiting` | 等待权限、审批或用户输入 |
41+
| `error` | 中止或失败 |
42+
| `idle` | Agent 空闲或准备就绪 |
43+
44+
## 示例
4745

4846
```bash
4947
scripts/agentlight-event --agent codex --event task_started
5048
scripts/agentlight-event --agent claude-code --event tool_call --send
5149
scripts/agentlight-event cursor done
5250
```
5351

54-
## Hook Strategy
52+
## Hook 策略
5553

56-
Different tools expose different integration points:
54+
不同工具暴露的接入点不同：
5755

58-
- Tools with hooks should call `scripts/agentlight-event --agent <agent> --event <event> --send`.
59-
- Tools with JSONL session logs can be tailed by a monitor script, like `scripts/codex-session-monitor`.
60-
- Tools without stable hooks can use a wrapper script around the CLI process to at least emit `start`, `done`, and `error`.
56+
- 有 Hook 的工具，让 Hook 调用 `scripts/agentlight-event --agent <agent> --event <event> --send`。
57+
- 有 JSONL 会话日志的工具，用监听脚本读取，例如 `scripts/codex-session-monitor`。
58+
- 暂无稳定 Hook 的工具，可以用 wrapper 包住 CLI 进程，至少发出 `start`、`done`、`error`。
6159

62-
## Platform Notes
60+
## 平台说明
6361

64-
For the full compatibility matrix, see
65-
`docs/agent-platform-compatibility.md`.
62+
完整兼容矩阵见 `docs/agent-platform-compatibility.md`。
6663

67-
| Platform | Integration note |
64+
| 平台 | 接入说明 |
6865
| --- | --- |
69-
| Codex | `scripts/codex-session-monitor` supports local session JSONL monitoring. |
70-
| Cursor | `hooks/cursor/agent-light.sh` wraps Cursor hook events. |
71-
| Claude Code | Use native hooks when available, otherwise `generic-wrapper.sh`. |
72-
| Gemini CLI | Use `generic-wrapper.sh` unless a local hook/event stream is configured. |
73-
| Qwen Code | Use `generic-wrapper.sh` unless a local hook/event stream is configured. |
74-
| Copilot CLI | Use `generic-wrapper.sh` around the Copilot command. |
75-
| opencode | Use `generic-wrapper.sh` around the opencode command. |
76-
| Kimi / CodeBuddy / Kiro / Antigravity / OpenClaw / Hermes / Pi | Use the shared event entrypoint or wrapper until tool-specific hooks are connected. |
77-
78-
The project intentionally keeps platform adapters thin. AgentLight does not
79-
own or reimplement each AI tool; it normalizes their lifecycle events into a
80-
small status vocabulary that the firmware already understands.
81-
82-
AgentLight is a hardware status light project. It does not provide desktop pet
83-
animation, tray UI, dashboards, permission bubbles, or terminal focus.
66+
| Codex | `scripts/codex-session-monitor` 支持本地 session JSONL 监听。 |
67+
| Cursor | `hooks/cursor/agent-light.sh` 用于接收 Cursor Hook 事件。 |
68+
| Claude Code | 优先使用原生 Hook；没有 Hook 时使用 `generic-wrapper.sh`。 |
69+
| Gemini CLI | 没有本地 Hook 或事件流时使用 `generic-wrapper.sh`。 |
70+
| Qwen Code | 没有本地 Hook 或事件流时使用 `generic-wrapper.sh`。 |
71+
| Copilot CLI | 用 `generic-wrapper.sh` 包住 Copilot 命令。 |
72+
| opencode | 用 `generic-wrapper.sh` 包住 opencode 命令。 |
73+
| Kimi / CodeBuddy / Kiro / Antigravity / OpenClaw / Hermes / Pi | 接入专用 Hook 前，先使用统一事件入口或 wrapper。 |
74+
75+
本项目刻意保持平台适配层很薄。AgentLight 不拥有也不重新实现各个 AI 工具，只把它们可观察到的生命周期事件归一化为固件能够理解的少量状态。
76+
77+
AgentLight 是硬件状态灯项目，不提供桌面宠物动画、托盘界面、Dashboard、权限气泡或终端聚焦能力。

‎hooks/antigravity/README.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,21 @@
1-
# Antigravity Integration
1+
# Antigravity 接入说明
22

3-
Use the shared AgentLight event entrypoint:
3+
使用 AgentLight 统一事件入口：
44

55
```bash
66
scripts/agentlight-event --agent antigravity --event start --send
77
scripts/agentlight-event --agent antigravity --event tool --send
88
scripts/agentlight-event --agent antigravity --event done --send
99
```
1010

11-
Wrapper pattern:
11+
Wrapper 模式：
1212

1313
```bash
1414
/absolute/path/to/AgentLight/hooks/agents/generic-wrapper.sh antigravity antigravity "$@"
1515
```
1616

17-
If Antigravity exposes hooks or task lifecycle callbacks, call:
17+
如果 Antigravity 提供 Hook 或任务生命周期回调，让它调用：
1818

1919
```bash
2020
/absolute/path/to/AgentLight/scripts/agentlight-event --agent antigravity --event <event> --send
2121
```
22-

0 commit comments

Comments
 (0)