@chen_hu_hu/pi-qq 1.3.3 → 1.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.3.5] - 2026-11-04
11
+
12
+ ### Added
13
+
14
+ - Reading a `SKILL.md` now renders a dedicated `## 🧩 Skill` block on QQ instead of a generic read tool; the file content is not forwarded.
15
+
16
+ ## [1.3.4] - 2026-11-04
17
+
18
+ ### Added
19
+
20
+ - `/status` now shows agent state, connection state, model/context, QQ user, battery (when available), and icons.
21
+ - `language` setting for `zh-cn` / `en-us`; user-facing text and logs are localized.
22
+ - Stable `msgKey` in structured logs for language-independent filtering.
23
+
24
+ ### Changed
25
+
26
+ - Default language is `zh-cn`.
27
+
10
28
  ## [1.3.3] - 2026-11-04
11
29
 
12
30
  ### Added
@@ -61,7 +79,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
61
79
  - Added thinking labels, per-tool icons, model-error recovery, and idle-safe session handling.
62
80
  - Reorganized modules by bounded context and updated settings and delivery documentation.
63
81
 
64
- [Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.3...HEAD
82
+ [Unreleased]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.5...HEAD
83
+ [1.3.5]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.4...v1.3.5
84
+ [1.3.4]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.3...v1.3.4
65
85
  [1.3.3]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.2...v1.3.3
66
86
  [1.3.2]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.1...v1.3.2
67
87
  [1.3.1]: https://github.com/CQ-Developer/pi-qq/compare/v1.3.0...v1.3.1
package/README-zh.md CHANGED
@@ -28,7 +28,7 @@ pi --extension /path/to/pi-qq
28
28
  2. 执行 `/qq-login`。
29
29
  3. 用手机 QQ 扫描二维码。
30
30
 
31
- 登录凭据只保存在进程内存中。重启 pi 后需要重新扫码。`/qq-logout` 会立即清除内存中的凭据。
31
+ 登录凭据不会写入配置文件。重启 pi 后需要重新扫码。`/qq-logout` 会立即清除凭据。
32
32
 
33
33
  ## 使用
34
34
 
@@ -89,7 +89,7 @@ Summarize this file.
89
89
  | ------------ | -------------------------------------- |
90
90
  | `/qq-login` | 扫码登录并绑定扫码的 QQ 用户 |
91
91
  | `/qq-status` | 显示登录、连接、模型、上下文和绑定用户 |
92
- | `/qq-logout` | 退出登录并清除内存中的凭据 |
92
+ | `/qq-logout` | 退出登录并清除凭据 |
93
93
  | `/qq-new` | 重置当前会话(由 QQ 侧 `/new` 调用) |
94
94
 
95
95
  QQ 侧命令:
@@ -120,15 +120,17 @@ QQ 侧命令:
120
120
  ```json
121
121
  {
122
122
  "thinkingRelay": true,
123
+ "language": "zh-cn",
123
124
  "logLevel": "silent"
124
125
  }
125
126
  ```
126
127
 
127
128
  | 配置项 | 默认值 | 说明 |
128
129
  | --------------- | ---------- | ------------------------------------------------------ |
129
- | `thinkingRelay` | `true` | 以 `💭 思考` 标题的纯文本回传思考;`false` 时隐藏 |
130
+ | `thinkingRelay` | `true` | 以本地化的 `💭` 标题纯文本回传思考;`false` 时隐藏 |
130
131
  | `deliverAs` | `"steer"` | 忙碌时新消息的排队方式:`steer` 或 `followUp` |
131
132
  | `fileMaxSize` | `52428800` | QQ 附件下载上限(字节,50MB) |
133
+ | `language` | `"zh-cn"` | UI 和日志语言:`zh-cn` 或 `en-us` |
132
134
  | `logLevel` | `"silent"` | 日志阈值:`silent`、`error`、`warn`、`info` 或 `debug` |
133
135
 
134
136
  配置在 pi 会话启动时读取;修改文件后请重启 pi。未知配置项会被忽略,无效值会回退到默认值并给出提示。
@@ -162,6 +164,7 @@ npm run format:check
162
164
  - 图片会保存为文件,并通过 pi 的 `read` 工具查看;当前模型必须支持图片输入才能看到内容。
163
165
  - 保存的附件位于工作区 `.pi/` 下;如有需要,请把 `.pi/` 加入你自己的项目 `.gitignore`。
164
166
  - QQ 对每条入站消息的被动回复次数有限制。可用 `/qq-test-budget` 查看本地额度。
167
+ - 读取 `SKILL.md` 时,QQ 显示 `## 🧩 Skill` 和 skill 名称,不转发文件内容。
165
168
 
166
169
  ## 许可证
167
170
 
package/README.md CHANGED
@@ -28,7 +28,7 @@ pi --extension /path/to/pi-qq
28
28
  2. Run `/qq-login`.
29
29
  3. Scan the QR code with mobile QQ.
30
30
 
31
- Credentials are kept in process memory only. Restarting pi requires scanning again. `/qq-logout` clears the in-memory credentials immediately.
31
+ Credentials are not written to `pi-qq.json`. Restarting pi requires scanning again. `/qq-logout` clears the credentials immediately.
32
32
 
33
33
  ## Usage
34
34
 
@@ -89,7 +89,7 @@ Run these in the pi terminal:
89
89
  | ------------ | ------------------------------------------------------ |
90
90
  | `/qq-login` | Log in with a QR code and bind the scanning QQ user |
91
91
  | `/qq-status` | Show login, connection, model, context, and bound user |
92
- | `/qq-logout` | Log out and clear in-memory credentials |
92
+ | `/qq-logout` | Log out and clear credentials |
93
93
  | `/qq-new` | Reset the current session (used by QQ `/new`) |
94
94
 
95
95
  QQ-side commands:
@@ -120,15 +120,17 @@ Create `~/.pi/agent/pi-qq.json` to override defaults. It stores settings only; c
120
120
  ```json
121
121
  {
122
122
  "thinkingRelay": true,
123
+ "language": "zh-cn",
123
124
  "logLevel": "silent"
124
125
  }
125
126
  ```
126
127
 
127
128
  | Key | Default | Description |
128
129
  | --------------- | ---------- | ------------------------------------------------------------ |
129
- | `thinkingRelay` | `true` | Relay thinking as plain text with a `💭 思考` header |
130
+ | `thinkingRelay` | `true` | Relay thinking as plain text with a localized `💭` header |
130
131
  | `deliverAs` | `"steer"` | Queue new messages while busy: `steer` or `followUp` |
131
132
  | `fileMaxSize` | `52428800` | QQ attachment download limit in bytes (50MB) |
133
+ | `language` | `"zh-cn"` | UI and log language: `zh-cn` or `en-us` |
132
134
  | `logLevel` | `"silent"` | Log threshold: `silent`, `error`, `warn`, `info`, or `debug` |
133
135
 
134
136
  Settings are read when a pi session starts; restart pi after editing the file. Unknown keys are ignored, and invalid values fall back to defaults with a warning.
@@ -162,6 +164,7 @@ The extension entrypoint is `index.ts`. Source modules are grouped by responsibi
162
164
  - Images are saved as files and read through pi's `read` tool; the current model must support image input to see them.
163
165
  - Saved attachments are workspace-local under `.pi/`; add `.pi/` to your own project `.gitignore` if needed.
164
166
  - QQ limits passive replies per inbound message. Use `/qq-test-budget` to inspect the local budget.
167
+ - Reading a `SKILL.md` is shown as a `## 🧩 Skill` block with the skill name; the file content is not forwarded to QQ.
165
168
 
166
169
  ## License
167
170
 
@@ -0,0 +1,427 @@
1
+ # `/status` 增强设计
2
+
3
+ > 状态:设计文档;已按执行计划实现
4
+ > 日期:2026-11-04
5
+ > 涉及版本:pi-qq 1.3.3
6
+ > 范围:QQ `/status` 与终端 `/qq-status`
7
+
8
+ ## 1. 需求
9
+
10
+ 1. **pi 执行状态**:执行中 / 已完成;
11
+ 2. **电脑电量**;
12
+ 3. **图标**:让状态行更易扫读;
13
+ 4. **中英文支持**:所有用户可见文字和日志消息支持 `zh-cn` 和 `en-us`;
14
+ 5. **语言配置**:通过配置项选择语言,不自动识别系统语言。
15
+
16
+ QQ `/status` 和终端 `/qq-status` 应保持一致。
17
+
18
+ ## 2. 现状分析
19
+
20
+ ### 2.1 命令入口
21
+
22
+ QQ 侧 `/status` 在 `src/qq/inbound-command.ts` 中处理:
23
+
24
+ ```ts
25
+ case "/status":
26
+ await reply(deps.getStatusLines().join("\n"));
27
+ break;
28
+ ```
29
+
30
+ 终端 `/qq-status` 在 `index.ts` 中处理:
31
+
32
+ ```ts
33
+ pi.registerCommand("qq-status", {
34
+ description: "pi-qq: show login, connection, and bound QQ user",
35
+ handler: async (_args, ctx) => {
36
+ ctx.ui.notify(getStatusLines(ctx).join("\n"), "info");
37
+ },
38
+ });
39
+ ```
40
+
41
+ 两处共用 `index.ts` 中的 `getStatusLines(ctx)`。
42
+
43
+ ### 2.2 当前字段
44
+
45
+ | 行 | 当前内容 | 数据来源 |
46
+ | -------------- | ----------------------------------------------------------------- | --------------------------- |
47
+ | `pi-qq status` | 固定标题 | 无 |
48
+ | `Login` | QR 登录,AppID 掩码 | `getLoginState()` |
49
+ | `Connection` | `stopped` / `starting` / `connected` / `reconnecting` / `blocked` | `lastState` + `stateDetail` |
50
+ | `Model` | 当前模型名 | `ctx.model` |
51
+ | `Context` | tokens / contextWindow / percent | `ctx.getContextUsage()` |
52
+ | `Bound user` | 绑定的 QQ openid | `getLoginState()` |
53
+ | `Settings` | 配置文件路径 | 固定字符串 |
54
+
55
+ ### 2.3 缺口
56
+
57
+ 1. **没有 agent 执行状态**
58
+ - `ctx.isIdle()` 已经存在,但状态行没有使用;
59
+ - `runFeedback.isQQRunActive()` 已经存在,可以区分 QQ 任务与本地任务。
60
+ 2. **没有电脑电量**
61
+ - 当前没有电池/电源采集代码;
62
+ - 状态构建函数是同步的,加入平台命令时要考虑阻塞和缓存。
63
+ 3. **没有图标**
64
+ - 当前 `/status` 是纯文本行;
65
+ - QQ 输出走普通文本消息,emoji 可以直接使用;工具/思考消息已经在用 emoji。
66
+ 4. **没有中英文支持**
67
+ - 当前所有命令回复、状态、错误提示都是硬编码英文;
68
+ - 没有统一文案表,也没有语言配置。
69
+ 5. **`Bound user` 显示完整 openid**
70
+ - 建议做掩码处理,和 AppID 保持一致。
71
+ 6. **信息层级偏平**
72
+ - 登录、连接、模型、上下文、绑定用户之间没有视觉区分。
73
+
74
+ ### 2.4 可用数据
75
+
76
+ - `ctx.isIdle()`:pi 当前是否空闲;
77
+ - `runFeedback.isQQRunActive()`:当前是否有 QQ 触发的 run;
78
+ - `lastState` / `stateDetail`:网关连接状态;
79
+ - `ctx.getContextUsage()`、`ctx.model`;
80
+ - Node 标准库的 `fs` / `child_process`:读取电量,无需新增依赖。
81
+
82
+ ## 3. 术语与需求确认
83
+
84
+ ### 3.1 执行状态的含义
85
+
86
+ - `running (QQ)`:pi 正在执行,当前 run 由 QQ 消息触发;输出会回传 QQ;
87
+ - `running (local)`:pi 正在执行,但 run 由终端/TUI/其他来源触发;输出不会回传 QQ;
88
+ - `completed`:pi 当前空闲,没有执行中的 run。
89
+
90
+ 区分 `QQ` / `local` 的价值:用户看到“正在执行但手机没有消息”时,可以判断是 QQ 任务还是本地任务。
91
+ 如果不需要这个粒度,统一显示 `running` / `completed` 即可。
92
+
93
+ ### 3.2 电脑电量
94
+
95
+ 已确认需求是“电脑电量”。展示:
96
+
97
+ - 电池百分比;
98
+ - 充电 / 放电 / 已接通电源。
99
+
100
+ **没有电池(台式机)或读取失败时,直接隐藏 Battery 行**,不显示 `unknown` / `desktop`。
101
+ 能返回 `/status` 本身就说明电脑在线,不需要额外展示在线状态。
102
+
103
+ ### 3.3 `QQ user` 是什么(原 `Bound user`)
104
+
105
+ `QQ user`(原 `Bound user`)是扫码登录时绑定的 QQ 用户 `openid`:
106
+
107
+ - 用于 allowlist,只接受这个用户的消息;
108
+ - 用于主动消息的默认目标;
109
+ - 不是 QQ 昵称,而是 QQ 开放平台提供的、按机器人隔离的用户标识。
110
+
111
+ 已确认把标签改为更直观的 `QQ user` / `QQ 用户`,并做掩码:
112
+
113
+ ```text
114
+ 👤 QQ user: openid-1…
115
+ ```
116
+
117
+ ### 3.4 图标选择
118
+
119
+ 已采用推荐组合:
120
+
121
+ | 字段 | 图标 / 状态 |
122
+ | ---------- | ---------------------------------------------------------------------- |
123
+ | 标题 | 🖥️ |
124
+ | Login | 🔐;未登录 ⚪ |
125
+ | Connection | 🌐 connected / 🔄 reconnecting / ⛔ stopped / 🚫 blocked / ⏳ starting |
126
+ | Agent | 🏃 running / ✅ completed |
127
+ | Model | 🧠 |
128
+ | Context | 📊 |
129
+ | QQ user | 👤 |
130
+ | Battery | 🔋 放电 / 🔌 充电 / ⚡ AC |
131
+ | Settings | ⚙️ |
132
+
133
+ Connection 使用网络/链路符号,Agent 使用动作/结果符号,避免两者都用黄绿圆点。
134
+
135
+ ## 4. 修改建议
136
+
137
+ ### 4.1 状态行设计
138
+
139
+ 英文示例:
140
+
141
+ ```text
142
+ 🖥️ pi-qq status
143
+ 🔐 Login: QR login (AppID abcd****)
144
+ 🌐 Connection: connected
145
+ 🏃 Agent: running (QQ)
146
+ 🧠 Model: claude-sonnet
147
+ 📊 Context: 12.3k/200k (6.2%)
148
+ 👤 QQ user: openid-1…
149
+ 🔋 Battery: 85% (discharging)
150
+ ⚙️ Settings: ~/.pi/agent/pi-qq.json
151
+ ```
152
+
153
+ 中文示例:
154
+
155
+ ```text
156
+ 🖥️ pi-qq 状态
157
+ 🔐 登录:扫码登录(AppID abcd****)
158
+ 🌐 连接:已连接
159
+ 🏃 执行:执行中(QQ)
160
+ 🧠 模型:claude-sonnet
161
+ 📊 上下文:12.3k/200k(6.2%)
162
+ 👤 QQ 用户:openid-1…
163
+ 🔋 电量:85%(放电中)
164
+ ⚙️ 设置:~/.pi/agent/pi-qq.json
165
+ ```
166
+
167
+ 空闲时:
168
+
169
+ ```text
170
+ ✅ Agent: completed
171
+ ⚡ Battery: 100% (AC)
172
+ ```
173
+
174
+ 没有电池时省略 Battery 行。
175
+
176
+ ### 4.2 执行状态
177
+
178
+ `getStatusLines(ctx)` 中增加:
179
+
180
+ ```ts
181
+ const agentRunning = ctx ? !ctx.isIdle() : runFeedback.isQQRunActive();
182
+ const agentLabel = !agentRunning ? "completed" : runFeedback.isQQRunActive() ? "running (QQ)" : "running (local)";
183
+ ```
184
+
185
+ - 使用 `ctx.isIdle()` 作为 pi 全局状态;
186
+ - 用 `runFeedback.isQQRunActive()` 区分 QQ 任务;
187
+ - `ctx` 为空时回退到 `runFeedback.isQQRunActive()`;
188
+ - 文案通过 i18n 表输出,不在代码中拼接中英文。
189
+
190
+ ### 4.3 电脑电量
191
+
192
+ 建议新增 `src/infra/power-status.ts`:
193
+
194
+ ```ts
195
+ export interface PowerStatus {
196
+ percent?: number;
197
+ state: "charging" | "discharging" | "ac";
198
+ }
199
+
200
+ export function getPowerStatus(): PowerStatus | undefined;
201
+ ```
202
+
203
+ - 返回 `undefined` 表示没有电池或读取失败,状态报告直接隐藏 Battery 行;
204
+ - **Linux**:读取 `/sys/class/power_supply/BAT*/capacity` 和 `/status`;
205
+ - **macOS**:解析 `pmset -g batt`;
206
+ - **Windows**:PowerShell `Get-CimInstance Win32_Battery`;
207
+ - **缓存**:结果缓存 30 秒,避免每次 `/status` 启动子进程;
208
+ - **失败处理**:异常静默返回 `undefined`,不能影响 `/status`;
209
+ - 不新增 npm 依赖。
210
+
211
+ 同步 vs 异步:
212
+
213
+ - 当前 `getStatusLines` 是同步函数;第一版建议同步读取 + 30 秒缓存;
214
+ - Linux 文件读取几乎无阻塞;macOS/Windows 子进程只在缓存过期时执行,并设置 500ms 超时;
215
+ - 如果后续发现阻塞明显,再改为异步并让 `/status`、`/qq-status` 都 `await`。
216
+
217
+ ### 4.4 提取纯格式化函数
218
+
219
+ 当前 `getStatusLines` 直接拼字符串,难以测试。建议提取:
220
+
221
+ ```ts
222
+ export interface StatusReportInput {
223
+ language: Language;
224
+ login?: { appId: string; openid: string };
225
+ connection: { state: BotState; detail?: string };
226
+ agent: { running: boolean; qq: boolean };
227
+ model?: { name: string };
228
+ usage?: ContextUsage;
229
+ power?: PowerStatus;
230
+ }
231
+
232
+ export function formatStatusReport(input: StatusReportInput): string[];
233
+ ```
234
+
235
+ 职责:
236
+
237
+ - `index.ts` 收集数据;
238
+ - `formatStatusReport()` 负责图标、标签、语言和格式;
239
+ - 单元测试覆盖所有状态组合;
240
+ - QQ `/status` 和终端 `/qq-status` 使用同一份输出。
241
+
242
+ ### 4.5 中英文与语言配置
243
+
244
+ 新增配置项:
245
+
246
+ ```json
247
+ {
248
+ "language": "zh-cn"
249
+ }
250
+ ```
251
+
252
+ 允许值:
253
+
254
+ - `"zh-cn"`:简体中文;
255
+ - `"en-us"`:英文。
256
+
257
+ 默认值:`"zh-cn"`。这是有意的行为变更:升级后默认中文;需要英文时配置 `"language": "en-us"`。
258
+
259
+ #### 覆盖范围
260
+
261
+ 所有**用户可见文字和日志消息**都应走文案表:
262
+
263
+ - QQ 命令回复:`/help`、`/status`、`/last`、`/stop`、`/compact`、`/new`、未知命令;
264
+ - QQ 错误和提示:附件失败、语音转写失败、unsupported message、模型错误;
265
+ - 状态行:登录、连接、执行状态、模型、上下文、QQ 用户、电量、设置;
266
+ - 流式输出:思考标题、工具失败标记、`(no output)` 等用户可见占位符;
267
+ - 终端 TUI:`/qq-status`、`/qq-login` 提示、连接状态通知、诊断命令;
268
+ - 状态细节 `stateDetail` 中的用户提示;
269
+ - pi-qq 自己写入的结构化日志消息。
270
+
271
+ 不翻译:
272
+
273
+ - 日志的 `scope`、字段名、级别等机器可读结构;
274
+ - 命令名(`/status`、`/stop`)和配置键;
275
+ - 第三方 SDK 返回的原始错误文本和原始日志(可保留英文原文)。
276
+
277
+ #### 实现建议
278
+
279
+ 新增 `src/infra/i18n.ts`:
280
+
281
+ ```ts
282
+ export type Language = "zh-cn" | "en-us";
283
+
284
+ export function configureI18n(language: Language): void;
285
+ export function getLanguage(): Language;
286
+ export function t(key: TranslationKey, params?: Record<string, string | number>): string;
287
+ ```
288
+
289
+ - 文案放在 `src/infra/i18n/en-us.ts` / `zh-cn.ts`;
290
+ - 使用类型化 key,缺少 key 时回退英文并在 debug 日志记录;
291
+ - `settings.ts` 增加 `language` 解析和校验,非法值回退默认并警告;
292
+ - `applyConfig()` / `session_start` 时调用 `configureI18n(settings.language)`;
293
+ - 图标不参与翻译,保持统一;
294
+ - 测试:两种语言、占位符、缺失 key 回退、非法配置回退。
295
+
296
+ #### 日志本地化
297
+
298
+ 日志也支持中英文,但保持机器可读结构:
299
+
300
+ - 新增稳定的 `msgKey` 字段,例如 `log.session.starting_bot`;
301
+ - `msg` 按当前 `language` 输出中文/英文;
302
+ - `scope`、`level`、时间、字段名保持英文/固定;
303
+ - pi-qq 自有日志消息通过统一消息表解析;现有调用继续传英文消息作为查找键;
304
+ - `file-logger` 在写入时解析消息表,同时写入 `msgKey` 和本地化后的 `msg`;
305
+ - 未命中的消息(SDK/动态内容)保持原文,不写 `msgKey`;
306
+ - `sdkLogger` 收到的 SDK 原文保持原样,不强行翻译;
307
+ - 语言切换只影响后续日志,已经写入的日志保持原语言;
308
+ - 默认语言是 `zh-cn`,因此未配置时日志消息也是中文;排障脚本应优先匹配 `scope` / `msgKey`,不要依赖 `msg` 文本。
309
+
310
+ 示例:
311
+
312
+ ```json
313
+ {
314
+ "time": "...",
315
+ "level": "info",
316
+ "scope": "session",
317
+ "msgKey": "log.session.starting_bot",
318
+ "msg": "正在启动机器人",
319
+ "appId": "...",
320
+ "allowedOpenid": "..."
321
+ }
322
+ ```
323
+
324
+ 如果现有日志消费方依赖英文 `msg`,需要把它们迁移到 `msgKey`;这是本方案的兼容性成本。
325
+
326
+ ### 4.6 隐私
327
+
328
+ `Bound user` 当前显示完整 openid。已确认改名为 `QQ user` / `QQ 用户`,并统一掩码,例如 `openid-1…`。
329
+ 如果排障需要完整值,只在日志中记录,不通过 QQ `/status` 展示。
330
+
331
+ ## 5. 执行计划
332
+
333
+ ### Phase 1:i18n 基础设施
334
+
335
+ 1. 新增 `src/infra/i18n.ts` 和中英文文案表;
336
+ 2. `settings.ts` 增加 `language`,默认 `zh-cn`,非法值回退并警告;
337
+ 3. 在会话启动时 `configureI18n()`;
338
+ 4. 补 settings/i18n 测试。
339
+
340
+ ### Phase 2:迁移用户可见文字与日志
341
+
342
+ 1. `/help`、`/status`、`/last`、`/stop`、`/compact`、`/new` 等命令回复;
343
+ 2. 附件失败、语音失败、unsupported message、模型错误;
344
+ 3. TUI 通知、`/qq-login` 提示、`/qq-status`;
345
+ 4. 流式输出的用户可见标题和占位符;
346
+ 5. pi-qq 自有的结构化日志消息迁移到 `msgKey` + 本地化 `msg`;
347
+ 6. 增加中英文快照测试和日志字段测试。
348
+
349
+ ### Phase 3:状态格式与 Agent 状态
350
+
351
+ 1. 新增 `src/qq/status-report.ts`;
352
+ 2. `index.ts` 收集登录、连接、agent、model、usage、power 等数据;
353
+ 3. `ctx.isIdle()` / `runFeedback.isQQRunActive()` 判断 `running (QQ)` / `running (local)` / `completed`;
354
+ 4. 接入图标和中英文文案;
355
+ 5. 测试所有状态组合。
356
+
357
+ ### Phase 4:电脑电量
358
+
359
+ 1. 新增 `src/infra/power-status.ts`;
360
+ 2. 实现 Linux/macOS/Windows 探测和 30 秒缓存;
361
+ 3. 无电池/读取失败返回 `undefined`,状态报告隐藏 Battery 行;
362
+ 4. 解析函数独立测试,不依赖当前机器。
363
+
364
+ ### Phase 5:接入、文档与验证
365
+
366
+ 1. 更新 `README.md` / `README-zh.md` 的 `/status`、`/qq-status` 和 `language` 配置;
367
+ 2. QQ `/status` 保持普通文本,不改成流式;
368
+ 3. 终端 `/qq-status` 继续使用 `ctx.ui.notify`;
369
+ 4. 手动验证中英文、执行中/已完成、电量/无电池、断线状态;
370
+ 5. 运行:
371
+
372
+ ```bash
373
+ npm run lint
374
+ npm run typecheck
375
+ npm test
376
+ npm run format:check
377
+ ```
378
+
379
+ ### 执行进度(2026-11-04)
380
+
381
+ - [x] i18n 基础设施、`language` 配置,默认 `zh-cn`
382
+ - [x] 用户可见文字迁移
383
+ - [x] pi-qq 自有日志消息本地化,新增 `msgKey`
384
+ - [x] 状态报告、执行状态、图标
385
+ - [x] 电量探测;无电池/失败时隐藏 Battery 行
386
+ - [x] QQ `/status` 与终端 `/qq-status` 共用格式化函数
387
+ - [x] 中英文、状态、电量、日志测试
388
+ - [x] README / CHANGELOG 更新
389
+ - [ ] 在手机 QQ 和终端 TUI 上做一次人工验收
390
+
391
+ 已知例外:
392
+
393
+ - 第三方 SDK 的原始日志和错误文本保持原文,不做翻译;
394
+ - 动态流式调试消息会按当前语言输出 `msg`,但没有稳定的 `msgKey`;
395
+ - 诊断探测中的底层文件名、命令名保留英文/原样。
396
+
397
+ ## 6. 变更文件
398
+
399
+ | 文件 | 变更 |
400
+ | ---------------------------------------- | --------------------------------------- |
401
+ | `src/infra/i18n.ts` | 语言类型、`t()`、中英文案表、日志消息表 |
402
+ | `src/infra/settings.ts` | 新增 `language` 解析与校验 |
403
+ | `src/infra/file-logger.ts` | 日志 `msgKey`、本地化 `msg` |
404
+ | `src/infra/power-status.ts` | 新增电量探测和缓存 |
405
+ | `src/qq/status-report.ts` | 新增纯格式化函数 |
406
+ | `index.ts` | 收集状态数据、初始化 i18n、调用格式化 |
407
+ | `src/qq/inbound-command.ts` | 命令回复走 i18n |
408
+ | `src/qq/qq-message-handler.ts` | 入站错误/提示走 i18n |
409
+ | `src/qq/qq-diagnostics.ts` | 诊断命令输出走 i18n |
410
+ | `src/attachments/attachment-failure.ts` | 附件失败文案走 i18n |
411
+ | `src/attachments/attachment-download.ts` | 下载错误文案走 i18n |
412
+ | `src/relay/stream-block-format.ts` | 思考/工具占位符走 i18n |
413
+ | `src/relay/stream-session.ts` | 流式调试日志走 i18n |
414
+ | `test/qq/status-report.test.ts` | 新增状态格式测试 |
415
+ | `test/infra/power-status.test.ts` | 新增电量解析测试 |
416
+ | `test/infra/i18n.test.ts` | 新增语言/回退测试 |
417
+ | `README.md` / `README-zh.md` | 状态与语言配置说明 |
418
+ | `CHANGELOG.md` | `[Unreleased]` 增加变更 |
419
+
420
+ ## 7. 已确认
421
+
422
+ 1. 保留 `running (QQ)` / `running (local)` 的区分。
423
+ 2. 默认语言为 `zh-cn`;需要英文时配置 `"language": "en-us"`。
424
+ 3. 日志也支持中英文;结构化字段保持稳定,新增 `msgKey`。
425
+ 4. `Bound user` 改名为 `QQ user` / `QQ 用户`。
426
+ 5. Connection / Agent 使用推荐图标:`🌐` / `🏃` / `✅`。
427
+ 6. 无电池或读取失败时隐藏 Battery 行。