@leviyuan/lodestar 0.21.4 → 0.21.6
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/README.md +2 -2
- package/dist/lodestar-agent.js +1 -1
- package/dist/lodestar.js +241 -241
- package/docs/AGENTS.md +1 -1
- package/docs/claude-agent-backend.md +6 -5
- package/docs/configuration.md +1 -1
- package/docs/models.md +3 -1
- package/docs/usage.md +12 -10
- package/package.json +1 -1
package/docs/AGENTS.md
CHANGED
|
@@ -11,7 +11,7 @@ README 保留项目哲学、项目介绍、最短快速开始、常用指令表
|
|
|
11
11
|
- `models.md`:账号、模型与 effort、OpenRouter 默认列表、DSH 与 GLM 接入。
|
|
12
12
|
- `claude-agent-backend.md`:后端实现、模型路由和会话行为。
|
|
13
13
|
|
|
14
|
-
- 保留 Codex、Claude
|
|
14
|
+
- 保留 Codex、Claude Code 订阅、GLM、DeepSeek、OpenRouter、PackyAPI 和 DeepSeek Harness 的支持说明。
|
|
15
15
|
- 只写已实现的行为。删除失效接口、历史方案、重复规则和无法复现的验证结论;不另建产品规范或计划。
|
|
16
16
|
- 不记录凭据、真实 session id、群成员或本机配置。临时测试报告、排障流水和某次测试通过数不作为长期文档;维护文档保留可复现的验证方法及适用边界。
|
|
17
17
|
- 文字变更检查引用的路径、方法和命令;伴随实现变化时按对应目录指引运行测试。
|
|
@@ -33,7 +33,8 @@ Token Source 管理账号凭据、模型目录、启动环境、默认模型、e
|
|
|
33
33
|
| PackyAPI | `[token_source.packy]`、`[token_source.packy-secondary]`;按令牌目录筛选模型,Claude 入口默认精选 MiniMax M、Opus、Fable、Qwen Max 家族最新版;Codex 入口精选 Kimi K、Grok 家族最新版,主令牌与 `packy-codex` 共用凭据 |
|
|
34
34
|
| DeepSeek Harness | `[token_source.deepseek-harness]`;模型、effort 与上下文容量来自当前安装的 DSH 原生目录 |
|
|
35
35
|
| DSH GLM Coding Plan | `[token_source.dsh-glm]` 或复用 `glm`;账号接口返回模型,DSH 原生适配器提供能力和推理档位 |
|
|
36
|
-
|
|
36
|
+
|
|
37
|
+
Claude 订阅统一由 `claude-sub` 管理登录验证、模型目录和额度,在 `md` 中选择“Claude Code 订阅”。
|
|
37
38
|
|
|
38
39
|
`model` 按 Claude Code、Codex、DeepSeek Harness 分组,组 ID 由 `ELEMENTS.modelAgentGroup` 生成。两个 Agent 下的 DeepSeek 来源都显示为 DeepSeek,协议 id 保持不变。选账号后进入模型列表;多个档位才展示 effort 卡,只有一个档位时直接应用,获取失败显示 `MISS`。同 provider/source 的切换调用 `setModelSettings`:Claude 和 DSH 从后续 turn 使用,Codex 保存选择并在重启进程后应用。跨 provider/source 或需要变更项目启动配置时,只能在空闲状态更换进程。
|
|
39
40
|
|
|
@@ -51,7 +52,7 @@ OpenRouter 和 PackyAPI 默认按指定家族从兼容目录筛选最新数字
|
|
|
51
52
|
|
|
52
53
|
## Claude 启动配置
|
|
53
54
|
|
|
54
|
-
GLM、DeepSeek、OpenRouter 等来源先清除冲突的 Anthropic 环境变量(含模型角色、OAuth 和云供应商选择),再注入各自凭据;默认读取 `project`、`local` settings。Claude Code 订阅读取 `user`、`project`、`local`,通过进程级 `settings` 覆盖冲突路由和 API key helper,不改本机文件;SDK `accountInfo()` 确认第一方订阅后才向 streaming input 放行用户输入。
|
|
55
|
+
GLM、DeepSeek、OpenRouter 等来源先清除冲突的 Anthropic 环境变量(含模型角色、OAuth 和云供应商选择),再注入各自凭据;默认读取 `project`、`local` settings。Claude Code 订阅读取 `user`、`project`、`local`,通过进程级 `settings` 覆盖冲突路由和 API key helper,不改本机文件;SDK `accountInfo()` 确认第一方订阅后才向 streaming input 放行用户输入。Token Source 指定的 settings 来源优先;未绑定 Token Source 时才使用项目 `setting_sources`。给注入凭据的来源加上 `user` 会重新引入本机 settings 中的路由。
|
|
55
56
|
|
|
56
57
|
`[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` 生成。
|
|
57
58
|
|
|
@@ -110,7 +111,7 @@ Agent 运行依赖由 `src/agent-updates.ts` 独立安装,daemon 启动时不
|
|
|
110
111
|
- 每个进程默认读取项目 `.mcp.json` 的 stdio/HTTP MCP,并加载 `.agents/skills`、`.dsh/skills` 和 Lodestar 管理的 Skill。项目 `tools` 和 `load_project_mcp` 对 DSH 生效。
|
|
111
112
|
- 图片 MIME 由文件字节识别。飞书下载的 JPEG 可能使用 `.png` 文件名,不能据扩展名声明编码;无法识别的图片明确报错。
|
|
112
113
|
- 运行状态保存在 `src/paths.ts` 的 `DSH_HOME_DIR`。不读取用户 DSH settings 或凭据文件;`DEEPSEEK_API_KEY`、`DEEPSEEK_BASE_URL` 由选定账号显式注入。默认 telemetry 插件不加载。
|
|
113
|
-
- 委派 worker 与原生子 Agent 均保留继续派工能力。Lodestar 调用上下文通过原生 ShellEnv 传给当前 Agent 及其后代,Agent CLI
|
|
114
|
+
- 委派 worker 与原生子 Agent 均保留继续派工能力。Lodestar 调用上下文通过原生 ShellEnv 传给当前 Agent 及其后代,Agent CLI 使用它保留项目、对话 ID(`chat_id`)和任务归属。
|
|
114
115
|
- 中断使用不可变原因对象,避免 Node fetch 附加 `stack` 属性后破坏 DSH 的无损 JSON 日志校验。关闭先回收 Agent,再通过协议、stdin EOF 与精确子进程终止确认退出。
|
|
115
116
|
|
|
116
117
|
需要 Node 22.19+(22.x)或 Node 24+;`[token_source.deepseek-harness].bin` 指定 Node 路径。DSH 是开发者预览版,升级依赖时须同步检查桥接协议并运行原生集成测试。`src/dsh-process.test.ts` 使用真实运行时和本地模拟模型/MCP,不连接飞书或付费 API。
|
|
@@ -121,11 +122,11 @@ Agent 运行依赖由 `src/agent-updates.ts` 独立安装,daemon 启动时不
|
|
|
121
122
|
|
|
122
123
|
各进程类将原生文本、工具、结果、用量、压缩和后台任务转换成 `AgentProcess` 事件。共享事件由 Session 和卡片消费,保留各后端在初始化、上下文和后台任务上的差异。
|
|
123
124
|
|
|
124
|
-
主 Agent、委派 Agent 和原生子 Agent 均可继续派工,不设置 Lodestar 委派层数上限,也不禁用各后端原生委派工具。Skill、worker 提示词和运行时入口保持一致;项目调用的非交互要求及调用方负责交付的规则沿委派链继承。Lodestar
|
|
125
|
+
主 Agent、委派 Agent 和原生子 Agent 均可继续派工,不设置 Lodestar 委派层数上限,也不禁用各后端原生委派工具。Lodestar Agent 不支持调用 Claude 订阅,遵守 Claude 用户协议;中转站等第三方来源的 Claude 模型仍可调用。限制仅按来源 ID 与类型判断,不按模型名称或显示名判断,主会话的 Claude 订阅能力不受影响。Skill、worker 提示词和运行时入口保持一致;项目调用的非交互要求及调用方负责交付的规则沿委派链继承。Lodestar 后续任务记录当前调用方作为父任务,续跑来源单独记录,取消沿父子关系传播。运行状态原子落盘,大段输入输出单独存放;委派会话登记后从主会话的历史列表中排除。
|
|
125
126
|
|
|
126
127
|
委派、原生子 Agent 和后台任务由同一个 `AgentCards` 实例展示。每项仅显示状态和一句说明,类型、进度、任务正文、结果、待回答问题及失败原因放在折叠体内,动作只展示最近三步。原生子 Agent 启动即展示,普通前台命令仍在观察池中;启动工具和 SDK task id 关联后只保留一项。
|
|
127
128
|
|
|
128
|
-
|
|
129
|
+
按对话 ID 定位消息尾部的委派卡,复用至容量用满或出现新消息;原任务继续在原卡更新,后台任务不再迁移。Card Kit 生命周期由共享卡片统一结算,停止主进程只结算其所属任务,不关闭仍有委派执行的共享卡;不展示 depth、session id 或 request id。
|
|
129
130
|
|
|
130
131
|
## 源码与验证
|
|
131
132
|
|
package/docs/configuration.md
CHANGED
|
@@ -28,7 +28,7 @@ lodestar-setup
|
|
|
28
28
|
| `lodestar-stop` | 停止 daemon |
|
|
29
29
|
| `lodestar-update` | 升级 Lodestar 及实际使用的 Codex、Claude Code/SDK、DSH;`--agents-only` 仅立即更新 Agent |
|
|
30
30
|
| `lodestar-version` | 查看 Lodestar、实际 Agent 版本及运行目录 |
|
|
31
|
-
| `lodestar-agent` |
|
|
31
|
+
| `lodestar-agent` | 调用已配置模型执行任务;不支持 Claude 订阅,遵守 Claude 用户协议,中转站等第三方 Claude 模型仍可调用 |
|
|
32
32
|
|
|
33
33
|
启动和停止命令会核对 PID 对应的实际入口,读取进程信息失败时明确报错。无法识别的运行时选项、macOS 无法区分边界的含空格入口、Windows 相对入口也会拒绝操作,请通过对应服务管理器处理。旧式单行 PID 文件缺少入口标识,`lodestar-stop` 会拒绝发送信号;请先核对该 PID 的完整命令行,再通过服务管理器或精确 PID 停止。停止命令以进程退出为准,删除 PID 文件不会被当作停止成功。
|
|
34
34
|
|
package/docs/models.md
CHANGED
|
@@ -67,7 +67,9 @@ Codex 启动和换号优先使用最近一次成功的额度缓存;能选出
|
|
|
67
67
|
|
|
68
68
|
订阅额度通过原生 `/usage` 控制接口读取,无需发送模型对话。`hi` 展示 5 小时、总周额度和接口返回的模型专属周额度及重置倒计时。回复底部同时显示 5 小时额度与周额度:本轮所选模型有专属周额度时显示该模型的额度,否则显示总周额度,沿用紧凑格式。后台瞬态查询失败保留成功缓存;没有缓存、认证失效或专属窗口缺数值时显示 `MISS`,不将缺失的专属额度改成总额度。此 SDK 查询接口仍属实验接口,版本不支持或接口变化时明确报错。
|
|
69
69
|
|
|
70
|
-
订阅进程保留本机和项目的 Claude 设置,并在进程内清除其他来源的 API key、模型映射和中转路由。发送任务前会再次核对实际账号是否为第一方订阅。Claude
|
|
70
|
+
订阅进程保留本机和项目的 Claude 设置,并在进程内清除其他来源的 API key、模型映射和中转路由。发送任务前会再次核对实际账号是否为第一方订阅。Claude 订阅统一使用“Claude Code 订阅”来源,`md`、`hi` 和回复底部共用该来源的账号与额度。
|
|
71
|
+
|
|
72
|
+
旧版“Claude”本机配置入口已移除;使用该入口的用户升级后请通过 `md` 选择“Claude Code 订阅”及模型。
|
|
71
73
|
|
|
72
74
|
## OpenRouter
|
|
73
75
|
|
package/docs/usage.md
CHANGED
|
@@ -104,9 +104,11 @@ WT 使用独立工作目录,其文件交付、项目工具/MCP 配置与主目
|
|
|
104
104
|
|
|
105
105
|
## 多模型任务
|
|
106
106
|
|
|
107
|
-
主 Agent 按任务和可用能力自行选择原生 subagent 或 `lodestar-agent
|
|
107
|
+
主 Agent 按任务和可用能力自行选择原生 subagent 或 `lodestar-agent`,也可通过 `lodestar-agent` 调用自身的模型或 Agent,但不能使用 Claude 订阅来源。使用 `lodestar-agent` 时先查询实时身份,再把任务交给一个或多个模型。同一个任务选择多个身份时并发执行;后续追问可继续使用各模型的原生会话。
|
|
108
108
|
|
|
109
|
-
|
|
109
|
+
Lodestar Agent 不支持调用 Claude 订阅,遵守 Claude 用户协议;中转站等第三方来源的 Claude 模型仍可调用。限制只按来源判断,不按模型名称判断;主会话的 Claude 订阅能力和原生委派工具保持可用。
|
|
110
|
+
|
|
111
|
+
被调用的 Agent 可以编辑文件、执行命令、使用 MCP 和 Skill,也可以通过 Lodestar 或原生子 Agent 继续派工,Lodestar 不设置委派层数上限。它们与主 Agent 共享工作区,修改会立即可见。会话委派需要输入时暂停,由调用方回填答案后继续;项目调用及其后续委派保持非交互执行。委派产生的会话不会混入主会话的 `rs` 历史列表。
|
|
110
112
|
|
|
111
113
|
首层任务默认使用主 Agent 的工作目录,后续委派默认使用调用方的执行目录,不受调用命令时 Shell 当前目录影响。可用 `--workdir <路径>` 指定其中已存在的子目录:相对路径以主 Agent 的工作目录为基准,也支持范围内的绝对路径。路径会解析软链接,越界、目录不存在或指向普通文件都会报错。同一个 run 的多个 Agent 使用同一目录;需要不同目录时分别发起任务。
|
|
112
114
|
|
|
@@ -117,7 +119,7 @@ lodestar-agent run --identity '<identity-id>' --description '检查应用代码'
|
|
|
117
119
|
|
|
118
120
|
每次 `run` 和 `follow-up` 必须填写 `--description`(不超过 60 字的单行说明)。委派任务、原生子 Agent 和后台任务统一收在委派卡里,每项只显示状态和一句说明,展开可看任务类型、正文、结果、错误和最近三步动作。子 Agent 启动即展示,普通前台命令不会额外生成任务项;任务结束后显示实际耗时。
|
|
119
121
|
|
|
120
|
-
|
|
122
|
+
委派卡仍在绑定对话 ID 的消息尾部时,新任务继续追加;容量满或该对话 ID 下出现新消息(包括主 Agent 新开的会话卡)后,下一项另开卡。旧任务继续原地更新,后台任务不再随新消息迁移。共享卡等全部任务结束后才停止更新;后续结果撑满卡片时,对应条目移到新卡。多模型委派的完整结果仍保存在任务记录中。
|
|
121
123
|
|
|
122
124
|
首轮完成后,返回内容包含原生会话 ID(文本中的 `Session:`;JSON 中的 `workers[].session_id`)和本轮结果(`workers[].output`)。后续只需传入这个 ID 和新的一句输入:
|
|
123
125
|
|
|
@@ -133,14 +135,14 @@ lodestar-agent run --session '<session-id>' --description '继续第二步' --pr
|
|
|
133
135
|
|
|
134
136
|
第二轮及后续轮次恢复同一个后端原生会话,每轮产生新的 `run_id`。已有 Lodestar 历史时,省略 `--identity` 会沿用最新记录的身份和 effort;也可显式选择原后端下的其他身份、模型来源及 `--effort`。切换身份且不指定 effort 时,使用新身份的默认档位。多模型首轮分别返回各 worker 的会话 ID,续跑时一次选择一个会话。也可使用 `lodestar-agent follow-up '<run-id>' --description '继续下一步' --prompt '下一步'`;原 run 包含多个 Agent 时需用 `--identity` 选择原 worker,若还需换模型,使用该 worker 的原生会话 ID 加新身份恢复。
|
|
135
137
|
|
|
136
|
-
`session_id` 是原生会话唯一且不变的 ID;`run_id` 只是一次调用记录,不是另一套会话 ID
|
|
138
|
+
`session_id` 是原生会话唯一且不变的 ID;`run_id` 只是一次调用记录,不是另一套会话 ID。对话 ID(`chat_id`)标识调用的绑定对象,与原生会话 ID 不同;同一对话 ID 可以拥有多个原生会话。原生会话归属项目和对话 ID,`run --session` 与 `follow-up` 只允许恢复同一项目、同一对话 ID 下的已登记会话,不要求与原调用使用相同的会话绑定或项目绑定。禁止跨项目、跨对话 ID;未知或归属不明的原生会话 ID 即使指定 `--identity` 也会报错。
|
|
137
139
|
|
|
138
140
|
```bash
|
|
139
|
-
# desc:
|
|
141
|
+
# desc: 在当前会话中恢复同项目同对话 ID 的原生会话
|
|
140
142
|
lodestar-agent run --session '<原生会话 ID>' --identity '<identity-id>' --workdir 'packages/app' --description '继续已有工作' --prompt '继续上一轮任务' --json
|
|
141
143
|
```
|
|
142
144
|
|
|
143
|
-
恢复时 `--workdir`
|
|
145
|
+
恢复时 `--workdir` 可选择本项目内的其他现有目录,省略则沿用历史执行目录;相对路径以当前项目目录解析。项目以规范工作目录识别,对话 ID 对应 `chat_id`;子目录不改变所属项目。新调用依照调用场景绑定当前会话或项目,旧记录不迁移。同项目同对话 ID 下切换绑定方式时,旧调用的取消不会连带停止新调用。原生会话 ID 和所属后端保持不变,模型、来源与 effort 可以在原后端支持且不使用 Claude 订阅来源的范围内调整。
|
|
144
146
|
|
|
145
147
|
同一个后端原生会话在开卡和执行期间不能重叠恢复。多 Agent 任务中某个 worker 已结束并退出后,可以单独续跑它,无需等待其他 worker。`run`、`follow-up`、`status` 支持 `--json`;返回的 `work_dir` 是实际执行目录,`resumed_from_run_id` 仅记录可用的恢复来源,不建立跨绑定方式的取消关系。使用 `--stdin` 可输入多行任务,`--no-wait` 立即返回启动状态。HTTP API 的 `session_id`、`identity_ids` / `identity_id` 和 `work_dir` 遵循同一规则。
|
|
146
148
|
|
|
@@ -150,7 +152,7 @@ Agent 在执行任务中调用其他 Agent 或模型时,必须绑定当前会
|
|
|
150
152
|
|
|
151
153
|
### 从终端或脚本调用项目 Agent
|
|
152
154
|
|
|
153
|
-
独立服务、定时任务或其他软件通过 `--project <项目名>` 直接调用本机 daemon
|
|
155
|
+
独立服务、定时任务或其他软件通过 `--project <项目名>` 直接调用本机 daemon,无需在对应对话 ID 下启动主 Agent;Agent 执行用户任务时不能使用此入口。项目必须已有明确的对话 ID 绑定和现有目录;worktree 使用完整的 `项目名[分支名]`,BTW/FK 临时会话名不作为项目入口。
|
|
154
156
|
|
|
155
157
|
```bash
|
|
156
158
|
# desc: 查询项目可用身份并发起独立任务
|
|
@@ -158,20 +160,20 @@ lodestar-agent --project '<项目名>' identities --json
|
|
|
158
160
|
lodestar-agent --project '<项目名>' run --identity '<identity-id>' --description '检查项目' --prompt '检查代码并报告结果' --request-id '<本次业务调用唯一编号>' --no-wait
|
|
159
161
|
```
|
|
160
162
|
|
|
161
|
-
|
|
163
|
+
每次项目调用在绑定对话 ID 下新建独立的“项目任务”卡,后续进度和结果更新原卡。它不复用会话委派卡,不读取或修改主会话的模型、账号和上下文;停止、重启、切换主会话不影响项目任务。可点击任务卡的“停止本次任务”,或使用同一 `--project` 下的 `cancel <run-id>`。两类任务仍共享实际工作目录。
|
|
162
164
|
|
|
163
165
|
项目入口面向传统软件,执行约定是不给调用方提问、不等待回答。调用方给出目标后,Agent 自行查明上下文、作出任务范围内的实现决策、持续执行并验证,直至完整完成目标;不能以计划、部分工作、索取输入或要求调用方安排更多 Agent 作为完成结果。真实阻断或底层故障仍须如实报告,不能伪造完成。`answer` 用于会话归属的各层委派,不支持 `--project`。
|
|
164
166
|
|
|
165
167
|
外部调用中的 Codex 同步、异步提问工具均会禁用,GPT-6 代码模式仍可执行任务。工具约束按本次调用生成;主 Agent 委派保留提问能力。
|
|
166
168
|
|
|
167
|
-
`status`、`follow-up` 和 `run --session` 均支持 `--project`;最后一个仍表示继续任务自身的原生 Agent
|
|
169
|
+
`status`、`follow-up` 和 `run --session` 均支持 `--project`;最后一个仍表示继续任务自身的原生 Agent 会话。只能恢复当前项目、当前对话 ID 下已登记的原生会话;本轮按项目绑定创建,旧记录不迁移。新建和续跑都按本轮绑定决定是否允许提问,项目调用不会继承旧会话的交互规则。没有 `--no-wait` 时客户端等到任务终态;等待期间 Ctrl+C 会取消任务,普通 HTTP 断开不会取消已接受的任务。
|
|
168
170
|
|
|
169
171
|
```bash
|
|
170
172
|
# desc: 查询项目任务状态和执行结果
|
|
171
173
|
lodestar-agent --project '<项目名>' status '<run-id>' --json
|
|
172
174
|
```
|
|
173
175
|
|
|
174
|
-
|
|
176
|
+
对话 ID 下的普通消息仍交给主会话。会话委派和项目任务均只向调用方返回结果与本地文件路径,由主 Agent 或调用程序处理交付。`--project` 不注入主会话的文件交付规则,也不上传附件、设置权限或执行输出中的交付标记;新建任务和续跑旧会话都遵循此规则。
|
|
175
177
|
|
|
176
178
|
项目任务的 `run` / `follow-up` 可用 `--request-id` 防止超时重试重复执行:同一归属、同一编号及相同输入返回原任务,输入不同则拒绝,daemon 重启后仍有效。重启不会自动重跑未完成任务;遗留非终态任务标为失败,已有原生会话可显式续跑。
|
|
177
179
|
|