@kyn0v/pi-tele0.2.0

Tele

供 AI agent 使用的交互式音乐工具。

Tele v0.2.0 新增 DSH 吉他和弦白板插件，保留 Pi 白板和私有续聊功能。让 agent 修改和弦进行，再点击和弦试听。DSH 插件不提供私有续聊、音乐模式或 DSH 内嵌面板。

下面的 npm 安装说明固定使用 v0.2.0。安装前确认 npm 已提供该版本。

English | 简体中文

安装 DSH 白板插件

Tele v0.2.0 仅支持 DSH 0.2.2-rc.1，不宣称兼容其他 DSH 版本。

在 DSH 插件管理器中安装 npm 包 @kyn0v/pi-tele@0.2.0。也可以让 DSH agent 调用 plugin_manager，使用 action: install_bundle、target: @kyn0v/pi-tele@0.2.0。npm 包已包含构建好的服务端和浏览器文件，不需要源码目录、自行构建或启用安装脚本。检查返回的激活结果；failed 或 restart-required 不代表插件已经运行。

从本地源码开发

如果改用本地源码，先在 shell 中准备：

cd /absolute/path/Tele
npm ci
npm run build

通过插件管理器安装 /absolute/path/Tele，或将该绝对目录作为 agent 的 install_bundle target。更新源码后重新构建，并遵循应用返回的重载或重启结果。linked 插件可以通过 profile 重新组合刷新，不必每次都重启。

无论使用哪种安装方式，都可以让 DSH agent 调用 tele_board 查看和弦库，按 boardId 读取白板，再用当前 expectedRevision 和完整 content 创建或替换。手动在 DSH 所在主机的浏览器打开返回 URL；Tele 不会自动打开。白板是独立本机网页，不是 DSH 内嵌面板，也不能读取或发送 DSH 对话。DSH 白板模式返回 chat: false、chatPanel: false，页面不显示 Pi 续聊面板；Pi 和 standalone 页面行为不变。

DSH 默认使用 dataDir: ~/.tele/dsh（展开为绝对 home 路径）和 port: 0（系统分配空闲端口）。通过插件管理器配置非空绝对 dataDir 和 0 至 65535 的整数端口。同一 profile 中使用该插件的会话共享白板，能访问本机服务的调用方可以读取；不要写入私有对话或秘密。插件作为可信代码以宿主用户权限运行，不提供操作系统沙箱。工具契约与真实宿主清单见 DSH 接入参考。npm run verify:dsh 执行构建和独立 fixture 检查；npm run verify:dsh:live -- http://127.0.0.1:PORT/b/board 对已有真实白板进行只读浏览器检查。两者不能证明真实 DSH 工具调用链或插件管理器 GUI 元数据已通过验证。

安装为 Pi 包

需要 Node.js 22.19 或更新版本、npm，以及 Pi 1.2。安装 Tele：

pi install npm:@kyn0v/pi-tele

包中已包含构建好的服务端和浏览器文件，不需要自行构建或启用安装脚本。也可以在 Pi 包目录找到 Tele。

请在 Tele 源码目录之外使用已安装的包，避免重复加载。在 Pi 中等当前工作结束，再输入：

/reload
/tele harmony

在两分钟内打开私有链接，完成浏览器配对。页面会显示当前分支的旧消息，你可以在白板旁继续对话。不要分享配对链接。运行 /tele off 可断开连接并恢复 Pi 原来的工具。

如果使用本地源码，先构建，再注册绝对路径：

cd /absolute/path/Tele
npm ci
npm run build
pi install /absolute/path/Tele

本地注册不会安装依赖或构建文件。更新源码后，重新运行 npm ci 和 npm run build。包注册、项目自动发现和显式 -e 加载只选一种。

在已有 Pi 会话中加载源码

如果没有注册 Tele 包，Pi 可以从本项目中自动发现扩展。先在 shell 中安装依赖并构建浏览器文件。不要同时启动独立的 Tele 服务。

npm ci
npm run build

如果 Pi 已在本项目运行，先等当前工作和子任务结束。信任项目扩展后，在 Pi 输入框中执行以下命令，不是在 shell 中执行。

/reload
/tele harmony

Pi 会发现 .pi/extensions/tele.js，由它导入 src/pi-extension.ts。扩展可以在没有 dist 时加载，但打开白板仍需构建浏览器文件。/tele harmony 启动本机服务，并给出一次性配对链接。

从其他目录启动一个新的 Pi 时，可以显式加载源码入口。

pi -e /absolute/path/Tele/.pi/extensions/tele.js

构建后也支持 pi -e /absolute/path/Tele/dist/pi-extension.js。各入口选一个，不要同时通过项目发现和 -e 重复加载。如果 Pi 使用 --tools 白名单，必须包含 tele_board。

启动 pi 会创建新进程，不会附着到另一个活跃 CLI。不要打开仍被另一个 Pi 使用的会话文件。要继续原来的活跃会话，请在原 Pi 中使用 /reload 和 /tele。

连接期间，模型只能调用 tele_board。其他扩展的确认框仍需在终端处理，浏览器不能代为批准。/tele off 会撤销连接、停止 Tele 服务、等待本轮运行结束，并恢复原来的工具。Pi 不会退出，已保存的白板修改也不会回滚。

如果独立服务已经占用该端口或数据目录，由其所有者先停止服务，再连接 Pi。Tele 不会终止其他服务。普通白板 URL 不授予私有历史或对话控制权。不要分享配对链接。

选择浏览器语言与布局

在白板页眉的 语言控件中选择 English 或 简体中文。选择器在对话面板外，面板收起或使用手机时仍可访问。

Tele 将选择保存在 tele.locale 中。如果没有有效的记录，浏览器首选语言以 zh 开头时使用简体中文，否则使用英语。即使存储被禁用，当前页面也能切换语言。

切换语言会更新控件、状态提示和无障碍标签，不会翻译消息、会话名、白板内容或和弦符号，也不会改写已保存的数据。新的数据目录使用英语示例。中文示例内容在两种界面语言下都保持中文。

对话面板默认在右侧，可以移到左侧或底部，也可以收起。Tele 会记住这些选择。手机使用底部面板，不改变桌面布局偏好。

切换语言或布局不会替换输入框或清空草稿。Enter 发送，Shift+Enter 换行；输入法组字时按 Enter 不会发送。刷新页面会丢失草稿。

不使用 Pi 运行白板

不连接 Pi 也能播放和更新白板。在 Tele 源码目录中运行：

npm ci
npm run build
npm start

打开 http://127.0.0.1:4317。首页进入教学白板，对比大四级 D → G → D 与小四级 D → Gm → D。这是和声教学示例，不是任何歌曲的已核实转录。对话面板会说明 Pi 尚未连接。

点击和弦卡片或 播放整组。每个和弦占两拍，速度由白板的 BPM 决定。停止播放取消当前和未来的音符。浏览器只有在用户操作后才启动音频。白板更新会停止旧播放，绝不自动播放新内容。语言切换保留当前播放及其停止控件。

让 agent 创建并更新白板

保持独立服务运行。在另一个终端或 agent 的命令工具中执行：

npm run board -- put harmony --expect 0 --file examples/major.json --open
npm run board -- get harmony
npm run board -- put harmony --expect 1 --file examples/comparison.json
npm run board -- catalogue

首次 put 创建白板，返回含 id、revision、content、url 的 JSON。--open 调用系统浏览器。更新后的 URL 仍是 /b/harmony，原页面通过 SSE 接收完整替换，无需刷新。

每次写入都会替换整块白板，并要求提供当前 revision。修改前先读取白板，保留不需要改动的分组。遇到 409 冲突时，先读取最新内容再重试。使用 npm run --silent board -- ... 可只输出 JSON，不显示 npm 的脚本名称。

可以给 agent 这样的指令：

运行 npm run --silent board -- catalogue 查看可用和弦。按 examples/major.json 的结构创建一个有标题、有序分组和和弦的 JSON 文件。运行 npm run --silent board -- put my-board --expect 0 --file /absolute/path/content.json --open。后续修改前先 get my-board，保留需要的分组，用读取到的 revision 完整替换同一块白板。遇到 409 先重新读取，不要盲目覆盖。

另一个可运行的例子：

npm run board -- put cadence --expect 0 --file examples/cadence.json --open

CLI 写入使用本机数据目录里的 capability 文件，浏览器不持有这个 token。不要把它贴入对话或提交到版本库。在服务所属的终端按 Ctrl+C，可停止服务并释放数据目录锁。

使用不同端口或数据目录

Pi 扩展、独立服务和 CLI 共用默认数据目录 ~/.tele，位于安装包之外。DSH 插件则默认使用 ~/.tele/dsh，从插件配置读取 dataDir/port，不使用 Pi flags 或 TELE_DATA/TELE_PORT。重新安装包不会替换白板或本机写入 capability。显式相对 TELE_DATA 路径仍相对于 shell 当前工作目录解析。不同目录中的命令应使用同一个绝对路径。

Tele 不会自动查找、移动或删除旧源码目录中的数据。如需继续使用已有白板，请在启动 Pi 和 CLI 前，为两者设置 TELE_DATA=/absolute/path/old-checkout/.data。

TELE_DATA=/tmp/my-tele TELE_PORT=4320 npm start
TELE_DATA=/tmp/my-tele TELE_PORT=4320 npm run board -- get demo

同一数据目录只允许一个服务，即使端口不同。崩溃后可能保留 server.lock，导致启动失败。先查看其中的 owner.json 并确认旧进程已退出，再手动移除锁目录。Tele 不自动猜测锁是否过期。

Pi 扩展也接受 --tele-port 和 --tele-data，优先于对应环境变量。端口 0 请求系统分配空闲端口。独立 CLI 的 TELE_PORT 必须是非零端口。Pi 使用自定义端口时，CLI 命令须设置相同的 TELE_PORT。Pi 使用 --tele-data 时，CLI 须通过 TELE_DATA 指向同一目录。

隐私与限制

Tele 只监听 127.0.0.1。白板读取对能访问本机服务的调用方公开，写入需要本机 capability。以下私有对话规则仅适用于 Pi 连接；DSH 插件不启动对话桥接，也不限制 DSH 的其他工具。Pi 私有对话读取和命令需要配对浏览器 cookie，限定一个绑定，带有 HttpOnly、SameSite=Strict 和八小时有效期。配对链接两分钟后失效，只能使用一次。断开、重载、会话替换或分支替换会撤销绑定。本机 HTTP 没有 TLS，cookie 不带 Secure。不要把服务暴露到公网。

配对后的浏览器可以读取所选分支的用户和助手文本。Tele 不显示思考内容、系统提示、工具参数与原始结果、压缩摘要或扩展私有消息，但无法可靠过滤普通消息中的秘密。浏览器最多显示 100 项、约 256 KiB 的内容，每项用户或助手文本最多 32,768 个 UTF-16 代码单元。不显示附件，对话历史仍只保存在 Pi 中。

收到提交回执，不代表模型已接受消息或完成回复。如果 Tele 无法确认结果，它会保留草稿，不会自动重发。重连只读取当前状态，不会重放命令。停止回复不会撤销已保存的白板修改，也不会处理终端确认框。

音乐模式不是操作系统沙箱。已信任扩展仍以 Pi 用户权限运行。Tele 限制模型工具调用，不限制扩展任意代码。不要加载不可信扩展。

当前原型支持本机使用、标准六弦调弦、固定和弦库和整块白板更新。Web Audio 合成近似拨弦的声音，不使用吉他录音。暂不支持变调夹、自定义调弦、和弦编辑、节奏编排、云端账号或 MCP 插件。白板可以在正常重启后恢复。文件原子替换不保证断电后或网络文件系统上的数据恢复。

验证改动

从没有 dist 的全新源码目录开始：

npm ci
npm run verify:ci

verify:ci 依次运行扩展发现、测试、构建、Chromium 安装、包检查、无模型对话探针和浏览器检查。如果已有 dist，它会拒绝运行，不会删除构建产物。GitHub Ubuntu 会安装 Chromium 的系统依赖，其他 Linux 主机需要另行安装。

可用绝对路径 PLAYWRIGHT_BROWSERS_PATH 指定共用浏览器缓存。添加 -- --artifact-dir /absolute/path/new-directory，可在全部检查通过后保留测试过的压缩包和元数据。详见发布说明。

verify:extension 在离线 Pi 中检查项目自动发现，使用临时配置、不保存会话、不传 -e。它不发送模型输入，也不生成 dist。

verify:package 构建并打包 Tele，在只安装生产依赖且禁用生命周期脚本的环境中安装压缩包，再将安装目录注册到一次性离线 Pi。它检查浏览器私有配对、全部已分发浏览器资源、已安装 CLI 的写入与冲突、默认 home 数据目录，以及重装后的持久化。Pi 和 Playwright 只由开发宿主提供。它还要求压缩包包含 DSH 入口、bundle patch、英中文元数据、图标及 DSH 清单声明。结构化测试 context 会仅用生产依赖加载压缩包中的 DSH 入口，检查网页资源和清理行为；这项可移植性检查不运行真实 DSH 工具注册表。包验证覆盖压缩包和 Pi 本地注册，不覆盖 Pi 的 npm 下载器或真实 DSH 激活。它不会发布包或修改你的 Pi 设置。真实 DSH 验收单独执行，见 DSH 验证清单。

npm test 使用真实 HTTP 服务、临时目录和 CLI 子进程，覆盖乐理数据、校验、冲突、持久化、锁、SSE、私有对话授权、语义提示、语言词典覆盖和回退。单元测试不能替代浏览器验证。

verify:chat:probe 驱动真实无模型 Pi 桥接和浏览器。它检查当前分支旧历史、私有载荷排除、真实终端等待事件、被消费输入的不确定状态、工具恢复、会话撤销，以及挂起输入在 provider 工作前被中止。它也检查两种界面语言和无障碍标签、存储与回退、被禁用的存储、草稿和历史不变、全部停靠与折叠布局，以及手机宽度无溢出。

verify:browser 驱动生产构建和 CLI，检查链接导航、音频自然结束、取消与旧播放静音、播放中切换语言、焦点、键盘、重连及桌面和手机布局。它将生产合成渲染为 WAV，检查有限、非零且不削波的样本。这些检查不代表主观试听。请通过扬声器或耳机判断听感。

截图、WAV 和报告保存在本机 .audit/browser/ 与 .audit/chat/。脚本使用临时数据和端口，只关闭自己的进程，并删除临时数据。

可选的真实模型检查最多发送三条用户消息，会消耗你配置的 Pi 模型额度，可能产生费用：

npm run verify:chat:browser
# 可选模型覆盖：
TELE_TEST_MODEL=github-copilot/gpt-6-luna npm run verify:chat:browser

它在一次性 Pi 中验证旧对话回忆、浏览器流式续聊、实际白板工具更新、Pi 历史持久化及浏览器停止回复。它不附着到你的原 CLI，也不修改全局 Pi 配置。

文档

README 和浏览器生成的界面支持英语和简体中文，其他文档并未全部翻译。

• DSH 接入参考说明 npm 和本地安装、配置、白板工具及单独的真实宿主验证清单。
• 白板 API 参考为英语，记录精确字段、容量、安全和持久化。
• Pi 对话参考为简体中文，说明私有 HTTP 接口、消息显示规则和会话生命周期。
• 白板设计和对话设计为英语。
• 发布说明包含 CI、包验证和 OIDC 发布步骤。
• 第三方说明记录依赖及许可证边界。

参考与许可

TwoMoons 将吉他指法图与可播放音高关联，采用 GPL-3.0 许可证。Tele 参考了它的产品设计，本地使用的是 kyn0v/two-moons fork。

Tele 没有使用 TwoMoons 的源码、音频样本或其他素材。HTML、CSS、指板绘制和音频合成均单独编写。依赖与许可证说明见第三方说明。

Tele 采用 MIT 许可证，版权归属 2026 Jian。第三方许可证保持不变。