@leviyuan/lodestar 0.17.1 → 0.17.3

package/docs/AGENTS.md

@@ -0,0 +1,17 @@
+# 文档维护
+
+README 保留项目哲学、项目介绍、最短快速开始、常用指令表、附加能力的一句话说明及文档链接。精简时保留项目哲学原文；指令表分列完整指令与缩写/别名，每个指令独立一行，不把不同功能合并。附加能力逐项链接到具体用法。
+
+项目介绍以“项目特色”为标题，用列表描述使用场景与体验，配上具体能力说明。首页指令只列 `hi`、`model`（`md`）、`kill`（`kl`），其余指令放在 `usage.md`。
+
+详细内容按主题维护，事实以源码和测试为准。文件大小限制、生图展示规则、更新机制、配置与开发步骤放在对应文档，不堆进首页。
+
+- `configuration.md`：安装、CLI、运行目录、配置、Agent 自动更新与源码开发。
+- `usage.md`：群内命令、会话、worktree、文件与生图、本机通知。
+- `models.md`：账号、模型与 effort、OpenRouter 默认列表、DSH 与 GLM 接入。
+- `claude-agent-backend.md`：后端实现、模型路由和会话行为。
+
+- 保留 Codex、Claude、GLM、DeepSeek、OpenRouter、DeepSeek Harness 和 Claude native 的支持说明。
+- 只写已实现的行为。删除失效接口、历史方案、重复规则和无法复现的验证结论；不另建产品规范或计划。
+- 不记录凭据、真实 session id、群成员或本机配置。临时测试报告、排障流水和某次测试通过数不作为长期文档；维护文档保留可复现的验证方法及适用边界。
+- 文字变更检查引用的路径、方法和命令；伴随实现变化时按对应目录指引运行测试。

package/docs/claude-agent-backend.md

@@ -0,0 +1,121 @@
+# 后端与模型路由
+
+[返回首页](../README.md) · [账号与模型](models.md) · [安装与配置](configuration.md)
+
+Lodestar 通过 `AgentProcess` 接口连接 Codex app-server、Claude Agent SDK 和 DeepSeek Harness。`Session` 负责群会话、消息排队和卡片；具体进程类负责协议转换。主会话和委派 Agent 共用 `agent-launch.ts` 的启动入口。
+
+## 进程与会话
+
+| 行为 | Codex | Claude Code（含 GLM、DeepSeek、OpenRouter） | DeepSeek Harness |
+| --- | --- | --- | --- |
+| 进程 | `codex app-server --listen stdio://`，通过 JSON-RPC 通信 | SDK `query()`，通过 `AsyncIterable<SDKUserMessage>` 连续输入 | Node 子进程，通过 Cordis stdio 桥接 |
+| 初始化 | 等待初始化和 thread 启动事务完成 | 首条输入才触发 `system/init`；启动时只检查早期错误 | `session/open` 完成原生会话创建或恢复并落盘 |
+| 恢复与分叉 | `thread/list`、`thread/fork(lastTurnId)` | 同目录 transcript、`forkSession`、`resumeSessionAt` | 原生持久化服务，以事件序号作为 checkpoint |
+| 澄清提问 | `item/tool/requestUserInput` | `canUseTool` 中处理 `AskUserQuestion` | `user-questions/request` |
+| 主动压缩 | `thread/compact/start` | 向 streaming input 发送 `/compact`，等待 `compact_boundary` | 原生 compaction 服务与事件 |
+| 后台任务 | app-server collab 子 Agent 事件 | SDK `task_*` 事件 | 原生子 Agent 与工具事件 |
+
+会话引用包含 provider、原生 session id 和 cwd。各后端分别保存恢复记录，切换后端不会共用同一段上下文。Claude fork 在首条输入前持久保存启动意图，获得新 session id 后才清除；历史会话通过原生 fork 接入新群，避免两个群写同一个会话。
+
+主动压缩没有固定完成时限，以完成事件为准，进程退出或报错时失败。Claude 明确返回 `Not enough messages to compact` 时视为无需压缩，普通 `result` 事件不能代替完成通知。
+
+## 账号和模型
+
+Token Source 管理账号凭据、模型目录、启动环境、默认模型、effort 和额度。内置来源如下：
+
+| 来源 | 配置和模型目录 |
+| --- | --- |
+| Codex subscription | 使用 Codex 登录态，模型来自 app-server `model/list` |
+| GLM Coding Plan | `[token_source.glm]` 或本机 Claude settings；模型来自兼容端点，可补录已验证模型 |
+| DeepSeek | `[token_source.deepseek]` 或本机 Claude settings；模型来自兼容端点，可补录已验证模型 |
+| OpenRouter | `[token_source.openrouter]` 或本机 Claude settings；默认十一家各一模型，账号目录验证能力，MD 面板维护增删 |
+| DeepSeek Harness | `[token_source.deepseek-harness]`；模型、effort 与上下文容量来自当前安装的 DSH 原生目录 |
+| DSH GLM Coding Plan | `[token_source.dsh-glm]` 或复用 `glm`；账号接口返回模型，DSH 原生适配器提供能力和推理档位 |
+| Claude native | 沿用本机 Claude 配置，目录来自 SDK `supportedModels()`；有其他已启用的 Claude 侧来源时让位 |
+
+`model` 按 Claude Code、Codex、DeepSeek Harness 分组，组 ID 由 `ELEMENTS.modelAgentGroup` 生成。两个 Agent 下的 DeepSeek 来源都显示为 DeepSeek，协议 id 保持不变。选账号后进入模型列表；多个档位才展示 effort 卡，只有一个档位时直接应用，获取失败显示 `MISS`。同 provider/source 的切换调用 `setModelSettings`：Claude 和 DSH 从后续 turn 使用，Codex 保存选择并在重启进程后应用。跨 provider/source 或需要变更项目启动配置时，只能在空闲状态更换进程。
+
+除 OpenRouter 保留默认十一项的显式列表外，所有来源由 `withModelVisibility` 在真实接口目录上应用 `hidden_models`。接口项通过显示/隐藏调整可见性，新增上游模型自动进入列表。所有来源都支持用 `custom_models` 补录列表外模型，`origin` 区分接口项和补录项；GLM / DeepSeek 会先做端点验证，补录模型可直接选择请求档位使用，DSH 原生解析目录外模型，其余来源使用 Agent 请求档位；不能用目录白名单挡住用户补录。接口收录同名模型后按接口项管理，不重复展示。
+
+`tokenSourceRuntimeModel(s)` 使用完整能力目录，隐藏不修改会话、`model`、`effort`、slots 或启动配置指纹。`model_custom_remove` 只删除补录项，拒绝删接口项；删除前要求会话不再选用该项，并清理默认模型和 slots 的悬空引用。补录/删除和显示/隐藏均串行写配置，旧面板失效。
+
+大模型目录每页 20 项，`model_page` 回调携带 `panel_id`、`source_id`、`page`，只使用服务端保存的目录快照并校验页码。切页后只接受当前页的模型选择；过期面板拒绝操作。
+
+`md` 等待模型目录刷新完成后生成账号卡。刷新开始会清空能力数据，不能先取此时的空数组生成“0 个模型”卡片；失败状态显示 `MISS`，用户明确清空的就绪列表才显示零项。面板记录实际 `message_id`，在模型列表、添加目录和分页间保持一致。
+
+活跃、续卡和结束 footer 的模型标识共用 `footerModelLabel`，固定为 `agent · 模型名/effort`，Agent id 小写，模型名剥除 `claude:`、`[1m]`；模型或 effort 缺失时显示对应的 `MISS`。footer 的窗口额度保留原格式 `4.1h·7%·[6.9d·17%]`，即重置倒计时与已用百分比，周窗口放在方括号中；不添加“额度 5h 已用”等标签或月度工具明细。结构化余额通过 `unifiedUsageSummary` 显示 `余额 $…` / `余额 ¥…`，控制台仍可展示完整窗口明细。失败明确显示 MISS。
+
+`[claude.models.<name>].model` 保留旧 `claude:<name>` 路由的解析。账号、显示名和模型目录由 Token Source 管理；Claude 槽位映射使用账号的 `slots`。
+
+## Claude 启动配置
+
+GLM、DeepSeek、OpenRouter 等来源先清除冲突的 Anthropic 环境变量（含模型角色、OAuth 和云供应商选择），再注入各自凭据；默认读取 `project`、`local` settings。Claude native 沿用本机环境并读取 `user`、`project`、`local`。Token Source 指定的 settings 来源优先；未绑定 Token Source 时才使用项目 `setting_sources`。给注入凭据的来源加上 `user` 会重新引入本机 settings 中的路由。
+
+`[projects.<name>]` 的 `cwd` 对所有后端生效；`setting_sources`、`strict_mcp` 用于 Claude，`tools`、`load_project_mcp` 用于 Claude 和 DSH 主会话。Claude 主会话默认发现项目 `.mcp.json`。排除 user settings 的 Claude 会话通过 SDK 本地插件加载 daemon 管理的 Skill，安装内容统一由 `managed-skills.ts` 生成。
+
+`[claude].bin` 可指定包装器，路径无效时启动失败；Windows `.cmd`/`.bat` 通过 shell shim 启动。未指定时使用独立运行目录中的 Claude Agent SDK 默认入口及其自带程序。
+
+Claude 使用 `permissionMode: default`：普通工具在 `canUseTool` 中放行，`AskUserQuestion` 等待用户回答。不能改成 `bypassPermissions`，否则 SDK 会绕开提问回调。
+
+## OpenRouter
+
+- 来源 id 为 `openrouter`，通过 factory 注册 `openrouter-setup`。默认根地址 `https://openrouter.ai/api`，粘贴的 `/api/v1` 会规范成 SDK 根地址。API key 注入 `ANTHROPIC_AUTH_TOKEN`，`ANTHROPIC_API_KEY` 显式置空，模型 slug 完整透传，不自动追加 `[1m]`。
+- 主会话和委派共用 `agent-launch.ts`，将所选模型传给 `spawnEnv`。辅助角色在进程启动时绑定所选模型，可用 `slots` 配置 opus/sonnet/haiku；主模型后续切换不改动进程启动时的辅助角色。
+- 默认列表由 `src/openrouter-defaults.ts` 定义，共十一项，详见[账号与模型](models.md#openrouter)。账号目录来自 `GET /api/v1/models/user`，遵循账号供应商、隐私和 guardrail 设置；过滤 OpenAI、GLM、DeepSeek 等被排除厂商、自动路由、非文本输出、无 tools 和 `:batch` 模型。厂商排除也在启动路由和 slot 校验中执行。
+- `modelSelection` 保存可见模型 id 和完整允许候选；`models` 只暴露面板可见项。`model_list_open` / `model_add` / `model_remove` 对应接口项显示/隐藏，服务端校验当前页、模式与配置版本。`model_custom_remove` 删除补录记录，不能用于接口项；厂商排除也应用于手动补录。
+- `models` 未配置时使用默认十一项，空字符串表示用户主动清空，不能当作未配置。默认模型、effort、slots、Key 及相邻配置节保留；启动和 slots 按完整允许目录验证。上游不再返回的已选项显示 `unavailableReason`，不能启动，但可以删除。
+- effort 来自 `reasoning.supported_efforts`，仅暴露 Claude SDK 支持的档位；显式 `null` 表示全部网关档位。没有 effort 选择器的模型使用 `default`，含义是请求不携带 `output_config.effort`，不代表关闭推理，选择模型后直接应用并跳过 effort 卡。其他缺失的默认档位保留 `null`，要求用户明确选择。已选榜单代表模型使用榜单明确的档位或账号目录的默认档位。
+- `default` 用显式启动档位配合子进程环境中的 `CLAUDE_CODE_EFFORT_LEVEL=unset`，避免 CLI 为请求补上 effort。`settings.env` 不能替代真实环境，单纯省略 SDK 选项也不成立。显式 `max` 通过 `effortLevel: 'max'` 下发，不能映射成 `ultracode`。
+- `modelEnvironmentRevision` 参与进程配置比较。`default` 与显式档位之间切换需要新进程环境，Session 在空闲时保存并恢复原生 session；相同模式继续走 `setModelSettings`。slots 不能混合两种参数模式，避免辅助任务继承不适用的环境。模型切换不触发 daemon 重启。
+- 余额直接来自 `GET /api/v1/credits`：`total_credits - total_usage`，USD。权限以实际 HTTP 结果为准；失败显示 `余额 MISS`，不能改用 `/key` 限额、单 Key 累计用量或旧余额。
+- HTTP、网络、畸形响应及无效显式配置均报告失败；目录刷新失败后清空旧能力数据，不改用公开目录或另一模型。Claude 进程禁用模型 fallback。`thinking_tokens` 转为实时估计进度，不计入真实 token 用量；空工具名记录诊断并显示 `MISS`。
+
+接口依据：[Claude Code 接入](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration)、[账号模型目录](https://openrouter.ai/docs/api/api-reference/models/list-models-filtered-by-user-provider-preferences-privacy-settings-and-guardrails)、[推理档位](https://openrouter.ai/docs/guides/best-practices/reasoning-tokens)、[账户余额接口](https://openrouter.ai/docs/api/api-reference/credits/get-credits)。官方兼容保证限于 Anthropic 第一方供应商，其他模型需另做真实 Agent 会话验证。
+
+## DeepSeek Harness 原生后端
+
+`DshProcess` 使用当前安装的运行目录启动 Node DSH 子进程，以 `sdk` profile 加载 `dsh-bridge` Cordis 插件，替换默认 SDK JSON-RPC server。Lodestar 的 stdio 协议只承载控制和事件；Agent 循环、工具执行、持久化及子 Agent 由 DSH 管理。
+
+Agent 运行依赖由 `src/agent-updates.ts` 独立安装，daemon 启动时不检查或更新。自动更新默认关闭；手动运行 `lodestar-update --agents-only`，或在 `[runtime.agent_auto_update]` 中分别开启 `codex`、`claude`、`dsh` 后，各自每 6 小时检查 upstream latest。安装成功直接启用，旧任务继续使用各自目录。DSH 子包的 dist-tag 可能不同步，因此从主包最新版本递归读取 dependencies/peerDependencies/optionalDependencies，整族安装该次动态选中的版本。不存在兼容版本白名单；不兼容直接报告并后续适配。`dsh-bridge` 被放入选中运行目录，从同一依赖树加载，握手版本来自实际 package.json。开发依赖和 Bun 锁文件只是本地测试快照，不限制生产更新。普通安全 overrides 同时用于独立运行目录，tarball 验收真实执行更新器、包审计和原生查询。
+
+- `session/open` 完成原生 create/resume/fork 并 flush 后才公布恢复点。`rs` 通过原生持久化服务列出同工作目录会话；`fk/bk` 使用 `turn/end` 的事件序号作为 checkpoint，原生日志验证并加载分叉历史。
+- 实时文本来自 `agent/assistant-stream`，工具和计划来自会话事件。进入 idle 后等待持久化完成，再用真实 `turn/end` 原因结算；认证失败、token 耗尽及驱动异常均向调用方报告。
+- 子工具返回的内容块数组先转换为后台卡摘要；不能按字符串直接处理。致命桥接错误会把未结束的子任务标记失败，并将进程退出作为异常向用户报告。
+- 提问通过 `user-questions/request` 停驻，复用飞书问答卡；回答按原始 question id 返回。主动和自动压缩使用 DSH compaction 服务与事件。
+- 模型与 effort 更新在下一轮应用，同一轮的工具续跑保持当前路由。`off` 是 DSH 原生推理选项。
+- `dsh-glm` 接入 Coding Plan 的 `/api/coding/paas/v4/models` 与 `/chat/completions`。显式配置优先，否则复用已有 GLM 账号；凭据变化参与 `spawnRevision`。`dsh-runtime` 通过私有 composition patch 启用原生 `llm-pi-ai` 的 `zai-coding-cn` / `zai` 路由并关闭 DeepSeek 适配器，patch 仅记录环境变量名，不写明文 Key。
+- GLM 可选列表来自账号接口并合并手动补录，通过 pi-ai models 配置提供请求档位，`supportsReasoningEffort` 明确启用所选档位的传递；本地安装目录未收录的新模型也能使用。`LODESTAR_DSH_*` 控制路由，跨来源先清除冲突环境，不能复用旧的 DeepSeek 凭据或默认模型。
+- 每个进程默认读取项目 `.mcp.json` 的 stdio/HTTP MCP，并加载 `.agents/skills`、`.dsh/skills` 和 Lodestar 管理的 Skill。项目 `tools` 和 `load_project_mcp` 对 DSH 生效。
+- 图片 MIME 由文件字节识别。飞书下载的 JPEG 可能使用 `.png` 文件名，不能据扩展名声明编码；无法识别的图片明确报错。
+- 运行状态保存在 `src/paths.ts` 的 `DSH_HOME_DIR`。不读取用户 DSH settings 或凭据文件；`DEEPSEEK_API_KEY`、`DEEPSEEK_BASE_URL` 由选定账号显式注入。默认 telemetry 插件不加载。
+- 委派 worker 与原生子 Agent 均禁止继续派工。主 Agent 的 Lodestar capability 通过原生 ShellEnv 按执行者注入，子 Agent 的 shell 不继承它；Agent CLI 识别这一专用上下文。
+- 中断使用不可变原因对象，避免 Node fetch 附加 `stack` 属性后破坏 DSH 的无损 JSON 日志校验。关闭先回收 Agent，再通过协议、stdin EOF 与精确子进程终止确认退出。
+
+需要 Node 22.19+（22.x）或 Node 24+；`[token_source.deepseek-harness].bin` 指定 Node 路径。DSH 是开发者预览版，升级依赖时须同步检查桥接协议并运行原生集成测试。`src/dsh-process.test.ts` 使用真实运行时和本地模拟模型/MCP，不连接飞书或付费 API。
+
+接口依据：[GLM Coding Plan 快速开始](https://docs.bigmodel.cn/cn/coding-plan/quick-start)、[DSH 模型供应商配置](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.md)。
+
+## 共享事件和委派
+
+各进程类将原生文本、工具、结果、用量、压缩和后台任务转换成 `AgentProcess` 事件。共享事件由 Session 和卡片消费，保留各后端在初始化、上下文和后台任务上的差异。
+
+委派只有一层：主 Agent 可以并行派工、回答问题和续跑原生会话，被委派的 Agent 不得继续调用其他 Agent。Skill、worker 提示词及运行时入口共同遵循该规则；worker 关闭 Codex `multi_agent` 或 Claude `Agent`/`Task`，保留其余代码工具、项目 MCP 和独立调用凭据。历史父子记录仍保留以便读取与清理。运行状态原子落盘，大段输入输出单独存放；委派会话登记后从主群的历史列表中排除。
+
+委派卡片将整体进度放在顶部，按执行者展示结果、待回答问题和失败原因。单个 Agent 的完成结果默认展开，多个 Agent 的结果分别折叠；不展示 depth、session id 或 request id。
+
+## 源码与验证
+
+- 启动与协议：`src/agent-launch.ts`、`src/agent-process.ts`、`src/codex-process.ts`、`src/claude-agent-process.ts`、`src/dsh-process.ts`、`src/dsh-runtime.ts`、`src/dsh-bridge.ts`。
+- 路由与配置：`src/token-source*.ts`、`src/session-model.ts`、`src/config.ts`、`src/claude-models.ts`。
+- 会话分支：`src/conversation.ts`、`src/session-temp.ts`、`src/temp-session-runtime.ts`、`src/feishu.ts`。
+- 委派：`src/agent-service.ts`、`src/agent-runner.ts`、`src/agent-session-registry.ts`。
+
+本地检查使用 `bun run typecheck`、`bun test` 和 `bun run build`。真实后端与飞书交互使用以下探针，运行前阅读[脚本说明](../scripts/AGENTS.md)，明确账号、目标群和允许的副作用。
+
+| 脚本 | 验证内容与运行条件 |
+| --- | --- |
+| [test-openrouter.ts](../scripts/test-openrouter.ts) | 真实 API/SDK 工具调用、model/effort 参数与原生 resume；显式提供私有凭据、输出目录和 `--agent-runtimes`，不连接飞书 |
+| [test-dsh-glm.ts](../scripts/test-dsh-glm.ts) | 使用已配置的 GLM Coding Plan 验证 DSH 工具调用与原生 resume，只操作私有临时目录，不连接飞书 |
+| [test-model-panel-live.ts](../scripts/test-model-panel-live.ts) | 在指定群和已有 daemon 上验证模型面板回调、显示/隐藏、补录/删除及回复；发送测试消息并临时修改模型设置，结束后恢复 |
+
+模型面板探针覆盖服务端回调与真实飞书消息更新；客户端点击手势需另外验证。校验卡片时读取 `raw_card_content`，并等待同一回复卡的最终 footer；布局或协议变更后需在加载新代码的 daemon 上重新验证。

package/docs/configuration.md

@@ -0,0 +1,79 @@
+# 安装与配置
+
+[返回首页](../README.md) · [模型与账号](models.md)
+
+## 安装与运行
+
+支持 Windows、macOS 和 Linux，需要 Node.js ≥ 18.15。Bun 用于源码开发和构建。
+
+DeepSeek Harness 子进程另需 Node 22.19+（22.x）或 Node 24+；可通过其账号配置的 `bin` 指定 Node 可执行文件。
+
+```bash
+npm i -g @leviyuan/lodestar
+lodestar-setup
+```
+
+向导会配置 Claude Code、可选的 GLM API key、飞书应用和项目目录，并启动 daemon；也可以同时配置 Codex 登录。Claude 按 API key 方式配置。
+
+把机器人拉进群，群名设为 `projects_root` 下的目录名。目录不存在时会自动创建。首次消息默认使用 Claude 侧已配置的账号；发 `model` 可切换到其他账号。
+
+安装后提供以下命令：
+
+| 命令 | 作用 |
+| --- | --- |
+| `lodestar-setup` | 配置向导 |
+| `lodestar-daemon` | 启动 daemon |
+| `lodestar-stop` | 停止 daemon |
+| `lodestar-update` | 升级 Lodestar 及实际使用的 Codex、Claude Code/SDK、DSH；`--agents-only` 仅立即更新 Agent |
+| `lodestar-version` | 查看 Lodestar、实际 Agent 版本、运行目录及更新错误 |
+| `lodestar-agent` | 由会话中的 Agent 调用其他模型执行任务 |
+
+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。旧版布尔总开关按原值兼容映射为三项并提示迁移，不可与新配置表混用。
+
+运行文件放在 Lodestar 数据目录的 `agent-runtimes/` 下，每个版本使用独立目录；更新只切换新进程所用的目录，保留正在运行任务的程序和 SDK。Windows 下也不覆盖、重命名或删除正在使用的旧版 EXE/DLL。取消安装时按安装器 PID 终止其进程树，并等待退出；若无法确认终止，保留可能被占用的临时目录并报告错误。
+
+查询或安装失败会明确报错，`lodestar-version` 可查看错误；不会静默改用旧安装。文件占用只做有限重试，最终失败仍显示。显式配置的 `[claude].bin` 按该路径执行。
+
+长期运行可交给 Linux `systemd --user`、macOS `launchd` 或 Windows 任务计划程序。daemon 重启后会恢复上次活跃的会话。
+
+## 本机配置
+
+默认配置文件是 `~/.config/lodestar/config.toml`，可通过 `LODESTAR_CONFIG` 指定文件。日志和会话状态位于 `~/.local/share/lodestar/`；Windows 使用相应的应用数据目录。完整路径定义见 [src/paths.ts](../src/paths.ts)。
+
+```toml
+[runtime]
+projects_root = "/abs/projects"
+live_elapsed = "bucket"      # bucket 按档位刷新耗时；second 按秒刷新
+
+[runtime.agent_auto_update] # 三项独立，默认关闭；启动时不检查
+codex = false
+claude = false
+dsh = false
+
+[projects.calculator]
+cwd = "/abs/projects/calculator"  # 对所有后端均生效
+setting_sources = "project"       # Claude 后端；仅未绑定 Token Source 时使用
+strict_mcp = "true"               # Claude 主会话
+load_project_mcp = "true"         # Claude / DSH 主会话
+tools = "Read,Write,Edit,Bash,Glob,Grep"  # Claude / DSH 主会话
+
+[claude]
+bin = "/abs/path/to/claude-wrapper"  # 可选的 Claude 可执行文件
+```
+
+账号配置、OpenRouter 默认模型和 DSH 接入见[模型与账号](models.md)。手动修改配置后需重启 daemon；群内设置自行保存。
+
+## 源码开发
+
+安装 Bun，在仓库根目录运行：
+
+```bash
+bun install
+bun run typecheck
+bun test
+bun run build
+```
+
+完成配置后用 `bun run start` 从源码启动。维护规则见[项目指引](../AGENTS.md)；真实飞书探针会操作目标群，使用前阅读[脚本说明](../scripts/AGENTS.md)。

package/docs/models.md

@@ -0,0 +1,84 @@
+# 账号、模型与 effort
+
+[返回首页](../README.md) · [安装与配置](configuration.md) · [群内用法](usage.md)
+
+账号配置使用 `[token_source.glm]`、`[token_source.deepseek]` 等节。GLM、DeepSeek 和 OpenRouter 也可以从本机 Claude settings 中识别；识别后由对应 Token Source 注入凭据，避免不同账号的环境变量串用。项目的工具限制只作用于主会话，委派 Agent 使用完整工具集。
+
+## 选择与管理模型
+
+发送 `model`（`md`），在 Claude Code、Codex、DeepSeek Harness 分组下选择账号，再选择模型。有多个推理档位（effort）时继续选择档位，只有一个档位时直接应用。
+
+| 操作 | 作用 |
+| --- | --- |
+| 选 | 使用该模型，按需继续选择推理档位 |
+| 隐 / 显 | 隐藏或显示接口目录中的模型，不改变当前运行模型 |
+| 补录模型 | 添加接口目录外的模型，可选择推理档位并使用 |
+| 删 | 删除补录记录；仍有会话选用时需先切换模型 |
+
+除 OpenRouter 使用内置默认列表外，各来源默认显示接口目录中的模型，新模型会随目录刷新出现。所有来源都支持补录，记录保存在 `custom_models`；支持端点验证的来源会先验证。目录未收录不会阻止选择，实际不支持的请求由后端报告错误。接口后来收录同名模型时自动转为接口项，不重复显示。删除补录记录也会清理默认模型和辅助模型中的相关引用。
+
+同账号切换 Claude 或 DSH 模型从后续回复生效；Codex 的持久设置需重启会话生效。跨账号或后端切换只允许在空闲时进行。来源禁用或目录获取失败显示 `MISS`。
+
+## 额度
+
+发送 `hi` 查看会话和账号额度。GLM 展示套餐与各窗口用量；Codex 展示额度窗口和账号可用的重置卡次数。
+
+回复底部显示 `agent · 模型名/effort`，其中 Agent 为 `claude`、`codex` 或 `dsh`。窗口额度如 `4.1h·7%·[6.9d·17%]`，分别表示重置倒计时与已用百分比，方括号内为周窗口；余额显示 `余额 $12.34` 或 `余额 ¥12.34`。读取失败显示 `MISS`，Codex 的短暂网络失败会有限重试。
+
+## OpenRouter
+
+OpenRouter 通过 Claude Agent SDK 运行。在群内发送 `openrouter-setup <api_key>`，再通过 `model` 面板选择模型和 effort；自建兼容端点用 `openrouter-setup <base_url> <api_key>`。也可在配置文件中添加：
+
+```toml
+[token_source.openrouter]
+agent = "claude"
+api_key = "填写自己的 OpenRouter API key"
+# base_url = "https://openrouter.ai/api" # SDK 自动追加 /v1/messages
+# model = "anthropic/claude-fable-5.1"   # 可选：默认运行模型，须获账号目录确认
+# effort = "max"                       # 可选：仅覆盖默认运行模型的档位
+# models = "anthropic/claude-fable-5.1,moonshotai/kimi-k3" # 可选：自定义可选列表
+# slots = "haiku=anthropic/claude-fable-5.1" # 可选：辅助任务模型，须获账号目录确认且使用相同的 effort 参数模式
+```
+
+内置默认列表包含以下 **11 项**，定义见[默认模型配置](../src/openrouter-defaults.ts)。这是项目提供的初始列表，可在面板中自行调整。
+
+| 厂商 | 模型 ID | 默认档位 |
+| --- | --- | --- |
+| Anthropic | `anthropic/claude-fable-5.1` | max |
+| Moonshot | `moonshotai/kimi-k3` | max |
+| Tencent | `tencent/hy4-preview` | high |
+| Google | `google/gemini-3.8-flash` | high |
+| SpaceXAI | `x-ai/grok-4.5` | high |
+| Alibaba | `qwen/qwen3.8-max-0902` | xhigh |
+| Meta | `meta/muse-spark-1.2` | xhigh |
+| Xiaomi | `xiaomi/mimo-v2.5-pro` | 模型默认 |
+| MiniMax | `minimax/minimax-m3` | 模型默认 |
+| 字节跳动 | `bytedance-seed/seed-2-1-turbo` | 模型默认 |
+| 美团 | `meituan/longcat-2.0` | 模型默认 |
+
+在 `md` → Claude Code → OpenRouter 中，点「显示模型」进入账号目录，再点「显」加入列表，点「隐」移出面板列表。可见性自动保存，不改当前运行模型；全部隐藏后也能继续显示或补录。未配置 `models` 时才使用上述十一项；`models = ""` 表示没有已显示的接口模型，刷新或重启不会补回默认项。内置列表更新不会覆盖用户维护的列表。
+
+候选目录来自 `/api/v1/models/user`，按账号供应商和隐私设置筛选，仅纳入支持文本和工具调用的交互模型；OpenAI、GLM、DeepSeek 及无法保证厂商范围的自动路由不会出现在添加候选中。目录刷新失败显示 `MISS`。显式配置但已下线的模型保留为可删除的 `MISS` 项。
+
+effort 按上游声明提供。小米、MiniMax、字节等没有 effort 选择器的模型直接选用原生默认行为，跳过 effort 卡，实际请求不携带 effort 参数。两种参数模式之间切换时，空闲进程会保存原生会话并在下一轮用新环境恢复；相同模式下继续使用 SDK 热切换。未配置 `model` 时需要通过面板明确选择运行模型。
+
+OpenRouter 余额来自 `/api/v1/credits`，按 `total_credits - total_usage` 计算；接口权限和错误以实际响应为准。账号目录可见不代表所有工具和请求都能成功，上游拒绝或路由不可用会明确报错。兼容接口、模型与档位的处理见[后端说明](claude-agent-backend.md#openrouter)。
+
+## DeepSeek Harness
+
+DeepSeek Harness 使用独立的 `[token_source.deepseek-harness]` 账号与原生会话。在群内发送 `deepseek-harness-setup <api_key>`，再通过 `model` 面板选择该来源即可启用。自建端点用 `deepseek-harness-setup <base_url> <api_key>`；这里使用原生 API 根地址，不带 `/anthropic`。
+
+```toml
+[token_source.deepseek-harness]
+agent = "dsh"
+api_key = "填写自己的 API key"
+# bin = "/abs/path/to/node"  # 可选：运行 DSH 的 Node 可执行文件
+# model = "deepseek-v4-pro" # 可选：默认模型
+# effort = "high"          # 可选：默认请求档位
+```
+
+### GLM Coding Plan
+
+DSH 也支持 GLM Coding Plan：已有 `[token_source.glm]` 时自动复用该账号，在 `md` → DeepSeek Harness → GLM Coding Plan 中选择模型。独立凭据用 `dsh-glm-setup [base_url] <api_key>`，配置节为 `[token_source.dsh-glm]`。它调用 Coding Plan 的 OpenAI 端点，复用 GLM 额度查询；不经过 OpenRouter 或 Claude SDK。账号接口模型和补录模型一起交给原生适配器，均可选择请求档位；接口项用「隐 / 显」，补录项用「删」。
+
+手动修改配置后需重启 daemon；群内账号启用和模型补录会自行重载相关配置。模型路由、配置优先级和后端差异见 [后端说明](claude-agent-backend.md)。

package/docs/usage.md

@@ -0,0 +1,77 @@
+# 群内使用指南
+
+[返回首页](../README.md) · [模型与账号](models.md)
+
+## 群内命令
+
+直接发送下列词语，不加斜杠，大小写不敏感。这些命令控制当前群的 Agent 会话。
+
+| 完整指令 | 缩写 / 别名 | 行为 |
+| --- | --- | --- |
+| `hi` | — | 打开控制台；会话未运行时先启动 |
+| `model` | `md` | 按 Agent 分组选择账号，再选择模型与推理档位（effort）并保存 |
+| `stop` | `st` | 打断当前回复并取消排队消息，保留进程 |
+| `kill` | `kl` | 关闭当前 Agent 进程，保存可恢复的会话记录 |
+| `restart` | `rs` | 进程存活时打断并恢复当前会话；已停止时列出同目录的历史会话，选择后创建独立分支 |
+| `clear` | `cl` | 关闭当前进程并开始新会话；已停止时提示先启动 |
+| `compact` | `cm` | 压缩当前会话的上下文 |
+| `agents` | `agent` | 查看可调用的 Agent 身份及可用状态 |
+| `task` | — | 创建、查看或删除绑定的飞书任务清单 |
+
+模型列表来自各账号的模型目录，获取失败显示 `MISS`。同账号切换 Claude 或 DSH 模型从后续回复生效，Codex 的持久模型设置需重启会话生效；跨账号或后端切换只允许在空闲时进行。账号接入、模型补录与额度说明见[账号与模型](models.md)。
+
+## 独立工作区
+
+需要独立修改文件时，在项目主群使用 worktree：
+
+| 完整指令 | 缩写 / 别名 | 行为 |
+| --- | --- | --- |
+| `worktree` | `wt` | 列出项目的 `work/*` 分支和工作区状态 |
+| `worktree feature-x` | `wt feature-x` | 创建或加入 `<project>[feature-x]` 群和同级 worktree 目录，使用 `work/feature-x` 分支 |
+
+已合并且未挂载的分支会折叠隐藏，再次启用时更新到主线。卡片上的“删”会检查对应群没有运行中的会话、工作区没有未提交变更，再解散群并删除 worktree；Git 分支保留。
+
+## 临时会话与对话分支
+
+临时会话共享当前工作目录，适合在同一项目里另开一段对话：
+
+| 完整指令 | 缩写 / 别名 | 行为 |
+| --- | --- | --- |
+| `btw` | — | 创建 `<session>*MMDD-HHMM` 临时群，继承账号、模型和工作目录，启动新会话 |
+| `fork` | `fk` | 选择一条用户输入，在临时群里从这条输入之前分叉 |
+| `back` | `bk` | 选择一条用户输入，让本群接到这条输入之前的新分支 |
+| `bye` | — | 停止并解散当前临时群，仅适用于 Lodestar 创建的临时群 |
+
+`fk`、`bk` 和从历史记录恢复的 `rs` 都使用后端原生 fork，保留源对话。选第 N 条输入表示回到它发出之前，选中的输入不包含在新分支内。Claude 的新分支在首条输入时获得会话 id，准备状态会持久保存。
+
+**分叉和回退只改变对话历史，不回滚文件或撤销 Shell、MCP 等外部操作。** `bk` 会附上已观察到的文件变更记录；需要目录隔离时使用 `wt`。
+
+## 多模型任务
+
+主 Agent 可以通过 `lodestar-agent` 查询实时身份，再把任务交给一个或多个模型。同一个任务选择多个身份时并发执行；后续追问可继续使用各模型的原生会话。
+
+被调用的 Agent 可以编辑文件、执行命令、使用 MCP 和 Skill；委派只允许一层，被调用的 Agent 不能继续派工。它们与主 Agent 共享工作区，修改会立即可见。运行状态和结果通过卡片展示；需要用户输入时暂停，由主 Agent 回填答案后继续。委派产生的会话不会混入主群的 `rs` 历史列表。
+
+`lodestar-agent` 只能在 Lodestar 管理的 Agent 进程里调用。命令用法见 [Agent Skill](../src/agent-skill.ts)。
+
+## 飞书任务清单
+
+发 `task`，点“启用”可创建并绑定 `<project>[lodestar]` 任务清单。删除需要在卡片上再次确认，会删除整个清单及其中任务。该面板管理清单绑定，任务执行由用户和 Agent 安排。
+
+## 本机通知
+
+脚本可通过 HTTP 向项目群发送通知，支持 `info`、`warn`、`error`，以及本地图片、交互按钮或文字回复：
+
+```bash
+curl -sS -X POST http://127.0.0.1:9876/notify \
+  -H 'Content-Type: application/json' \
+  -d '{"project":"ops","level":"error","text":"构建失败，截图如下","images":["/abs/shot.png"]}'
+```
+
+按钮点击结果可以 POST 到指定的本机 `callback`，或通过 `GET /notify/result/<notify_id>` 查询。需要文字回复时设置 `allow_reply: true`，卡片会提供“回复”按钮；文字回复模式与自定义按钮模式不能同时启用。字段和协议见 [feishu-notify Skill](../src/notify-skill.ts)。daemon 启动时会将该 Skill 同步到 Codex 和 Claude 的 Skill 目录。
+
+## 文件与生图
+
+单个出站文件不能超过 **30 MB**（30 × 1024 × 1024 字节）。Agent 在交付前检查大小，超限先压缩或分卷；发送层也会拒绝超限文件。
+
+Codex 生图完成后，提示词和图片放在同一个折叠面板中，点击展开查看图片并放大预览。无法嵌入时，图片仍会单独发送。