lodestar AGENTS.md

Lodestar 项目指引

Lodestar 是一个 Bun/TypeScript daemon：它从飞书 WebSocket 接收消息，把每个群映射为一个 Session，再通过统一 AgentProcess 驱动 Codex app-server 或 Claude Agent SDK，并把 turn、工具与状态渲染到 Feishu Card Kit schema 2.0 卡片。

本仓库的维护入口和 AI 协作说明统一以 Codex/AGENTS.md 为准；这只是维护方式迁移，不是产品后端迁移。Codex、Claude、GLM、DeepSeek 与 Claude native 路径都是受支持产品能力，未经用户明确提出产品变更，不得因清理维护文件、缺少本机凭据或个人偏好而删除、弱化或伪装任一后端。

范围地图

• cli.ts 只处理首次配置与 PID guard，daemon.ts 负责 WS、session registry、Card action 和本机通知；业务逻辑放在 src/。
• src/ 是 session、双 agent 进程、token sources、飞书 API、Card Kit 队列、任务清单和 worktree 的核心实现。修改前读取 src/AGENTS.md。
• src/cards/ 只维护卡片模板和渲染辅助。修改前同时读取 src/AGENTS.md 与 src/cards/AGENTS.md。
• scripts/ 会复用生产配置并触达真实群或 daemon；运行或修改前读取 scripts/AGENTS.md。
• docs/ 保存后端设计 memo；修改双后端架构前按 docs/AGENTS.md 选择性阅读，但最终事实仍以源码和测试为准。
• 从仓库根目录启动的 agent 不会自动获得更深目录的说明；编辑子树前主动读取该路径适用的嵌套 AGENTS.md。

工作规则

• 开发运行时是 Bun，源码入口用 bun daemon.ts 或 bun run start；发布产物由 bun run build 生成可在 Node.js 18+ 运行的入口。
• config.ts 在 import 时同步加载配置且缺失即报错；首次安装的延迟导入只能留在 cli.ts。不要吞掉配置、凭据、Codex 登录、Claude SDK native binary 或飞书 API 错误。
• 配置默认在 ~/.config/lodestar/config.toml，日志和 session/chat/resume/model/tasklist 等状态默认在 ~/.local/share/lodestar/。新增持久状态统一经 src/paths.ts 放到 XDG/平台数据目录，不要写回仓库。
• 凭据只存在于用户配置、登录状态或环境变量。禁止把 token、App Secret、聊天成员数据、debug context、~/.codex/~/.claude 内容或本机绝对配置复制到跟踪文件。
• API、模型目录、额度、上传或 agent 启动失败必须显式记录并向调用方显示失败；不得伪造数据、静默成功或偷偷换 provider/source。只允许针对已知瞬态条件的有限重试，最终失败仍需暴露。
• 保留用户已有改动；不要覆盖无关脏文件。依赖变更同步更新 bun.lock，不要手工改锁文件内容。
• 所有展示到工具卡片的 shell 命令第一行使用 # desc: <中文摘要>；src/cards/shell-command.ts 依赖这个约定提取可读标题。
• Card action kind、共享 element_id、群命令、resume/model map 和 token source id 都是持久 wire contract。重命名时同步修改生产分发、迁移和测试，不能只改显示层。

跨模块不变式

• 一个飞书群只对应一个 Session 和一个当前主 agent 进程。Codex 走 codex app-server --listen stdio:// JSON-RPC；Claude/GLM/DeepSeek/native 走 @anthropic-ai/claude-agent-sdk 的 streaming-input query()。AgentService 可按实时身份并行启动完整 delegated Agent：它们与主进程共用全能力 coding-agent 启动面，行为范围只由主 Agent 的原始 prompt 约束，并可通过独立 capability 继续委派。不要恢复 tmux、旧 JSONL 队列或旁路进程控制。
• daemon-owned Skill 必须由 managed-skills.ts 同源同步：Codex/Claude standalone 目录用于各自 user source，另生成 Claude 本地插件供排除 user settings/env 的 GLM/DeepSeek SDK 主会话显式加载。不得为了加载 Skill 把 user source 重新混入注入凭据的 TokenSource。
• Token Source 是账号、凭据、模型目录、spawn env 和额度的真相源。内置 source 包括 Codex subscription、GLM Coding Plan、DeepSeek 与 Claude native；GLM/DeepSeek 可由 config 或本机 Claude settings 探测，存在显式 Claude-side source 时 native 让位。新增 source 按 factory 注册模式扩展，禁止在 model/session 层再建固定枚举。
• Agent 身份目录必须动态遍历 Token Source 的全部模型，使用模型目录声明的真实默认 effort，并允许主 Agent 按 run 显式选择受支持 effort；source disabled 或目录刷新失败都显示 MISS，禁止换模型/降 effort。
• 同一原始 prompt 选择多个 Agent 身份时，主 Agent 用一个 run 携带全部 identity id，由 run 内 fan-out 并发。不同 run 可并行并组成父子 DAG；每个 worker 使用独立、run-scoped、可撤销 capability，只能访问自己的 run 子树。全局并发和递归深度是透明进程治理，不能改变模型权限、注入审计语义或偷偷降级。
• Delegated Agent 必须使用完整工具面：Codex 固定 danger-full-access 且不禁 apps/plugins/multi_agent/MCP/hooks；Claude 固定 claude_code preset、完整内置工具、项目 MCP 与 daemon-managed Skills。不得恢复 reviewer system prompt、read-only/safe mode、工具白名单或自动 deny。AskUserQuestion/request_user_input 进入 needs_input，由主 Agent 通过 answer API 回填；follow-up 必须复用 provider 原生 session。
• Agent run 每次生命周期状态变化都原子落盘；大 prompt/输出拆成独立私有正文 artifact，状态快照不得重复内嵌。委派产生的 Codex/Claude 原生 session id 另行登记并从主会话 rs/fk 历史排除。父 run 取消、Session stop/kill/restart 与 daemon staged shutdown 都必须在首次 await 前封住新建入口、吊销 capability，并递归回收后代进程。
• model 是账号→模型→effort 三级动态面板。Codex 模型来自 app-server model/list，GLM/DeepSeek 来自兼容端点并允许受验证的补录，native 使用 SDK aliases；失败显示 MISS，不造假选项。
• 同 provider、同 token source 的模型设置走 setModelSettings：Claude 从后续 turn 使用，Codex 持久目标需重启进程生效。跨 provider 或跨 source 会改变进程/env，只能在空闲时停止旧进程并按各 provider 独立 resume id 重新启动；活跃或排队状态按现有规则拒绝切换。
• Claude 路径保留原生 session resume/fork、fk/bk/rs、AskUserQuestion、project profile、MCP/skills、主动 /compact 和 SDK task_* 后台任务；Codex 路径保留 app-server 权限、request_user_input、plan/goal、compaction、usage 与 collab 子 agent 映射。共享卡片事件不能抹平两端确有差异。
• cardkit.ts 独占生产卡的 sequence、队列、流式 TTL 重开、元素计数和写失败状态。session 与模板不得旁路它直调 Card Kit HTTP；专用探针只能在 scripts/cardkit-probe.ts 中显式操作测试卡。
• Assistant 正文按完整 block 插入静态元素，不走 /content 逐字输出；footer 用 element replace。公式渲染、换卡和 turn 收尾服从同一 per-card 队列，具体事务见 src/AGENTS.md。
• worktree.ts 独占 work/* 分支和同级 <project>[name] worktree 操作。飞书任务清单只保留基础绑定/删除，不运行自动计划、执行、审核或合并 worker。
• [[send: /abs/path]] 由 outbound marker 流程解析并作为独立飞书文件消息发送；正文保留原标记作为可见回执，卡片模板本身不得读取本机文件。