pi-language-coach 0.0.0-stage → 0.7.7

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 ADDED
@@ -0,0 +1,193 @@
1
+ # 更新日志
2
+
3
+ ## 0.7.7 (2026-11-16)
4
+
5
+ ### 变更
6
+
7
+ - **词语和语法改成按需显示,不再每句都凑。** 之前提示词要求「有难度的都要讲」,结果每句都硬塞 2–3 条,其中大量是 `fix`、`show`、`change`、`yet`、`whether` 这种你早就会的词,或者只是把整句复述一遍的语法点。现在两段都明确可选:没有值得学的词就给 `"words":[]`,没有值得讲的结构就省略整个 `grammar`,两者都没有时面板只显示英文。`Continue.`、`Hello.` 这类短句现在什么都不讲。
8
+ - **词语有了取舍标准,不再按数量凑。** 提示词写明哪些不讲:`fix`、`show`、`change`、`build`、`yet`、`whether`、`continue`、`bug`、`code`、`api`、`mock`、`input`、`log`、`test`、`data` 这类日常词和编程常用词;你已经用英文写过的词;从中文直译出来的长名词短语(`algorithm configuration`、`background outside the table` 这种);超过 3 个词的整段话。只讲 `popup`、`clickable`、`hardcoded`、`routing` 这种确实可能不会的。
9
+ - **中文词例外保留。** 输入里用中文写、英文里换成英文的那个词一定讲(输入「接口」、英文是 API 就讲 API)——那是你唯一真正不会写的词,不能被排除名单挡掉。
10
+ - **英语错误一定产出语法。** 其余情况语法可以省略,但输入里的英语有错时必须写,并把该错误放在第一条,这条规则优先于所有省略规则。
11
+
12
+ ### 提示词
13
+
14
+ - 从 931 字改为 1392 字,按「翻译/输出形状/可选项/词语/语法/纠错」六段组织。
15
+ - 真机 27 条固定样例 ×2 轮(同一批用例、同一模型),前后对比:
16
+
17
+ | | 两句都不讲 | 只有词语 | 只有语法 | 两者都有 | 词语总数 | 语法条数 |
18
+ | --- | --- | --- | --- | --- | --- | --- |
19
+ | 0.7.6 | 1 | 0 | 1 | 52 | 92 | 137 |
20
+ | 0.7.7 | 12 | 3 | 20 | 19 | 28 | 67 |
21
+
22
+ 10 句带英语错误的样例仍然 10/10 都产出了语法和纠正。两轮结果一致(每轮 6 句完全不讲),不是单次运气。
23
+
24
+ ## 0.7.6 (2026-11-16)
25
+
26
+ ### 变更
27
+
28
+ - **词语和语法各最多 3 条,一条一行、左边对齐。** 0.7.5 的词语最多 8 个,语法讲解挤成一句、纠错再接一句,读起来还是一段话。现在词语最多 3 个、语法最多 3 条,每条一句独立的话(模型返回 `explanations` 数组);标签只出现在第一行,后面的条目缩进到与第一个序号同一列,换行后的续行也对齐到该列:
29
+ ```
30
+ 词:1. meant 意思是「想说」
31
+ 2. cause 原因
32
+ 语法:1. 说「我说的不是这个」用 That's not what I meant 开头。
33
+ 2. 后面接分号和具体建议,把 meant 换成 said 也能表达同样意思。
34
+ 纠正:It's don't work → It doesn't work
35
+ ```
36
+ 存了收藏提示(`已收藏 · 语法:1. …`)时,后面的条目按提示宽度一起右移,序号仍然排成一列。
37
+ - **`纠正:` 单独一行、不占语法编号。** 它说的是这句话里改了什么,不是第三条「怎么说」,所以用与 `语法:` 等宽的前缀另起一行。
38
+ - **复习页同步。** `/coach review` 里词语与语法是有序列表(每条一行),`纠正:` 作为列表下方独立一行,不再被编成第 4 条。
39
+
40
+ ### 修复
41
+
42
+ - **旧收藏照常显示。** 0.7.4 及更早的记录只有一条 `explanation` 字符串,读取时按「一条」处理,不会因为缺 `explanations` 数组被跳过。
43
+ - **一条语法不合格不再拖累其余。** 校验按条进行:某条用了公式或与英文矛盾时只丢掉那一条,其余可读的仍显示;全部不合格才降级为只有英文。
44
+
45
+ ### 提示词
46
+
47
+ - 改成要求 `explanations` 数组(最多 3 条、每条不超过 50 字、一条讲一个点),词语改为「只挑最难的、最多 3 个」;总长 931 字。
48
+ - 真机 27 条固定样例 ×2 轮:完整讲解 53/54(0.7.5 为 50/54),平均每条语法 35 字(原 65 字),平均词语 1.7 个。
49
+
50
+ ## 0.7.5 (2026-11-16)
51
+
52
+ ### 变更
53
+
54
+ - **词语和语法一条一行、带序号。** 原来词语用 `·` 连成一行(`词:mocked 用假数据模拟的 · hard-coded 写死的`),条目一多就挤成一段、看不出每条在哪儿断开。现在每条各占一行并编号:`词:1. mocked 用假数据模拟的`、`2. hard-coded 写死的`;语法同理,讲解是第一条,纠错单独作为第二条 `2. 纠正:go → went`,不再用 `;纠正:` 接在讲解后面。标签只出现在每组第一行,缺哪部分就没有那几行。
55
+ - **译文前加 `英文:` 标签。** 原文、词语、语法都有标签,只有译文是一行裸文本;现在统一为 `英文:`,四行一眼能对上号。
56
+ - **复习页同样的排版。** `/coach review` 生成的页面里,英文上方多了「英文」小标签;词语与语法改成有序列表(浏览器自带 1. 2. 编号、每条一行),不再用「·」把多条挤成一段。
57
+
58
+ ### 修复
59
+
60
+ - **提示词按职责分段,并补上校验器已经在用的规则。** 原来 745 字挤成一段、约 40 条约束一路顿号连写,靠后的要求容易被模型漏掉。现在按「翻译/输出形状/words/grammar/纠错」分成五段,同时把三类此前只在校验器里、提示词没说的规则写明:`meaning` 不超过 20 字、`explanation` 不超过 100 字(超出会被判无效、整条语法丢掉),以及不用「动词 + 名词」这类带加号的公式(`usesFormula` 会拒绝;实测这一条把公式导致的语法丢失从 3/27 降到 1/27)。
61
+ - **模型写 `"correction": ""` 不再让整条语法失效。** 提示词要求「没有错误就省略 correction」,但模型有时写成空字符串,之前会被当成无效字段、整条语法降级为只剩英文。现在空字符串按「没有纠错」处理;类型不对(比如数字)仍然判为无效。
62
+
63
+ ## 0.7.4 (2026-11-16)
64
+
65
+ ### 变更
66
+
67
+ - **词语行单独占一行,语法行单独占一行。** 原来 `词:… | 语法:…` 挤在同一段里,词一多就把语法挤到中间、读起来找不到重点。现在最多四行:原文、英文、`词:…`、`语法:…`;缺哪部分就没有那一行(语法无效时不再补一句「未取得有效语法点」,只保留词语或英文)。
68
+ - **有难度的词都解释,上限从 3 提到 8。** 默认提示词要求逐个解释句中有难度的词和短语、按句中顺序、最多 8 个,跳过 it、this、code 这类基础词;`parseWords` 的硬上限相应放宽到 8,单条释义长度放宽到 60 字。
69
+ - **语法讲解改成「这类话英语怎么说」。** 默认提示词不再只要求「讲最值得讲解的语法点」(此前实际输出常是「用于询问完成某项任务的合适方法或步骤」这种只讲意思、不讲怎么说的句子),改为要求写清用哪个说法开头、后面接什么、把哪个词换掉就能表达别的意思,并用英文里的真实单词举例;同时不许用动名词、从句、不定式这类说法,改写成「后面接 explaining grammar 这样的 -ing 形式」。自定义 `promptFile` 不会自动更新。
70
+
71
+ ### 新增
72
+
73
+ - **错词和改后词用下波浪线标出。** 以前只有一行文字 `纠正:don't → doesn't`,两行英文本身没有任何标记,要肉眼比对才知道改了哪个词。现在原文行把错处(`don't`)标波浪线,英文行把改后写法(`doesn't`)也标出来;多处纠正(`go → went;discuss → discussed`)每个词都标。标记用 `\x1b[4m\x1b[4:3m`:认 SGR 4:3 的终端(Kitty、WezTerm、Ghostty、foot、iTerm2 等)画下波浪线,其余终端忽略这个未知参数、保留 `\x1b[4m` 的实线下划线,所以不会出现完全没标记的情况。标记只匹配整词、跟随换行重新起止,不改变可见宽度,也不进入收藏数据。
74
+
75
+ ### 修复
76
+
77
+ - **英文输入不再丢掉语法讲解。** 之前用 `pattern`(模型内部的公式字段)和中文讲解一起做公式校验:模型把 pattern 写成 `don't + 动词原形`、`be + 形容词` 这类形式时,即使中文讲解本身可读,整条语法点也会被判定无效,面板只剩「语法:未取得有效语法点;英文结果已保留。」。现在只校验实际显示的中文讲解,`pattern` 只作为收藏数据保留(面板和复习页都不显示它)。用真实模型跑 12 条英文输入:修复前 11/12 丢讲解,修复后 12/12 保留。
78
+ - **多处纠正不再整条丢失。** 英文输入有两处以上错误时,模型会写 `go → went; discuss → discussed`,之前只认“单个 A → B”,整行无法比对就整条丢弃,面板只剩讲解、没有「纠正:」。现在按 `;`/`;` 拆开逐对核对:只在原文和英文结果里都能找到的改动才保留,中文侧照旧丢弃,读起来是 `纠正:go → went;discuss → discussed`。
79
+ - **模型先叙述再输出 JSON 时不再整条失败。** 偶尔(实测约 1/3)模型会在 JSON 前先说一句「I'll inspect the working tree…」,之前会让整次学习请求报「学习响应格式无效」。现在会在回复里找出那个完整的 JSON 对象并继续解析,找不到或只找到截断的对象时仍然报错,不会把半截结果当成完整译文。
80
+
81
+ ## 0.7.3 (2026-11-13)
82
+
83
+ ### 变更
84
+
85
+ - **中英混合输入的教学提示词。** 默认提示词点明中英混合说明其中用中文写的词不会说:词语区优先讲这些词,meaning 在简短中文释义外附上这个说法怎么用的要点;语法区在中文片段较长时优先讲这个片段的完整英文说法。自定义 `promptFile` 不会自动更新。
86
+
87
+ ## 0.7.2 (2026-11-12)
88
+
89
+ ### 变更
90
+
91
+ - **粘贴图片的路径不再进入收藏和复习页。** 原文里的图片引用(粘贴截图得到的临时路径、Markdown 图片、HTML 图片标签、图片占位符、data URI)统一显示为 `「图片」`:面板的「原文:」行、收藏 JSON 和 `review.html` 都只保留标记,旧收藏在生成复习页时同样替换(原文件不改写)。手写的文件名和链接仍按原样保留,学习请求发送前仍会去掉全部路径、链接和图片引用。
92
+ - **中英混合输入的词语讲解。** 词语区优先讲用户用中文写的词,给出对应英文单词和简短中文释义(如输入 `I want to eat 西瓜`,讲解 `watermelon 西瓜`),不再只挑翻译结果里最值得讲的词;词语按英文里的原样拼写给出,避免 `retry` 这类说法因只存在于英文的变形形式而被丢弃。
93
+ - **英文输入的语法错误优先讲解。** 输入是英语且语法有误时,语法点优先讲这个错误本身,并照旧附上 `before → after` 纠错,而不是另选一个无关语法点。
94
+ - **重写默认教学提示词的顺序和纠错规则。** 写明输入是拼音输入法给编程助手发的消息,英文输入直接改错且大小写和标点不算错误;讲错误和填 correction 写在同一处,correction 只写最主要的一处改动涉及的几个词;excerpt 写明从英文结果而非输入复制;词语跳过基础词,讲解不用公式和较难术语。用真实模型各跑 27 条输入 × 2 次:英文有错时显示纠错从 3/12 升到约 9–12/12(两次对照之间有波动),保留下来的语法点从 21/54 升到约 40/54,不再出现讲大小写的语法点。自定义 `promptFile` 不会自动更新。
95
+ - **复习页改为宽屏多栏、单页整屏显示,滚轮静默累计翻页。** `review.html` 不再是一条 900px 窄栏:主区域放宽到 2100px,卡片按 340px 自动分栏(2000px 窗口 5 栏、1440px 3 栏、窄屏单栏),两侧空间被利用。每 10 条一页、**一次只显示一页**(`:target` 换页 + `overflow:hidden`,文档高度恒为一屏,两页内容绝不同屏);鼠标滚轮改为静默累计,累计约 400px(约 4 格滚轮)才翻页,不足时页面不动,反向同样生效;翻页带动画(旧页放大淡出、新页自 90% 缩放淡入,仅内容区域、分页栏不参与,`prefers-reduced-motion` 关闭);窄窗口页面超高时先页内滚动、到边缘才翻页。每页在右侧留白带一条自己的页码(只显示首尾与当前页附近共 5 个左右,`↑`/`↓` 翻页、点数字跳页,窄屏改为贴底横条),标题吸顶,右下角标「x / N」,内容在屏内垂直居中。卡片高度收敛:下限 236px,原文最多两行、英文最多六行,超出部分悬停显示完整文本、打印时全部展开并按页分页。**首次引入一段内联脚本**(滚轮计数器,无网络请求、无外部资源,CSP 仍 `default-src 'none'`;单页收藏不输出脚本),其余仍为纯 CSS 离线文件。
96
+
97
+ ### 新增
98
+
99
+ - **`/coach` 参数快捷选项。** 打字输入 `/coach ` 时会自动列出 `on`、`off`、`retry`、`clear`、`save`、`practice`、`review` 和 `autosave on`/`autosave off`,各项带一句中文说明;已输入前缀时只保留匹配项(不区分大小写),`autosave` 后的第二个词同样可补全;`↑`/`↓` 选择,`Tab` 或回车补成完整参数。未配置、未启用学习时同样可用,只影响输入补全。
100
+
101
+ ## 0.7.1 (2026-11-11)
102
+
103
+ ### 变更
104
+
105
+ - **精简默认翻译提示词。** 翻译根据上下文修正同音错别字,忽略图片、文件和链接占位符,按英语表达习惯调整语序,并由模型自行选择最值得讲解的单词和语法点。
106
+
107
+ ## 0.7.0 (2026-11-10)
108
+
109
+ 相对 0.6.0 的变化。
110
+
111
+ ### 新增
112
+
113
+ - **配置文件。** 新增 `~/.pi/agent/language-coach/config.json`:供应商、各供应商 key/地址/模型、思考档位、显示开关、超时和自定义提示词(`prompt` 内联或 `promptFile` 文件)都可以集中在这一个文件里,不再依赖 shell 环境变量。按字段逐项生效:环境变量 > config.json > 内置默认;文件缺失等价于未配置,格式错误会明确停用学习功能并指出文件。`promptFile` 相对于 language-coach 目录解析。
114
+
115
+ ## 0.6.0 (2026-11-10)
116
+
117
+ 相对 0.5.0 的变化。
118
+
119
+ ### 新增
120
+
121
+ - **面板显示可配置。** 新增 `PI_LANGUAGE_COACH_SHOW_ORIGINAL`(默认开启,关闭后译文上方不再显示「原文:」行)和 `PI_LANGUAGE_COACH_SHOW_PRACTICE`(默认开启,关闭后每个新结果不再自动弹出「输入一遍」练习框;`/coach practice` 手动打开不受影响)。两个开关只改显示,收藏内容不变。
122
+ - **教学提示词可配置。** 新增 `PI_LANGUAGE_COACH_PROMPT`(整体替换内置提示词)和 `PI_LANGUAGE_COACH_PROMPT_FILE`(从 UTF-8 文件读取,优先于 `PROMPT`)。替换后内置的格式要求不会自动保留;返回无法解析时面板仍保留可用部分。
123
+
124
+ ## 0.5.0 (2026-11-10)
125
+
126
+ 相对 0.4.0 的变化。
127
+
128
+ ### 新增
129
+
130
+ - **学习服务支持 DeepSeek 官方与 OpenAI Responses 中转站。** 新增 `PI_LANGUAGE_COACH_PROVIDER`(`minimax` 默认/`deepseek`/`h-self`),每个供应商用各自的作用域变量配置:deepseek 用 `…_DEEPSEEK_API_KEY`、`…_DEEPSEEK_BASE_URL`、`…_DEEPSEEK_MODEL`(默认 `deepseek-flash`,官方 `api.deepseek.com`,思考只有开/关,`low`/`medium`/`high` 均为开);h-self 用 `…_H_SELF_API_KEY` 等(默认 `gpt-5.6-luna`,OpenAI Responses 协议、固定 `store:false`,思考发送 `reasoning.effort`,`disabled` 为 `none`,`adaptive` 省略由服务默认)。minimax 沿用原有未加前缀的变量,旧配置不受影响,且永远不会被其他供应商读取;切换供应商只改 `PROVIDER` 后重启 Pi。两个新供应商都已用真实接口端到端验证(完整管线:请求 → 响应解析 → 语法/词语校验)。
131
+
132
+ ## 0.4.0 (2026-11-10)
133
+
134
+ 相对 0.3.0 的变化。
135
+
136
+ ### 新增
137
+
138
+ - **收藏阅读列表分页。** `/coach review` 超过 10 条时按每页 10 条分页,页面底部用「‹ 上一页 / 第 x / y 页 / 下一页 ›」切换;仍是单个自包含离线 HTML,分页仅靠 CSS(`:target` 配合 `:has()` 默认显示第一页)完成,不引入脚本、外部资源或服务器;10 条以内与旧版完全相同,打印时自动展开全部页并隐藏翻页栏。
139
+
140
+ ## 0.3.0 (2026-11-10)
141
+
142
+ 相对 0.2.0 的变化。
143
+
144
+ ### 修复
145
+
146
+ - **路径紧贴中文时吞掉正文。** 截图路径后直接接中文(如 `去掉/tmp/a.png上面的标题`)时,旧过滤把后面的中文一起删掉,导致译文只剩 `1.`、`2.` 或残句。现在路径不会延伸进中文和全角标点。
147
+ - 单段斜杠写法(`win/mac`、`前端/后端`、`/coach`)不再被当成路径删除。
148
+
149
+ ### 变更
150
+
151
+ - **默认模型切换为 MiniMax-M3.1-Flash,默认思考档位 medium。** 同形状请求实测(3 样例 × 4 轮):M3.1-Flash 加 `effort: medium` 中位延迟 3.5s(原 M3 adaptive 为 5.5s、M3.1-Flash adaptive 为 9.8s),思考 token 从约 400–2200 降到约 140–230,最稳定;单价也是 M3 的一半。此前用 M3 的用户无需改动,升级后自动获得新默认;显式设置过 `PI_LANGUAGE_COACH_MODEL`/`THINKING` 的环境以环境变量为准。
152
+ - **取消强制小写。** 译文和讲解按正常大小写显示,标识符保持原样(如 `InputNumber`);仍不把输入中的随手小写当成错误纠正。此前保存的收藏保持原来的小写。
153
+
154
+ ### 新增
155
+
156
+ - **思考档位可调。** `PI_LANGUAGE_COACH_THINKING` 在 `adaptive`/`disabled` 之外新增 `low`/`medium`/`high`:开自适应思考并附 `output_config: {"effort": "…"}` 限制思考深度;省略字段仍是关思考。M3 实测忽略 effort(仍只有开/关两档),M3.1-Flash 真实生效。
157
+ - **译文上方显示本次输入。** 结果面板第一行以 `原文:` 前缀原样显示本次提交的内容(多行输入压成一行,超宽自动换行),方便对照英文与讲解;发送给学习服务前仍会先把路径、链接和图片引用替换为标记,这行显示的始终是原始输入。
158
+ - **学习请求开启思考。** 新增 `PI_LANGUAGE_COACH_THINKING`(默认 `adaptive`):请求体带上 `thinking: {"type": "adaptive"}`,M3 回答前先推理歧义(实测如“快关门了”不再译成打烊),译文和语法讲解更准;设为 `disabled` 可换回更快响应。M3 只有开/关两档,不支持 budget/effort 档位,非这两档的取值直接判定配置无效。
159
+ - **超出宽度自动换行。** 英文和讲解不再固定两行、按 F9/F10 翻页,改为按终端宽度换行显示全部内容;移除 F9/F10 快捷键。
160
+ - **语法讲表达差异。** 语法点优先讲中英文说法不同的地方:时间、地点、原因的位置,长修饰放名词前还是后,英文需要补的 it/there、a/the、词尾,以及“是否、不是…而是、先…再、没有…”的英文说法。
161
+ - **第二行增加词语注释。** 面向英语基础较弱的使用者,每条结果最多解释 3 个可能不认识的词语或短语(如 `hard-coded 写死的`),显示在语法前;词语必须出现在英文中,重复或互相包含的条目会被去掉。语法点无效时仍显示词语。收藏和 `/coach review` 页面同步保存、展示词语。
162
+
163
+ ### 改进
164
+
165
+ - **移除内容改为标记。** 路径、链接、图片替换为 `「文件」`、`「链接」`、`「图片」`,译文能写成 “the title above the screenshot”,原内容仍不发送。
166
+ - **语法讲解允许基础术语。** 动词、名词、过去式、被动、完成时等可配合句中真实单词使用;较难术语和英文公式仍不使用。
167
+ - **提示词精简。** 系统提示词从约 9,100 字符缩到约 3,300 字符,每条要求只写一次,并附一个完整输出示例。
168
+ - **提示词按真实使用场景重写。** 说明输入是用拼音输入法给编程助手发的指令;明显同音错字按原意翻译,未知缩写不补全;编号列表逐条翻译。语法点优先讲中文母语者常错的语序、搭配和词尾,短回复给出更地道的说法并讲一个词的用法;用具体词替代语法术语的写法给出对照。
169
+ - **本地拦截错误讲解。** 讲解与译文词尾矛盾、引用译文中没有的介词搭配或问句开头、使用中英文语法公式或较难术语时,不显示这条语法,词语照常显示。
170
+
171
+ ## 0.2.0 (2026-11-10)
172
+
173
+ 相对 0.1.0 本地安装版的变化。
174
+
175
+ ### 变更
176
+
177
+ - **练习框不再占用快捷键。** F2 归还给 `@narumitw/pi-plan-mode`(问卷/自由讨论切换),消除启动时的 `Extension shortcut conflict` 警告。练习框保持默认自动出现(主编辑器无草稿时),回车或 Esc 关闭,`/coach practice` 重新打开(只开不关,已打开时仅提示)。
178
+ - **与外来编辑器组合而非让位。** 其他扩展(如 `@gomeen/pi-usage-bar` 的用量条编辑器)注册编辑器组件时,language-coach 把练习能力叠加到对方实例上:保留对方的类、草稿和装饰,练习关闭后恢复原样;注册顺序不影响结果。此前会让位导致练习框静默不出现。
179
+
180
+ ### 新增
181
+
182
+ - **学习请求过滤升级。** 发送给学习模型的正文在原有文件路径、文件名、链接基础上,进一步移除完整 Markdown 链接(含标签与引用定义)、图片引用(替代文字、HTML 图片/链接/picture 标签、data/blob URI、`[Image #1]` 占位符)和更多扩展名的文件名。附图输入只翻译剩余正文;过滤后无正文则不请求(含重试)。主模型收到的原始输入与附件保持不变。
183
+
184
+ ### 改进
185
+
186
+ - **译文风格。** 提示词要求按英语习惯调整语序和句式、像同事间日常消息而不是逐字直译或报告腔,同时保留 only/just/not yet 等限制与动作先后。
187
+ - **返回统一小写。** 所有返回英文字符串(含语法讲解里的英文示例)强制小写;小写是显示偏好,不作为纠错教学内容。
188
+ - **练习框交互。** 使用 Pi 原生多行编辑器(支持换行、光标移动、粘贴),不触发 Orca「需要输入」提醒;练习期间 F8 收藏、F9/F10 翻页和原生快捷键仍可用。
189
+
190
+ ### 修复
191
+
192
+ - 图片引用(`![alt](...)`)不再被误判为 Bash 命令而跳过翻译。
193
+ - 嵌套括号、带标题的 Markdown 链接等畸形输入不再破坏路径过滤。
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Pi Language Coach contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,322 @@
1
- # Temporary Holding Version
1
+ # Pi Language Coach
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 在 Pi 输入框上方显示刚提交提示词的英语表达,第一部分是英文,第二部分是词语和语法;超出终端宽度时自动换行:
4
+
5
+ ```text
6
+ don't implement anything yet; outline the goals and plan first.
7
+ 语法 “还没/先不”的 yet 放在句尾:implement anything yet。
8
+ ```
9
+
10
+ 中文、中英混合输入会按英语习惯调整语序、句式及分句,翻译成自然英文,不逐字直译;保留原意、限制和动作先后。提示词按“用拼音输入法给编程助手发指令”的场景理解术语,明显的同音错字(如“北京的间距”实为“背景”)按原意翻译,不认识的缩写原样保留。英文输入可以纠正语法和拼写,并用中文解释相关结构。英文按正常大小写显示(句首、I、专有名词和缩写大写,代码和标识符保持原样);你随手用小写输入英文不算错误,不会单独纠正大小写。原始提示词仍照常发给主模型,**不会替换成译文**。
11
+
12
+ 学习请求在后台独立调用 MiniMax,不等待它完成才开始主任务。教学规则、英文和语法不加入主对话上下文,也不写入会话记录。
13
+
14
+ ## 安装
15
+
16
+ 需要 Node.js **22.19+** 和 Pi。本扩展按 Pi package 标准分发,`package.json` 的 `pi.extensions` 声明入口 `src/index.ts`,不需要编译。
17
+
18
+ 下载或克隆本仓库后:
19
+
20
+ ```bash
21
+ # 使用仓库的真实绝对路径;本地安装直接引用该目录,请勿随后删除或移动。
22
+ pi install /absolute/path/to/pi-language-coach
23
+ ```
24
+
25
+ 重新启动 Pi,或在当前 Pi 会话运行 `/reload`。
26
+
27
+ 只试用一次,不写入安装配置:
28
+
29
+ ```bash
30
+ pi --extension /absolute/path/to/pi-language-coach/src/index.ts
31
+ ```
32
+
33
+ 卸载:
34
+
35
+ ```bash
36
+ pi remove /absolute/path/to/pi-language-coach
37
+ ```
38
+
39
+ 不需要把文件复制到 Pi 安装目录,也不要同时用多个方式加载同一扩展。Pi 提供扩展所需的宿主模块;仅运行扩展无需在本仓库安装开发依赖。
40
+
41
+ ## 配置 API key
42
+
43
+ **每位使用者必须自己配置学习请求的 key。扩展不读取 Pi 的 `auth.json`,不自动复用主模型密钥。**
44
+
45
+ 在启动 Pi 的同一个终端设置(用 `PROVIDER` 选供应商,每个供应商只读自己的 key 变量,可以在同一终端同时配置多个供应商,切换只改 `PROVIDER`):
46
+
47
+ ```bash
48
+ export PI_LANGUAGE_COACH_PROVIDER='h-self' # minimax(默认)| deepseek | h-self
49
+ export PI_LANGUAGE_COACH_API_KEY='填写你自己的 MiniMax key' # provider=minimax 时读取
50
+ export PI_LANGUAGE_COACH_DEEPSEEK_API_KEY='填写你自己的 DeepSeek key' # provider=deepseek 时读取
51
+ export PI_LANGUAGE_COACH_H_SELF_API_KEY='填写你自己的中转站 key' # provider=h-self 时读取
52
+ pi
53
+ ```
54
+
55
+ 缺少当前供应商的 key 时,主任务不受影响,学习面板保持隐藏,提示中会写明缺少哪个变量;deepseek 和 h-self 永远不会读 `PI_LANGUAGE_COACH_API_KEY`,旧的 minimax 变量也不会泄漏到其他供应商。
56
+
57
+ ### 配置文件(推荐:集中在一处)
58
+
59
+ 所有配置也可以写进一个 JSON 文件:`~/.pi/agent/language-coach/config.json`(与收藏目录同处,建议权限 600):
60
+
61
+ ```json
62
+ {
63
+ "provider": "h-self",
64
+ "thinking": "medium",
65
+ "showOriginal": true,
66
+ "showPractice": true,
67
+ "autoSave": true,
68
+ "timeoutMs": 30000,
69
+ "promptFile": "prompt.md",
70
+ "providers": {
71
+ "minimax": { "apiKey": "…", "baseUrl": "…", "model": "…" },
72
+ "deepseek": { "apiKey": "…", "baseUrl": "…", "model": "…" },
73
+ "h-self": { "apiKey": "…", "baseUrl": "…", "model": "…" }
74
+ }
75
+ }
76
+ ```
77
+
78
+ 所有字段均可省略(省略即用预设默认);`promptFile` 相对于 language-coach 目录解析,`prompt` 可直接内联文本,两者都不写则用内置提示词。优先级为:环境变量 > config.json > 内置默认,按字段逐项生效;文件不存在完全等价于未配置,格式错误会明确停用学习功能并指出文件。不需要 shell 环境变量的用户可以只用这一个文件。
79
+
80
+ PowerShell:
81
+
82
+ ```powershell
83
+ $env:PI_LANGUAGE_COACH_API_KEY = '填写你自己的 MiniMax key'
84
+ pi
85
+ ```
86
+
87
+ 不要把真实 key 提交到 Git、发送到聊天中,或写进扩展源码。本扩展不自动读取 `.env`。建议使用个人 shell 配置或密码管理器注入环境变量;如果直接执行含 key 的命令,要注意 shell 历史记录。
88
+
89
+ 环境变量在会话初始化时读取;修改后重新启动 Pi。缺少 key 时,主任务不受影响,学习面板保持隐藏,不占空行。
90
+
91
+ ### 供应商与模型
92
+
93
+ 学习模型固定,不跟随 `/model` 切换。`PI_LANGUAGE_COACH_PROVIDER` 选择内置供应商,每个供应商自带接口协议、默认地址和默认模型:
94
+
95
+ | Provider | 协议 | 默认地址 | 默认模型 | key 变量 | 地址 / 模型覆盖变量 |
96
+ | --- | --- | --- | --- | --- | --- |
97
+ | `minimax`(默认) | Anthropic Messages | `https://api.minimaxi.com/anthropic` | `MiniMax-M3.1-Flash` | `PI_LANGUAGE_COACH_API_KEY` | `PI_LANGUAGE_COACH_BASE_URL` / `PI_LANGUAGE_COACH_MODEL` |
98
+ | `deepseek` | OpenAI Chat Completions | `https://api.deepseek.com` | `deepseek-flash`(DeepSeek V4.1 Flash) | `PI_LANGUAGE_COACH_DEEPSEEK_API_KEY` | `PI_LANGUAGE_COACH_DEEPSEEK_BASE_URL` / `PI_LANGUAGE_COACH_DEEPSEEK_MODEL` |
99
+ | `h-self` | OpenAI Responses | `https://ai.yuchuantest.com/v1` | `gpt-5.6-luna` | `PI_LANGUAGE_COACH_H_SELF_API_KEY` | `PI_LANGUAGE_COACH_H_SELF_BASE_URL` / `PI_LANGUAGE_COACH_H_SELF_MODEL` |
100
+
101
+ `h-self` 预设按 OpenAI Responses 协议中转站接入,请求固定 `store: false`;指向其他 OpenAI 兼容中转站时改用各自的 `_BASE_URL` 覆盖变量即可。追加的路径由协议自动确定:`/v1/messages`、`/chat/completions`、`/responses`(deepseek 官方地址不带 `/v1`,中转站地址一般带)。默认使用实测速度最快的 **`MiniMax-M3.1-Flash`**(同形状请求延迟约为 M3 的一半,单价也是 M3 一半):
102
+
103
+ ```bash
104
+ export PI_LANGUAGE_COACH_MODEL='MiniMax-M3.1-Flash'
105
+ export PI_LANGUAGE_COACH_BASE_URL='https://api.minimaxi.com/anthropic'
106
+ ```
107
+
108
+ 早期默认为 `MiniMax-M3`(沿用 Pi 自定义配置的 `minimax-cn/MiniMax-M3[1M]`)。真实验证中,中国区接口以 HTTP 400 拒绝了 `MiniMax-M3[1M]`,而 `MiniMax-M3` 请求成功,因此曾显式修正;2026-11 又用同形状请求实测四组模型×思考档位后切换到 M3.1-Flash。直接请求不要加 `minimax-cn/` 前缀或未经服务支持的 `[1M]` 后缀。扩展仍不会在请求失败时偷偷换模型或回退到主模型;显式配置的 ID 会原样发送。
109
+
110
+ 国际区账号可显式设置:
111
+
112
+ ```bash
113
+ export PI_LANGUAGE_COACH_BASE_URL='https://api.minimax.io/anthropic'
114
+ export PI_LANGUAGE_COACH_MODEL='MiniMax-M3'
115
+ ```
116
+
117
+ 区域、账号、key、套餐、模型和接口必须匹配。扩展不会自动读取或迁移你在 Pi `models.json` 中的自定义地址、请求头或认证配置。
118
+
119
+ ### 思考档位
120
+
121
+ 默认 `PI_LANGUAGE_COACH_THINKING='medium'`:发送 `thinking: {"type": "adaptive"}` 让模型在回答前思考,并附 `output_config: {"effort": "medium"}` 限制思考深度。2026-11 用 3 个固定样例 × 4 轮实测:M3.1-Flash 加 `effort: medium` 后思考 token 从约 400–2200 降到约 140–230,中位延迟从 9.8s 降到 3.5s,且是最稳的组合(最差 6.9s);译文与讲解仍然完整有效。此实测仅为当次观察,不是延迟或质量承诺。
122
+
123
+ 接受值:`adaptive`(开思考,深度由模型自定)、`low` / `medium` / `high`(开思考并加 effort 上限)、`disabled`(关思考,请求中省略该字段)。注意:**M3 只有开/关两档**,实测忽略 `output_config.effort`,档位不改变其思考深度;若把 `PI_LANGUAGE_COACH_MODEL` 换回 M3,思考档位仅有 `adaptive` 与 `disabled` 有区别。无法关闭思考的模型会拒绝显式 `disabled`,因此关闭时扩展直接省略该字段。
124
+
125
+ 档位按协议映射:minimax 发送 `thinking: {"type":"adaptive"}` 加 `output_config.effort`;deepseek 的思考只有开/关(`thinking:{"type":"enabled"}` / `{"type":"disabled"}`),`low`/`medium`/`high` 都映射为开,与 Pi 的接入一致;OpenAI Responses 协议发送 `reasoning:{"effort":档位}`,`disabled` 发送 `effort:"none"`,`adaptive` 省略该字段(由服务端默认档位决定)。
126
+
127
+ ```bash
128
+ export PI_LANGUAGE_COACH_THINKING='medium' # 默认:思考开,深度中等
129
+ export PI_LANGUAGE_COACH_THINKING='disabled' # 关闭思考,换取更快响应
130
+ ```
131
+
132
+ 各地址覆盖变量是对应协议的根地址,不要带路径后缀(`/v1/messages`、`/chat/completions`、`/responses` 由扩展按协议追加);仅支持 HTTPS(本机 HTTP 用于测试),拒绝带 URL 账号、查询参数或 fragment 的地址,并且不跟随重定向。所有协议都用非流式请求。自定义地址会收到当前提示词和专用 key,请只使用可信服务。
133
+
134
+ ### 面板显示与练习框
135
+
136
+ 两个显示开关默认都开启,只改展示,不影响收藏内容(收藏始终包含完整原文(图片路径除外)、英文和语法):
137
+
138
+ ```bash
139
+ export PI_LANGUAGE_COACH_SHOW_ORIGINAL='false' # 不在译文上方显示「原文:」行
140
+ export PI_LANGUAGE_COACH_SHOW_PRACTICE='false' # 结果出来后不再自动弹出「输入一遍」练习框
141
+ ```
142
+
143
+ `SHOW_PRACTICE=false` 只关闭自动弹出;想练习时仍可运行 `/coach practice` 手动打开,回车或 Esc 关闭。
144
+
145
+ ### 自定义教学提示词
146
+
147
+ 不设置时使用内置教学提示词(要求返回固定 JSON:english、words、grammar)。可以完整替换:
148
+
149
+ ```bash
150
+ export PI_LANGUAGE_COACH_PROMPT='你自己的完整提示词'
151
+ # 或指向一个 UTF-8 文本文件(优先级高于 PROMPT):
152
+ export PI_LANGUAGE_COACH_PROMPT_FILE='/absolute/path/to/prompt.md'
153
+ ```
154
+
155
+ 替换是整体替换,内置提示词的格式要求(固定 JSON 形状、词语必须出现在英文中、语法点约束等)不会自动保留;若自定义提示词导致返回无法解析或缺少字段,面板会保留可用部分并标注缺失,不会报错中断主任务。路径需是本机可读的文本文件;读取失败时学习功能停用并在提示中说明。
156
+
157
+ ### 可选配置
158
+
159
+ | 环境变量(均可在 config.json 中以同名字段替代,环境变量优先) | 默认值 | 含义 |
160
+ | --- | --- | --- |
161
+ | `PI_LANGUAGE_COACH_PROVIDER` | `minimax` | 学习服务供应商:`minimax`、`deepseek`、`h-self`(OpenAI Responses 中转站) |
162
+ | `PI_LANGUAGE_COACH_API_KEY` | 无 | minimax 的独立学习 key;deepseek/h-self 不读这个变量 |
163
+ | `PI_LANGUAGE_COACH_DEEPSEEK_API_KEY` / `PI_LANGUAGE_COACH_H_SELF_API_KEY` | 无 | 对应供应商的独立学习 key |
164
+ | `PI_LANGUAGE_COACH_MODEL` | `MiniMax-M3.1-Flash` | minimax 的准确模型 ID;deepseek/h-self 用各自的 `…_DEEPSEEK_MODEL` / `…_H_SELF_MODEL` |
165
+ | `PI_LANGUAGE_COACH_THINKING` | `medium` | `adaptive`(开思考,深度模型自定)、`low`/`medium`/`high`(思考 effort 上限)、`disabled`(关思考);按协议映射(见上);M3 忽略档位 |
166
+ | `PI_LANGUAGE_COACH_BASE_URL` | `https://api.minimaxi.com/anthropic` | minimax 的 Anthropic 兼容根地址;deepseek/h-self 用各自的 `…_DEEPSEEK_BASE_URL` / `…_H_SELF_BASE_URL` |
167
+ | `PI_LANGUAGE_COACH_AUTO_SAVE` | `true` | 默认自动收藏有效英文结果;设为 `false` 或 `0` 可永久关闭(重启 Pi 后生效),仍可手动收藏 |
168
+ | `PI_LANGUAGE_COACH_TIMEOUT_MS` | `30000` | 单次学习请求超时,毫秒 |
169
+ | `PI_LANGUAGE_COACH_SHOW_ORIGINAL` | `true` | 译文上方是否显示「原文:」行 |
170
+ | `PI_LANGUAGE_COACH_SHOW_PRACTICE` | `true` | 每个新结果后是否自动弹出「输入一遍」练习框;`/coach practice` 不受影响 |
171
+ | `PI_LANGUAGE_COACH_PROMPT` | 内置提示词 | 整体替换教学提示词;输出仍须是约定 JSON 形状 |
172
+ | `PI_LANGUAGE_COACH_PROMPT_FILE` | 无 | 从 UTF-8 文件读取提示词,优先于 `PROMPT` |
173
+
174
+ ## 使用
175
+
176
+ 直接在 Pi 提交提示词即可,无需额外前缀。
177
+
178
+ - 原文(译文上方第一行):以 `原文:` 前缀显示本次提交的内容,方便对照译文;多行输入压成一行,超宽自动换行。只有粘贴图片的本地路径显示为 `「图片」`,其余文字(包括手写的文件名和链接)按原样显示;发送给学习服务前仍会先把路径、链接和图片引用替换为标记。
179
+ - 英文:以 `英文:` 前缀显示英文翻译或纠正后的英文,与「原文:」「词:」「语法:」用同一套标签。
180
+ - 讲解**按需显示**,不是每句都有:词语组和语法组各自可选,一句话没有值得学的词就没有词语行,没有值得讲的结构就没有语法行,两者都没有时只显示英文(`Continue.`、`Hello.` 这类短句通常什么都不讲)。有内容时,英文下方一个词一行、一条语法一行,按 `1.` `2.` `3.` 编号,最多各 3 条。**词语组**只讲真可能不会的词或固定说法,最多 3 个,按句中先后顺序:`fix`、`show`、`change`、`build`、`yet`、`whether`、`continue`、`bug`、`code`、`api`、`mock`、`input`、`log`、`test`、`data` 这类日常词和编程常用词不讲,你已经用英文写过的词不讲,从中文直译出来的长名词短语(如 `algorithm configuration`)不讲,超过 3 个词的整段话不讲;只有 `popup`、`clickable`、`hardcoded`、`routing` 这种才讲。**唯一例外**是用中文写的词——输入里写「接口」、英文是 API 时一定讲 API,因为那正是你不会写的词。**语法组**讲这类话英语怎么说——最多 3 条,每条一句独立的话(用哪个说法开头、后面接什么、能换哪个词),并用英文里的真实单词举例(如「用 How should I 开头,后面接动词原形」「把 test 换成 debug 就能问怎么调试」),不写成「用于询问……」这种只讲意思的说明;输入是英语且用错时,这条错误一定放在第一条(这是唯一不省略语法的情况)。面板形如:
181
+
182
+ ```
183
+ 原文:我说的不是这个,先看原因
184
+ 英文:That's not what I meant; let's look at the cause first.
185
+ 词:1. meant 意思是「想说」
186
+ 2. cause 原因
187
+ 语法:1. 说「我说的不是这个」用 That's not what I meant 开头。
188
+ 2. 后面接分号和具体建议,把 meant 换成 said 也能表达同样意思。
189
+ 纠正:It's don't work → It doesn't work
190
+ ```
191
+
192
+ 标签只在每组第一行出现(`词:1. …`、`语法:1. …`),后面的条目缩进到与第一个序号同一列,换行后的续行也对齐到该列,所以序号始终排成一列、不会回到最左边。词语必须出现在英文中(用英文里的原样拼写);语法讲解可以用动词、名词、过去式、被动这类基础术语,但要配上句中的真实单词,不用“宾语从句”这类较难术语或 `don't + adverb + base verb` 这类公式。英文原句有错误时才附上一行 `纠正:`——它单独占一行、不参与语法编号(它是这句话里的事实,不是第三条「怎么说」):`纠正:go → went`(多处错误列成 `纠正:go → went;discuss → discussed`,每一处都必须在原文和英文结果里逐字出现)。改动的词会在两行英文上用**下波浪线**标出:原文行标 `don't` 这类错处,英文行标 `doesn't` 这类改后写法,一眼能看到改了什么;用的是 `\x1b[4m\x1b[4:3m`,认波浪线的终端(Kitty、WezTerm、Ghostty、foot、iTerm2 等)画波浪线,其余终端忽略未知参数、保留实线下划线,不会出现「错词完全没标记」的情况;标记在换行处会重新起止,不影响行宽计算和复制。语法点无效时仍显示词语。模型生成仍可能不准确,不能保证每次都符合要求。
193
+ - **只有取得英文结果才显示面板**。请求中、跳过、请求失败、未配置、未提交、清空或关闭时完全移除面板,不显示提示文字、不保留占位空行。
194
+ - 不增加标题、边框、状态栏或空白行。
195
+ - 长原文、译文与讲解保留完整文本,超出终端宽度时自动换行显示,不需要翻页。长输入的结果会占用更多行。
196
+ - 不再按本地字符数跳过长提示词,也不截断原文。模型本身仍有上下文和最多 32768 输出 token 等服务限制;超限或未完成会隐藏结果,不冒充完整译文。响应读取保留 1 MiB 安全上限。
197
+ - 默认在获得有效英文后自动保存原文、完整英文、词语注释和可用语法(不要求语法有效);内容去重,生成中、失败、被取消、跳过和旧响应不保存。关闭自动收藏后仍可手动保存。
198
+
199
+ ### 命令
200
+
201
+ | 命令 | 作用 |
202
+ | --- | --- |
203
+ | `/coach` | 清除当前显示;命令用法见此表,不显示状态占位 |
204
+ | `/coach on` | 开启后续输入的自动学习,无结果时仍隐藏面板 |
205
+ | `/coach off` | 取消学习请求、清除内存内容并隐藏面板 |
206
+ | `/coach retry` | 重试最近一条可处理的提交,仅请求学习模型,不重发主提示词 |
207
+ | `/coach clear` | 取消学习请求、清除内存内容并隐藏面板,保持开关状态;不删除已收藏文件 |
208
+ | `/coach save` | 收藏当前原文、完整英文、词语注释与有效语法;等同于按 `F8` |
209
+ | `/coach practice` | 输入一遍:在讲解下方打开输入区,照着英文敲一遍,回车退出 |
210
+ | `/coach review` | 用浏览器打开本机收藏阅读列表,不需要 API key |
211
+ | `/coach autosave off` | 在当前 Pi 运行期间关闭自动收藏,不影响手动收藏 |
212
+ | `/coach autosave on` | 在当前 Pi 运行期间重新开启自动收藏;不追溯收藏此前结果 |
213
+
214
+ 命令不改动正在编辑的草稿。打字输入 `/coach ` 时会自动列出下面这些快捷选项,每项带一句说明:不输入参数时列出全部子命令(超过一屏时默认只显示 5 条,并标出「(1/9)」这类计数);已输入前缀时只保留匹配项(不区分大小写),`autosave` 后的第二个词同样可补全;`↑`/`↓` 选择,`Tab` 或回车补成完整参数。列表被 `Esc` 关掉后要再输入一个字符才会重新出现,这是 Pi 的触发策略;参数前缀不匹配时列表直接收起。`autosave` 命令在当前 Pi 运行期间生效,切换会话不重置;重新加载扩展后由 `PI_LANGUAGE_COACH_AUTO_SAVE` 环境变量决定;其他开启状态也不跨重启保存。连续提交时取消旧请求,只有最新提交的结果能更新面板;新会话、切换会话、重载、退出和会话树切换会清理旧学习状态。
215
+
216
+ ### 输入一遍
217
+
218
+ 学习结果出现时,若主编辑器没有草稿,练习输入区**默认自动出现**,位于讲解下面;若已经在写下一条提示,则不自动切走焦点,之后可用 `/coach practice` 手动打开:
219
+
220
+ - 上面是原文、英文和讲解,下方是与 Pi 正常提示词输入区同款的多行编辑框,带上下边框,支持自动换行、光标移动和粘贴。上边框标注「输入一遍」,下边框提示退出按键。照着英文敲一遍,敲完回车即退出——主动产出比只读一遍记得牢。
221
+ - **不做任何校验**:输入对不对由你自己对照英文。不请求任何模型、不联网、不写入收藏文件,也不进入主对话上下文。
222
+ - **回车或 Esc 关闭输入区**,恢复讲解和正常编辑器;关闭前后你正在编辑的草稿都会保留。练习没有专用快捷键(避免与其他扩展冲突,例如 Plan 模式的 F2),关闭后用 `/coach practice` 可随时再打开;没有结果、或学习未配置/关闭时,该命令只给提示。
223
+ - 练习是原生编辑器的本地模式,不打开阻塞式提问,因此**不会触发 Orca 的「需要输入」提醒**;正常提问、确认与审批提醒保持不变。练习与主草稿使用独立缓冲区,长粘贴的正文和光标位置不会经文本恢复而丢失。F8 收藏仍可用;应用级控制键会返回主编辑器并按 Pi 原有方式处理。
224
+ - 若其他扩展也注册了编辑器组件(例如用量条、Vim 模式),不会争夺:language-coach 会把练习能力叠加到对方的编辑器实例上(保留其类、草稿和装饰),打开练习框时显示练习输入,关闭后恢复对方原样。`/coach autosave off` 只关闭自动收藏,不关闭练习。
225
+
226
+ ### 快捷键收藏
227
+
228
+ 自动收藏默认开启;需要手动收藏时,在看到英文结果后按 **F8**,保存该结果对应的原文、**完整而非被界面截断的英文**、有效语法说明和收藏时间。没有结果时不保存、不显示占位;相同原文、英文与语法重复收藏只保留一份。仅英文有效时也可收藏,此时不保存无效语法。
229
+
230
+ 成功、重复或写入失败的提示会显示在讲解开头约 1.8 秒,然后恢复;不改草稿,不调用模型。快捷键在主编辑界面使用;弹窗可能接管按键。macOS 的 Option+S 在某些终端会输入 `ß` 而非发送 Alt 键,因此扩展默认使用 F8;若键盘需要 Fn 才能发送 F8,请按 Fn+F8。不方便使用功能键时可执行 `/coach save`。可通过 `/hotkeys` 检查快捷键。若希望用 **F19+S 同时按**,需在终端外通过按键映射工具把该组合映射为 F8;当前用户的 Karabiner-Elements 已配置为仅在 Orca 前台映射,不属于发布包配置。
231
+
232
+ 默认目录:
233
+
234
+ ```text
235
+ ~/.pi/agent/language-coach/saved/
236
+ ```
237
+
238
+ 设置了 `PI_CODING_AGENT_DIR` 时,会改用该目录下的 `language-coach/saved/`。也可以在启动 Pi 前设置绝对路径:
239
+
240
+ ```bash
241
+ export PI_LANGUAGE_COACH_STORAGE_DIR='/absolute/path/to/saved-lessons'
242
+ ```
243
+
244
+ 每条收藏是一个 UTF-8 JSON 文件,包含格式版本、内容 ID、收藏时间、原文、英文及可用的词语注释和语法。原文里粘贴图片的本地路径保存为 `「图片」`,不会写入收藏文件;手写的文件名和链接按原样保存。新建收藏目录和文件的权限分别为 `0700`、`0600`(POSIX);文件**不加密**。不修改已有目录权限,不自动备份或同步。清空内存、关闭学习、切换会话或重启不会删除收藏;可手动删除对应 JSON,或删除 `saved/` 下所有收藏文件。
245
+
246
+ 执行 `/coach review` 会读取该目录中的收藏 JSON,按收藏时间倒序生成同目录的 `review.html`,并在系统默认浏览器中打开。每次执行都会重新生成;浏览器中已打开的页面可能需要手动刷新。页面只显示原文、英文、词语注释和可用的中文语法说明(旧收藏中的公式字段也不展示);英文上方有「英文」小标签,词语与语法每条各占一行、用有序列表自动编号(不再是「·」挤成一段),`纠正:` 与面板一样单列一行;0.7.4 之前保存的单条 `explanation` 记录仍能正常显示,旧收藏里的图片路径同样显示为 `「图片」`;保留完整文本;没有答题、评分或定期提醒。收藏按每 10 条一页分块,**一次只显示一页**:文档不滚动(overflow:hidden),两页内容不会同屏;鼠标滚轮**静默累计**,累计约 400px(约 4 格滚轮)才翻页,不足时页面纹丝不动,反向滚动同样生效;翻页带动画:旧页放大淡出、新页自 90% 缩放淡入,仅作用于内容区域,分页栏不做动画(`prefers-reduced-motion` 时关闭);翻页也可以用右侧页码(只显示首尾与当前页附近共 5 个左右,上下箭头翻页、点数字跳页,窄窗口改为贴底横条);标题吸顶,右下角标「x / N」,内容在屏内垂直居中;窄窗口页面超高时先在页内滚动、到边缘后滚轮才翻页;不显示垂直滚动条。这是复习页第一次引入脚本:一段内联滚轮计数器(无网络请求、无外部资源,CSP 仍为 default-src 'none'),单页收藏时完全不输出脚本;卡片高度有下限,原文最多两行、英文最多六行,超出部分悬停可看全文、打印时展开,避免个别长段落在卡片墙上格外突兀。仍是同一个自包含离线文件,只有 CSS,不引入脚本或外部资源。未收藏时显示空状态;损坏或不支持的收藏会跳过并显示数量,不修改原文件。该离线快照同样是**明文**,权限为 `0600`(POSIX),手动打开或清除可使用 `saved/review.html`。自动打开失败时 Pi 会提示路径,文件仍可手动打开。阅读无需启动服务器、请求模型或修改主会话。
247
+
248
+ ### 自动处理范围
249
+
250
+ 仅处理交互式终端中的人工文本提交。RPC、print、JSON 模式和其他扩展注入的输入不会触发学习请求。跳过空内容、斜杠命令、`!` shell 输入和纯代码围栏。发送翻译请求前会把常见文件路径、文件名、完整链接(含 Markdown 标签)和图片引用(含替代文字、HTML 图片标签、图片 data URI 与图片占位符)替换为 `「文件」`、`「链接」`、`「图片」` 标记,原内容不发送;不发送图片附件。路径紧贴中文时只替换路径本身,例如 `去掉/tmp/a.png上面的标题` 发送为 `去掉「图片」上面的标题`,译文仍是完整句子;连续多张截图合并为一个标记。`win/mac`、`前端/后端`、`/coach` 这类单段写法保留原样。没有分词,中文目录名前紧贴的中文词仍可能被一起替换。附图输入仅翻译剩余正文;替换后只剩标记则不请求模型,重试同样执行过滤。主模型收到的提示词保持原样。长输入的其余正文不截断,服务自身的容量限制仍然适用。
251
+
252
+ 英文纠错是学习建议,不是可靠的语法校验器。语法输出无效时保留可用英文,并在讲解中提示语法暂不可用(有词语时只显示词语)。讲解与英文自相矛盾(如称 objectives “不加 s”)、引用译文里没有的搭配(如 match with),或讲解里出现 `don't + adverb + base verb`、`动词 + 名词` 这类公式,或出现主语、宾语、从句、动名词、祈使句这类较难术语时,也按语法无效处理;只检查实际显示的中文讲解,模型内部的 `pattern` 字段不显示也不参与判断,因此它写成公式不会连带丢掉可读的讲解。服务返回不完整生成时不将其当成完整译文;模型偶尔先叙述再输出 JSON 时,会从回复中取出那个完整 JSON 对象,而不是整条丢弃。
253
+
254
+ ## 隐私、上下文与费用
255
+
256
+ - 每次学习请求仅发送固定教学规则和**当前提交文本中把常见路径、文件名、完整链接和图片引用替换为标记后的正文**。不读取主对话历史、工具结果、项目文件或主模型 system prompt。
257
+ - 译文和讲解只经 `ctx.ui.setWidget()` 显示,不调用消息注入、工具注册或会话持久化接口。
258
+ - 即使主模型也是 MiniMax,两者也没有共享对话历史。原始输入仍按 Pi 自身的正常流程进入主会话。
259
+ - 其他扩展可能在本扩展前后转换输入;这里不保证学习文本等于最终主模型收到的 provider payload。
260
+ - 每条可处理提交通常多一次付费请求,手动重试也会产生用量。学习用量不计入 Pi 主会话的 token/费用显示,实际账单以 MiniMax 为准。
261
+ - 路径和链接过滤采用启发式识别,不是完整的隐私脱敏或敏感信息检测;特殊格式仍可能漏过。普通文本里的密钥、内部代码和隐私也可能随提示词发送给学习服务;处理敏感内容前请 `/coach off`。
262
+ - **默认自动收藏每个成功生成的结果**,原文、完整英文和可用语法明文保存在本机(包括含代码、路径、密钥或隐私的原文);不将配置的 API key 或原始服务错误响应写入收藏。若不希望落盘,启动前设 `PI_LANGUAGE_COACH_AUTO_SAVE=false`,或运行 `/coach autosave off` 暂时关闭。关闭后仍可用 F19+S(Orca 的本机映射)、F8 或 `/coach save` 手动收藏。请谨慎处理敏感输入和备份。进程内存、终端回滚缓冲、截图,以及 MiniMax 的数据保留政策不在此保证范围内。
263
+ - Pi 的原有会话记录不受本扩展改变;此前显示的内容也不会因为清空面板而从终端历史中抹除。
264
+
265
+ ## 排错
266
+
267
+ | 现象 | 检查 |
268
+ | --- | --- |
269
+ | 找不到 `/coach` | 检查 `pi list`,重新启动或 `/reload`,避免入口路径失效 |
270
+ | 缺少 API key | 确认变量名是 `PI_LANGUAGE_COACH_API_KEY`,且从设置变量的同一终端启动 Pi |
271
+ | HTTP 401 / 403 | 检查专用 key、区域和套餐权限;不会自动使用其他凭据 |
272
+ | HTTP 400 / 404 | 检查准确模型 ID 和 Anthropic 接口地址,尤其自定义的 `[1M]` 标识 |
273
+ | HTTP 429 | 降低提交频率或稍后手动重试;不自动循环重试 |
274
+ | 超时 / 网络错误 | 检查网络、代理和接口可用性,可适当增加超时后重启 |
275
+ | 没有学习结果 | 无结果时不显示状态提示,这是设计行为。确认已开启、设置了专用 key、使用交互终端,且输入没有被跳过、模型未超出自身容量限制;可用 `/coach retry` 重试 |
276
+
277
+ ## 复习页展示原型
278
+
279
+ [prototypes/review-demo.html](prototypes/review-demo.html) 是此前的独立 HTML 草图;正式复习请在 Pi 输入 `/coach review`,显示真实收藏。草图可双击离线打开,或运行:
280
+
281
+ ```bash
282
+ npm run demo:review
283
+ ```
284
+
285
+ 浏览器打开 `http://127.0.0.1:8767/review-demo.html`。草图仅保留简洁阅读列表,**其中是示例数据**;正式 `/coach review` 读取真实收藏,无需运行这个预览服务。当前截图为 `prototypes/review-reading.png` 和 `prototypes/review-mobile.png`。
286
+
287
+ ## 开发与验证
288
+
289
+ ```bash
290
+ npm install --ignore-scripts
291
+ npm run typecheck
292
+ npm test
293
+ npm pack --dry-run
294
+ ```
295
+
296
+ 可选真实 Pi 伪终端回归(需要 PATH 中有 `pi`,并在 Python 虚拟环境中安装测试依赖 `pyte`):
297
+
298
+ ```bash
299
+ python test/smoke-pi.py
300
+ COACH_SMOKE_FULLSCREEN=1 python test/smoke-pi.py
301
+ ```
302
+
303
+ 脚本使用临时 HOME、模拟 key 和本地模拟服务,不调用真实模型;截图文本写入 `.scratch/`。
304
+
305
+ 开发依赖仅供检查和测试;宿主提供的 Pi 包声明为 `peerDependencies`,不作为运行时依赖打包。`prototypes/` 保留早期 HTML 草图,**不是最终扩展,也不进入发布包**。
306
+
307
+ 自动测试使用模拟服务,不使用真实 key;输入一遍覆盖默认自动出现(每个新结果)、回车/Esc 关闭契约、无结果与未配置提示、`/coach practice` 重开及已打开时不再关闭。练习无专用快捷键,避免与其他扩展冲突(如 Plan 模式的 F2)。另已在隔离配置目录启动真实 Pi 1.5.0,通过伪终端和本地模拟服务检查:100/36 列宽的上下两行、主任务不等待学习响应、学习请求不带历史、主请求和会话记录不含学习内容,以及清空和关闭行为。收藏与复习功能另通过单元/集成测试及真实 Pi 的 regular/fullscreen 伪终端验证:实际 F8/F9/F10 按键、草稿保留、完整内容保存、重复去重、自动收藏开关、第二行临时反馈,以及收藏不增加模型请求、不写入主会话。
308
+
309
+ 另于 2026-11-07 使用真实中国区 MiniMax 接口验证了中文翻译、路径/命令限制和英文纠错三个固定样例,最终均成功,耗时约 1.4–1.7 秒;默认模型已从服务拒绝的 `MiniMax-M3[1M]` 修正为 `MiniMax-M3`。详见 [真实验证记录](docs/minimax-live-validation.md)(仓库文档,不随 npm 包分发)。这不是普遍质量或延迟保证,其他账号/区域、长期稳定性和真实账单仍需自行核实。
310
+
311
+ ## 发布状态
312
+
313
+ 当前为可本地安装的扩展包,采用 [MIT 许可证](LICENSE),已完成上述真实 MiniMax 固定样例验证。尚未发布到 npm,也未替你修改全局 Pi 配置;公开发布前还需确定仓库/包发布位置。
314
+
315
+ ## 参考
316
+
317
+ 交互目标借鉴 [prompt-language-coach](https://github.com/leeguooooo/prompt-language-coach)。本扩展独立实现,不复制其 hook 注入方式:学习内容不会附在主模型回答中。
318
+
319
+ Pi 接口与打包约定:
320
+
321
+ - [Extensions](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md)
322
+ - [Pi packages](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md)
package/package.json CHANGED
@@ -1,6 +1,41 @@
1
1
  {
2
2
  "name": "pi-language-coach",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.7.7",
4
+ "license": "MIT",
5
+ "description": "Independent prompt, English and grammar coaching panel for Pi.",
6
+ "type": "module",
7
+ "keywords": [
8
+ "pi-package"
9
+ ],
10
+ "engines": {
11
+ "node": ">=22.19.0"
12
+ },
13
+ "pi": {
14
+ "extensions": [
15
+ "./src/index.ts"
16
+ ]
17
+ },
18
+ "files": [
19
+ "src/",
20
+ "README.md",
21
+ "CHANGELOG.md",
22
+ "LICENSE"
23
+ ],
24
+ "scripts": {
25
+ "test": "tsx --test test/*.test.ts",
26
+ "typecheck": "tsc --noEmit",
27
+ "demo:review": "python3 -m http.server 8767 --bind 127.0.0.1 --directory prototypes",
28
+ "try": "tsx scripts/try.ts"
29
+ },
30
+ "peerDependencies": {
31
+ "@earendil-works/pi-coding-agent": "*",
32
+ "@earendil-works/pi-tui": "*"
33
+ },
34
+ "devDependencies": {
35
+ "@earendil-works/pi-coding-agent": "^1.5.0",
36
+ "@earendil-works/pi-tui": "^1.5.0",
37
+ "@types/node": "^22.19.0",
38
+ "tsx": "^4.20.0",
39
+ "typescript": "^5.9.0"
40
+ }
41
+ }