ai_co_discuss 0.3.98 → 0.4.0

package/.agents/skills/discuss-host/references/free.md

@@ -64,7 +64,7 @@
 
 ## 工作流
 
-本次任务有 `workflow` 字段时，本房间启用了用户的工作流。它像技能一样按需使用：`workflow.description` 是它的用途，请求与用途相符或用户要求按它做时才用，其他请求照常处理。要用时，本会话还没读过、或 `workflow.revision` 与上次读到的不同，才读 `workflow.skill_path`（API 主持人读系统提示中的工作流正文）；否则沿用已读内容。按它组织工作时，`workflow.members` 列出每张卡片现在由哪位成员担任、是否在场、项目权限；只点名在场的成员。`workflow.flow` 是用户在流程画布上排好的接力：`order` 是顺序说明，`cli` 是照它派活要带的参数（API 主持人用 `api` 中的字段），派活时原样带上，正文写清每一棒做什么；`flow.missing_cards` 列出缺成员的卡片（此时不能照画布派活，按下文补齐或说明缺谁），`flow.errors` 说明画布排不成接力，按 SKILL.md 组织并在回答里提醒用户修改画布。`workflow.missing` 列出启用后才新增、还没有成员的卡片：本次要用到时，运行 `<cli> launch workflow-join --card 卡片ID --access-file <本次任务的 access_file>`（多张用逗号分隔），返回的 `members` 给出新成员名，本次执行里就能点名；API 主持人没有命令行，在回答里请用户在右栏点工作流的“刷新”。成员离开或被移除的角色不要自行请回，在回答里说明缺谁，不另找成员代替。工作流只带来做法和成员，不扩大你的权限。
+本次任务有 `workflow` 字段时，本房间启用了用户的工作流。它像技能一样按需使用：`workflow.description` 是它的用途，请求与用途相符或用户要求按它做时才用，其他请求照常处理。要用时，本会话还没读过、或 `workflow.revision` 与上次读到的不同，才读 `workflow.skill_path`（API 主持人读系统提示中的工作流正文）；否则沿用已读内容。按它组织工作时，`workflow.members` 列出每张卡片现在由哪位成员担任、是否在场、项目权限；只点名在场的成员。`workflow.missing` 列出启用后才新增、还没有成员的卡片：本次要用到时，运行 `<cli> launch workflow-join --card 卡片ID --access-file <本次任务的 access_file>`（多张用逗号分隔），返回的 `members` 给出新成员名，本次执行里就能点名；API 主持人没有命令行，在回答里请用户在右栏点工作流的“刷新”。成员离开或被移除的角色不要自行请回，在回答里说明缺谁，不另找成员代替。工作流只带来做法和成员，不扩大你的权限。
 
 本次任务（本地任务文件或 API 的 `task`）没有 `workflow` 字段时，不按任何工作流做事，即使会话里读过。
 

package/.agents/skills/local-tts-setup/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: local-tts-setup
+description: "为 AI CoDiscuss 安装本机朗读语音：下载 yovoice CLI、推理引擎与 Qwen3-TTS 模型，在这台电脑的显卡上合成朗读，并配置为网页“设置 → 语音”里的“本机”服务。用户要求安装、修复、升级或卸载本地朗读、本机语音、离线 TTS 时使用；不用于填写火山引擎、阿里云、Azure 等云端语音的密钥。"
+---
+
+# 本机朗读语音（local-tts-setup）
+
+装好后的样子：
+
+- `SERVICE_HOME/yovoice/cli/`：yovoice CLI（含 `tools/` 下的音频转换器）；`SERVICE_HOME/yovoice/data/`：推理引擎与模型，只给 CoDiscuss 用，不与 yovoice 桌面应用共用（`SERVICE_HOME` 见“前提”第 2 条）。
+- 访问令牌存在 CoDiscuss 的本机私有密钥里（地址 `http://127.0.0.1:18765`），不写进其他文件。
+- 朗读设置切到“本机”。yovoice 服务由 CoDiscuss 本机程序在朗读时自动启动，只监听 `127.0.0.1:18765`；用户点停止朗读后 5 秒内、或 1 分钟没有朗读请求时自动结束并释放显存（CoDiscuss 崩溃也一样），不需要开机自启。
+
+全程只在用户电脑上操作：不改 CoDiscuss 源码，不把令牌写进回复、日志或命令行参数；下载与安装前把预计占用（下文“前提”）告诉用户。
+
+## 前提
+
+依次检查，任何一项不满足就停下说明，不硬装：
+
+1. **CoDiscuss 版本**：运行 `codiscuss launch tts-settings`，输出的 `catalog` 里要有 `"id": "local"`。没有说明版本过旧，请用户先更新（`npm install -g ai_co_discuss@latest`，再 `codiscuss service restart`）后继续。
+2. **服务目录**：设置了环境变量 `DISCUSS_SERVICE_HOME` 时用它，否则是 `~/.codiscuss`。下文记为 `SERVICE_HOME`。
+3. **推理后端**（决定 `setup --backend`）：
+
+   | 平台 | 判断 | 后端 |
+   |---|---|---|
+   | Windows + NVIDIA | `nvidia-smi` 的驱动主版本 ≥ 580 | `cuda13`（RTX 50 系必须用它：CUDA 12.4 不支持 Blackwell） |
+   | Windows + NVIDIA | 驱动更旧 | `cuda`，或请用户先升级驱动 |
+   | Windows + AMD / Intel 独显 | — | `vulkan` |
+   | macOS Apple Silicon | — | `metal` |
+   | Linux x64 | 有可用的 Vulkan 驱动 | `vulkan`，否则 `cpu` |
+
+   只能用 `cpu` 时先告诉用户：每段朗读可能要十几秒以上，播放会断断续续，用户同意再装。
+4. **显存与磁盘**：模型（Qwen3-TTS 1.7B CustomVoice Q8）约 2.7 GB，需要 4 GB 以上显存；磁盘约 3.5 GB（CUDA 引擎约 0.6 GB + 模型）。
+
+## 安装
+
+命令以 Windows 的 `yovoice.exe` 为例，macOS / Linux 的可执行文件是 `yovoice`。下载走用户当前的网络设置；GitHub 或 ModelScope 访问失败时，先问用户是否有代理，不自行换来源。
+
+1. **下载 CLI**：读 `https://api.github.com/repos/leemysw/yovoice/releases/latest`，取资产 `yovoice-<版本>-cli-<windows-x64 | macos-arm64 | linux-x64>.zip` 与 `SHA256SUMS.txt`，下载到空目录 `SERVICE_HOME/yovoice/download/`，核对 SHA-256 一致后解压到 `SERVICE_HOME/yovoice/cli/`（Windows 用 `tar -xf`），保留 `tools/` 目录。已装过时先结束正在运行的 yovoice 进程再覆盖。用 `yovoice.exe --version` 确认。
+2. **推理引擎**：`yovoice.exe setup --backend <后端> --data-dir SERVICE_HOME/yovoice/data`。
+3. **模型**：`yovoice.exe models download qwen3-tts-customvoice-q8 --data-dir SERVICE_HOME/yovoice/data`（默认从 ModelScope 下载，失败时可加 `--source huggingface`）。
+4. **令牌**：生成 64 位十六进制随机串，写入临时文件 `{"base_url": "http://127.0.0.1:18765", "api_key": "<令牌>"}`，运行 `codiscuss launch api-key --file <临时文件>`，记下返回的 `api_key_ref`，随即删除临时文件。
+5. **切换朗读服务**：把 `codiscuss launch tts-settings` 的输出存成临时文件，只改两处：`provider` 设为 `"local"`，`providers.local.api_key_ref` 设为上一步的引用；其余字段不动（读出的 `catalog` 等字段保存时会被忽略），用 `codiscuss launch tts-settings --file <临时文件>` 保存后删除临时文件。用户只要求安装、不想马上切换时，`provider` 保持原值，只写 `api_key_ref`。
+6. **验证**：先结束正在运行的 yovoice 进程（推理子进程 `audiocpp_server` 会随之退出），否则旧令牌启动的服务会拒绝新令牌。临时文件写入 `{"text": "你好，这是本机朗读测试。"}`，运行 `codiscuss launch tts --file <临时文件>`：返回 `format` 为 `"m4a"`、`audio` 非空即成功，`SERVICE_HOME/yovoice/serve.log` 会出现一行 `"url":"http://127.0.0.1:18765"`，说明服务是由 CoDiscuss 拉起的。1 分钟内再换一段约 100 字的新文本请求一次，测服务已启动时的速度（同一文本会命中本机缓存，测不出速度）。参考：RTX 5060 8 GB + `cuda13`，短句含启动服务与加载模型约 4 秒；服务已启动时，100 字约 6–7 秒合成约 27 秒音频。
+7. **清理与汇报**：删除 `SERVICE_HOME/yovoice/download/` 与所有临时文件。向用户报告后端、模型、实测耗时，并说明：网页“设置 → 语音”选“本机”，可选 9 个音色并分别试听；本机服务不支持调语速，语气提示可用；切回云端服务只需在同一处点选。网页经已在运行的 CoDiscuss 本机服务朗读；刚更新过 CoDiscuss 时，先运行 `codiscuss service restart` 再刷新网页，才会出现“本机”。
+
+## 修复、升级与卸载
+
+- **修复**：读 `SERVICE_HOME/yovoice/serve.log` 与 `SERVICE_HOME/yovoice/data/logs/`，对照下表处理；必要时从出问题的那一步重做，令牌变了就重做第 4、5 步。
+- **升级 yovoice**：结束 yovoice 进程，重做第 1 步；新版要求新引擎时重做第 2 步。
+- **卸载**：先在设置里切回其他服务（或用第 5 步的方法改 `provider`），结束 yovoice 进程，删除 `SERVICE_HOME/yovoice/`。
+
+| 现象 | 原因与处理 |
+|---|---|
+| 本机语音尚未安装 | 没找到 `cli/yovoice.exe` 或令牌：重做第 1、4、5 步 |
+| 服务拒绝了令牌 | 18765 端口上是旧令牌启动的 yovoice：结束该进程后重试 |
+| 服务启动超时 | 看 `serve.log`；端口被其他程序占用时请用户释放该端口 |
+| 合成失败（HTTP 500） | 看 `data/logs/`：CUDA 报错时检查驱动，或换后端重做第 2 步；显存不足时关闭占显存的程序 |
+| 转码失败 | `cli/tools/` 缺失或损坏：重做第 1 步 |

package/.agents/skills/workflow-creator/SKILL.md

@@ -21,9 +21,9 @@ description: AI CoDiscuss 工作流的创建与修改技能。用户要把房间
 
 1. **弄清需求**：目标产物；有哪些角色、各自负责什么；交接顺序；谁可以改哪些文件；什么算验收通过；哪些做法已在房间里跑通过。能从房间记录或用户描述得到的不问，只问会改变设计的关键歧义。
 2. **设计**：按下面“写什么、放哪里”决定 SKILL.md 和每张卡片的内容。
-3. **按格式写**：见“格式”。
+3. **按格式写**：见“格式”。流程定下后，照 SKILL.md 画一张示意图 `flow.json`（见“流程画布”）。
 4. **校验并保存**：见“校验与保存”，按报错修正，直到通过。
-5. **修改已有工作流**：先读现有文件，沿用同一 ID，优先局部调整；保存后，启用它的房间从成员下一次执行起读到新内容；新增的卡片不会自动加入这些房间，由主持人用到时补齐，或由用户在右栏点工作流的“刷新”。
+5. **修改已有工作流**：先读现有文件，沿用同一 ID，优先局部调整；改了谁接谁、增删了卡片，就重画 `flow.json`，没有的补一张；保存后，启用它的房间从成员下一次执行起读到新内容；新增的卡片不会自动加入这些房间，由主持人用到时补齐，或由用户在右栏点工作流的“刷新”。
 
 ## 写什么、放哪里
 
@@ -31,6 +31,7 @@ description: AI CoDiscuss 工作流的创建与修改技能。用户要把房间
 |---|---|---|
 | `SKILL.md` | 主持人 | 用途；开工前准备；每一步找哪个角色、交回什么、怎么验收；各角色共同遵守的约束；产物放在哪里（写成“读项目 README 找到……”） |
 | `agents/<卡片ID>.md` | 该角色 | 角色立场、质量标准、本角色特有的做法和常见错误 |
+| `flow.json` | 用户 | SKILL.md 流程的示意图：谁接谁、哪里交回主持人、哪里循环 |
 
 - **同一条规则只写一处。** 流程、交接和输出格式写在 SKILL.md，由主持人派活时写进任务；卡片不复述流程。原因：之后用同一 ID 修订时只需改一处，两处都写迟早会对不上。
 - **SKILL.md 自成一体**：只按角色的显示名、描述和产物路径说话，不引用卡片提示词的内容（API 主持人读不到卡片）。
@@ -47,12 +48,35 @@ description: AI CoDiscuss 工作流的创建与修改技能。用户要把房间
   SKILL.md
   agents/
     <卡片ID>.md
+  flow.json           流程示意图
   templates/ 等（可选）  主持人要用的模板、参考资料，只认文本文件
 ```
 
-**流程画布**（`flow.json`，可选）：用户在编辑页画的接力，`{ "nodes": [{ id, type: start|card|host, card?, x, y }], "edges": [{ source, target }] }`。保存时程序检查它排得成接力（从唯一的 `start` 出发一棒接一棒；同一棒并排的卡片由同一棒交来、交给同一棒；`host` 是前一棒之后的检查点；连回前面卡片的边是循环，不能跨过前一个检查点），主持人任务里会拿到按它生成的派活参数。粘贴草稿不带画布；用草稿保存时，已有的 `flow.json` 原样保留。起草时不用写它，SKILL.md 照常写清流程；用户画了画布时，SKILL.md 里的顺序要与画布一致。
+**流程画布**（`flow.json`）：用户在“工作流”页看到的示意图，帮用户一眼看懂 SKILL.md 里谁接谁。它只是示意：程序不执行它，主持人也收不到它，派活只按 SKILL.md。所以流程照常完整写在 SKILL.md，图照着 SKILL.md 画，两边对不上时以 SKILL.md 为准，并把图改对。
 
-`SKILL.md` 和 `agents/` 之外的文件随工作流一起保存和分享；在 SKILL.md 里按相对路径指给主持人，如“照本工作流文件夹下 `templates/` 建项目”。粘贴草稿只能带 SKILL.md 和卡片；用草稿保存时，文件夹里已有的这些文件原样保留。
+```json
+{ "nodes": [
+    { "id": "start", "type": "start" },
+    { "id": "writer", "type": "card", "card": "writer" },
+    { "id": "people", "type": "card", "card": "people" },
+    { "id": "world", "type": "card", "card": "world" },
+    { "id": "accept", "type": "host", "label": "验收" }
+  ],
+  "edges": [
+    { "source": "start", "target": "writer", "label": "任务书" },
+    { "source": "writer", "target": "people", "label": "同时审" }, { "source": "writer", "target": "world", "label": "同时审" },
+    { "source": "people", "target": "accept" }, { "source": "world", "target": "accept" },
+    { "source": "accept", "target": "writer", "label": "返工" }
+  ] }
+```
+
+- 恰好一个 `start`，代表主持人开始派活。`card` 节点用 `card` 指明卡片 ID，每张卡片至少一个节点；同一角色在流程里出场两次（如批评家每集审稿、阶段末再通读）就放两个节点，`id` 不同、`card` 相同；`host` 节点表示交回主持人判断（验收、裁定、改任务书），可以有多个。节点 `id` 用英文、数字、下划线或连字符。
+- 连线 `source → target` 表示“交给”：从开始连到最先做的角色；同时做的几位从同一处各连一条；指回前面的节点表示循环（图上画成金色虚线），比如上例审完交回主持人、要返工就回到写手。线型只分普通和循环，其余的意思写在说明里。
+- **说明**（可选，不换行）：`host` 节点的 `label` 写主持人在这里做什么（最多 12 字，如“验收”“改任务书”）；连线的 `label` 写这条线的意思（最多 16 字），线型表达不了的都靠它：同时做的标“同时审”，循环标回去的条件“返工”“下一集”，条件分支各标条件，不等交回的标“不等交回”。没有特别含义的线不写。
+- 不写 `x`、`y`：所有节点都没有坐标时，页面打开时自动按先后排版；用户拖动后会存下坐标。
+- 最多 60 个节点、120 条连线。保存时只检查格式和卡片是否存在，连线怎么画都行。
+
+`SKILL.md`、`agents/` 和 `flow.json` 之外的文件随工作流一起保存和分享；在 SKILL.md 里按相对路径指给主持人，如“照本工作流文件夹下 `templates/` 建项目”。粘贴草稿只能带 SKILL.md、卡片和 `flow.json`；用草稿保存时，文件夹里已有的其他文件原样保留，草稿不带 `flow.json` 时已有的示意图也保留。
 
 ### 登记命令（给模型 API 成员）
 
@@ -123,6 +147,8 @@ project_access: write
 （SKILL.md 全文，含头信息）
 <!-- workflow-file: agents/writer.md -->
 （卡片全文，含头信息）
+<!-- workflow-file: flow.json -->
+（示意图 JSON）
 ```
 
 - 分隔行必须独占一行、从行首开始。说明文字只能写在第一个 `workflow-file` 分隔行之前；之后的内容都算文件正文，最后一个文件后面不要再加说明。