@leviyuan/lodestar 0.18.25 → 0.19.0

package/docs/configuration.md

@@ -30,6 +30,8 @@ lodestar-setup
 | `lodestar-version` | 查看 Lodestar、实际 Agent 版本及运行目录 |
 | `lodestar-agent` | 由主 Agent 调用已配置模型执行任务，也支持与自身相同的模型 |
 
+启动和停止命令会核对 PID 对应的实际入口，读取进程信息失败时明确报错。无法识别的运行时选项、macOS 无法区分边界的含空格入口、Windows 相对入口也会拒绝操作，请通过对应服务管理器处理。旧式单行 PID 文件缺少入口标识，`lodestar-stop` 会拒绝发送信号；请先核对该 PID 的完整命令行，再通过服务管理器或精确 PID 停止。停止命令以进程退出为准，删除 PID 文件不会被当作停止成功。
+
 daemon 启动时不检查 Agent 版本，也不安装或更新 Agent。自动更新默认关闭；首次安装缺少运行文件或需要更新时，运行 `lodestar-update --agents-only`。手动更新和显式开启的自动更新都选择上游 `latest`，独立于 Lodestar 发版，不设置兼容版本白名单。
 
 Codex、Claude、DSH 在 `[runtime.agent_auto_update]` 下分别设置 `codex`、`claude`、`dsh` 开关，未设置的项均为 `false`。设为 `true` 的 Agent 在 daemon 运行满 6 小时后首次检查，之后每 6 小时独立检查，启动阶段仍不检查；一个 Agent 更新较慢或失败不阻塞其他 Agent。旧版布尔总开关按原值兼容映射为三项并提示迁移，不可与新配置表混用。
@@ -83,6 +85,8 @@ bin = "/abs/path/to/claude-wrapper"  # 可选的 Claude 可执行文件
 
 项目名用于定位工作目录；工具、MCP 等启动配置按实际目录匹配。同目录的 BTW/FK 与项目别名共享配置，别名配置冲突时明确报错。WT 的目录独立，不自动套用主目录的启动配置；需要配置某个 WT 时，可新增一个项目配置项，将 `cwd` 指向该 WT 的实际路径。工作目录内的 Agent 原生配置仍由相应后端读取。
 
+Claude 后端启用项目 MCP 时，缺少 `.mcp.json` 表示未配置；文件存在但无法读取、JSON 损坏或缺少有效的 `mcpServers` 对象会阻止会话启动，并显示具体错误。修正配置后再启动会话。
+
 账号配置、OpenRouter 默认模型和 DSH 接入见[模型与账号](models.md)。手动修改配置后需重启 daemon；群内设置自行保存。
 
 ## HTTP 代理

package/docs/models.md

@@ -6,7 +6,7 @@
 
 ## 配置 API Key
 
-GLM Key 可在首次安装时跳过，之后用群命令添加或更换。以下命令先向对应平台校验凭据和模型目录，通过后才保存；认证、网络或响应错误均保留原配置并给出原因。校验无需调用付费模型，也不要求先安装对应 Agent。
+GLM Key 可在首次安装时跳过，之后用群命令添加或更换。以下命令先返回回执，后台向对应平台校验凭据，通过后才保存；认证、网络或响应错误均保留原配置并给出原因。校验无需调用付费模型，也不要求先安装对应 Agent。
 
 | 账号 | 群命令 |
 | --- | --- |
@@ -24,11 +24,15 @@ GLM Key 可在首次安装时跳过，之后用群命令添加或更换。以下
 
 `[base_url]` 表示可选参数，命令中不输入方括号；API Key 只填原值，不加 `Bearer`。`glm-setup <base_url> <api_key>` 的原有格式仍可使用，GLM 的 Key 与平台地址必须对应。保存后发送 `md` 选择模型。账号配置由本机所有群共用，更新 Key 保留已有模型、档位和可见性设置。
 
-如果凭据校验通过，但保存后的模型加载因 Agent 未安装等原因失败，会明确提示“配置已保存，但暂不可用”；按提示处理后发送 `md` 刷新。认证失败会提示核对 Key，网络失败会提示检查连接和代理，不会将错误正文误报为“缺少 data 数组”。
+凭据校验通过后会明确返回“配置已保存”，模型目录和额度随后在后台加载；若 Agent 未安装或目录刷新失败，`md` 显示具体错误。处理后等待后台刷新即可。认证失败会提示核对 Key，网络失败会提示检查连接和代理，不会将错误正文误报为“缺少 data 数组”。
 
 ## 选择与管理模型
 
-发送 `model`（`md`），在 Claude Code、Codex、DeepSeek Harness 分组下选择账号，再选择模型。有多个推理档位（effort）时继续选择档位，只有一个档位时直接应用。
+发送 `model`（`md`），在 Claude Code、Codex、DeepSeek Harness 分组下选择账号，再选择模型。面板直接使用缓存，不等待平台接口或 Codex 账号查询。有多个推理档位（effort）时继续选择档位，只有一个档位时直接应用。
+
+模型目录每 5 分钟、额度每 60 秒独立在后台刷新，只有 daemon 启动会等待首次加载。`md`、`hi`、账号列表、Agent 身份目录、自动选号和回复页脚都直接读取已提交缓存；打开面板不会启动额外查询，某个来源变慢也不会占住交互。Codex 邮箱复用后台原生账号查询的结果。
+
+同一来源和账号的并发刷新会合并，刷新完成后一次更新缓存。网络或限流失败保留成功快照，错误写入日志，目录刷新错误也会显示在模型面板；失败按 1、2、4、5 分钟退避并遵守平台更长的限流冷却。没有缓存或认证已失效时立即显示加载中或 `MISS`。修改凭据会隔离并清除受影响账号的缓存，旧请求结果不能覆盖新配置；其他账号继续可用。
 
 | 操作 | 作用 |
 | --- | --- |
@@ -37,7 +41,7 @@ GLM Key 可在首次安装时跳过，之后用群命令添加或更换。以下
 | 补录模型 | 添加接口目录外的模型，可选择推理档位并使用 |
 | 删 | 删除补录记录；仍有会话选用时需先切换模型 |
 
-除 OpenRouter 和 PackyAPI 使用内置精选列表外，各来源默认显示接口目录中的模型，新模型会随目录刷新出现。所有来源都支持补录，记录保存在 `custom_models`；支持端点验证的来源会先验证。目录未收录不会阻止选择，实际不支持的请求由后端报告错误。接口后来收录同名模型时自动转为接口项，不重复显示。删除补录记录也会清理默认模型和辅助模型中的相关引用。
+除 OpenRouter 和 PackyAPI 使用内置精选列表外，各来源默认显示接口目录中的模型，新模型会随后台目录刷新出现。隐藏、显示和补录只修改本地列表，不重拉全部来源。所有来源都支持补录，记录保存在 `custom_models`；补录按本地规则检查模型 ID 和请求档位，不在交互中查询上游；实际调用不支持时由后端报告错误。目录未收录不会阻止选择，实际不支持的请求由后端报告错误。接口后来收录同名模型时自动转为接口项，不重复显示。删除补录记录也会清理默认模型和辅助模型中的相关引用。
 
 同账号切换 Claude 或 DSH 模型从后续回复生效；Codex 的持久设置需重启会话生效。跨账号或后端切换只允许在空闲时进行。来源禁用或目录获取失败显示 `MISS`。
 
@@ -51,7 +55,7 @@ GLM Key 可在首次安装时跳过，之后用群命令添加或更换。以下
 
 回复底部显示 `agent · 模型名/effort`，其中 Agent 为 `claude`、`codex` 或 `dsh`。窗口额度如 `4.1h·7%·[6.9d·17%]`，分别表示重置倒计时与已用百分比，方括号内为周窗口；余额显示 `余额 $12.34` 或 `余额 ¥12.34`。Codex 刷新失败或进程已退出时，回复底部按原格式保留同账号上次成功的额度。没有成功缓存、登录认证失败或缓存已被重新登录、删除账号、额度重置操作清除时显示 `MISS`。Codex 的 `hi`、`codex-accounts` 额度区域在网络或限流导致刷新失败时也保留成功缓存，账号列表仍展示本次调度失败原因。
 
-Codex 启动和换号优先使用最近一次成功的额度缓存；能选出账号就直接启动，不等待其他账号刷新。其他账号未参与选号的诊断保留在日志和 `codex-accounts` 中，不主动发送“部分账号 MISS”警告。只有无法启动或继续任务时，才主动展示相应失败或等待状态。
+Codex 启动和换号优先使用最近一次成功的额度缓存；能选出账号就直接启动，不等待其他账号刷新；没有可用缓存时明确显示 MISS，后台继续刷新。其他账号未参与选号的诊断保留在日志和 `codex-accounts` 中，不主动发送“部分账号 MISS”警告。只有无法启动或继续任务时，才主动展示相应失败或等待状态。
 
 ## Claude Code 订阅
 
@@ -61,7 +65,7 @@ Codex 启动和换号优先使用最近一次成功的额度缓存；能选出
 
 账号和模型目录通过 Claude Code 原生 SDK 查询，模型与 effort 随目录更新；未登录会显示启用引导，查询失败显示 `MISS`。可选配置节为 `[token_source.claude-sub]`，支持 `enabled`、`display`、`model`、`effort`、`hidden_models` 和 `custom_models`。`enabled = false` 禁用，`enabled = true` 或省略时沿用本机登录检测；群命令更新该字段。
 
-订阅额度通过原生 `/usage` 控制接口读取，无需发送模型对话。`hi` 展示 5 小时、总周额度和接口返回的模型专属周额度及重置倒计时。回复底部同时显示 5 小时额度与周额度：本轮所选模型有专属周额度时显示该模型的额度，否则显示总周额度，沿用紧凑格式。查询失败或缺失数据显示 `MISS`，不使用旧额度替代，也不将缺失的专属额度改成总额度。此 SDK 查询接口仍属实验接口，版本不支持或接口变化时明确报错。
+订阅额度通过原生 `/usage` 控制接口读取，无需发送模型对话。`hi` 展示 5 小时、总周额度和接口返回的模型专属周额度及重置倒计时。回复底部同时显示 5 小时额度与周额度：本轮所选模型有专属周额度时显示该模型的额度，否则显示总周额度，沿用紧凑格式。后台瞬态查询失败保留成功缓存；没有缓存、认证失效或专属窗口缺数值时显示 `MISS`，不将缺失的专属额度改成总额度。此 SDK 查询接口仍属实验接口，版本不支持或接口变化时明确报错。
 
 订阅进程保留本机和项目的 Claude 设置，并在进程内清除其他来源的 API key、模型映射和中转路由。发送任务前会再次核对实际账号是否为第一方订阅。Claude native 继续保留为使用本机完整配置的来源。
 

package/docs/usage.md

@@ -145,6 +145,8 @@ curl -sS -X POST http://127.0.0.1:9876/notify \
 
 按钮点击结果可以 POST 到指定的本机 `callback`，或通过 `GET /notify/result/<notify_id>` 查询。需要文字回复时设置 `allow_reply: true`，卡片会提供“回复”按钮；文字回复模式与自定义按钮模式不能同时启用。字段和协议见 [feishu-notify Skill](../src/notify-skill.ts)。daemon 启动时会将该 Skill 同步到 Codex 和 Claude 的 Skill 目录。
 
+通知 JSON 正文上限为 4 MiB，超出返回 `413`；图片仍通过本地路径提供。按钮回调或文字回复发送期间若 daemon 中断，重启后会显示“送达状态未知”并禁止再次发送，请先向接收方核实处理结果。通知状态文件无法读取或 JSON 损坏会明确阻止启动，避免丢失去重记录后重复执行。
+
 ## 文件与生图
 
 Agent 用 `[[send: /abs/path]]` 交付本地文件。**默认沿用直接发送聊天附件的方式**，单文件不能超过 30 MB（30 × 1024 × 1024 字节）；超限需先压缩或分卷。原来的文件、图片消息通道保留。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leviyuan/lodestar",
-  "version": "0.18.25",
+  "version": "0.19.0",
   "publishConfig": {
     "access": "public"
   },