work-ally

work-ally 是一个把当前项目连接到命名 assistant 办公桌与官方 Codex runtime 的薄编排层。

面向最终客户的文档

PRODUCT.md 是可以直接交给最终客户的正式文档。它先介绍 work-ally 是什么，再沿最短路径完成安装、连接飞书和第一次真实对话。

第一次接触时，只需要给出这一个入口。创建飞书机器人和获取应用凭证的具体步骤，单独维护在 docs/feishu-bot-setup.md。PRODUCT.md 会在需要时引导进入。

维护者需要随产品行为持续更新这两份文档，但不应把工程实现、迁移历史或内部排障过程写进去。

内部维护入口

• 产品同事：docs/product-onboarding.md
• 研发同事：docs/developer-workflow.md
• 值班排障：docs/ops-runbook.md、docs/troubleshooting.md

Desk V2（当前基线）

assistant 办公桌根目录：~/.ally/desk/<assistant_id>/

~/.ally/desk/<assistant_id>/
├── AGENTS.md
├── ally.toml
├── Desk/
│   ├── PROFILE.md
│   ├── MEMORY.md
│   ├── conversations/
│   ├── journal/
│   └── skills/
│       └── work-ally-operator/
└── .system/
    ├── codex-home/
    │   ├── AGENTS.md
    │   └── config.toml
    ├── runtime/
    ├── logs/
    ├── runs/
    ├── cache/
    │   └── feishu-attachments/<conversation_id>/<message_id>/
    ├── routines/
    └── archive/

用户路径

ally setup <assistant_id> --workspace /path/to/project
ally config show --assistant <assistant_id>
ally start --assistant <assistant_id>
ally status --assistant <assistant_id>

进度播报默认开启。飞书会把同一 turn 的 commentary 收敛到一张 CardKit 2.0 卡片，每当 assistant 完成一段工作说明，就用当前完整内容更新同一张卡片。runtime 明确标记的 commentary 之间留一个空行；无法可靠识别段落边界的过程条目使用单换行紧凑展示，避免把同一段尚未完成的表达拆成多个松散段落。正文以自适应深浅色主题的中性灰普通文本直接展示。工作过程卡不依赖飞书的打字机流式窗口，长时间任务也能在后续条目完成时继续刷新。过程内容不依赖 Markdown 格式。卡片标题只显示“处理中 / 待确认 / 已完成 / 未完成”四种状态。最终回复独立使用飞书官方 Markdown 流式卡片，标题、列表、引用、代码和表格等展示由官方 SDK 统一处理。上下文压缩是 Codex 内部运行事件，只记录在底层，不向飞书发送通知。需要让 assistant 默认只回最终结果时，可以首次启动或重启时设置：

ally --assistant <assistant_id> start --progress off
ally --assistant <assistant_id> restart --progress off

该值保存在 assistant 的 runtime state 中，supervisor 自愈和 /update 重启后继续沿用。在飞书中发送 /progress on|off|default 可以只覆盖当前私聊或群聊；/progress 查看当前有效值。关闭后仍会收到 reaction、错误、补充问题、恢复提示和最终回复。

人格与记忆设置

先拿到办公桌路径：

ally --assistant <assistant_id> desk

然后编辑这两个文件：

• 人格/风格/原则：~/.ally/desk/<assistant_id>/Desk/PROFILE.md
• 长期记忆：~/.ally/desk/<assistant_id>/Desk/MEMORY.md

修改后建议执行：

ally --assistant <assistant_id> restart

每次 ally start / ally restart 都会自动对该 assistant desk 的内置 Skill 做 reconcile：缺失即安装，版本落后即更新，文件漂移即修复。当前内置的核心 Skill 是 Desk/skills/work-ally-operator/，用于把“重启一下”“我想回飞书了”“我想回 codex-cli 了”这类自然语言请求翻译成正式的 ally 操作。

assistant_id 规则：^[a-z][a-z0-9_-]{1,31}$

配置与模型作用域

• 用户配置真源：ally.toml（固定 V1 schema）
• CLI 配置命令：ally config show|set
• provider、model 与 reasoning effort 都只属于单个 assistant，不存在机器级 global 或 work-session 级 current
• provider 支持 openai 与 openrouter；OpenRouter 当前默认模型是 deepseek/deepseek-v4-pro，但可直接填写其他 OpenRouter 模型 ID
• 飞书会话命令：/model show、/model set <model> [effort]、/model reset
• 进度投递：assistant 默认值使用 start/restart --progress on|off；conversation 覆盖使用 /progress on|off|default

安全边界

• 官方 Codex 登录继续使用 ally --assistant <assistant_id> auth codex，原 Device Code 路径不变
• OpenRouter 使用 ally --assistant <assistant_id> auth openrouter；Key 写入该 assistant 专属 Codex config.toml，文件权限固定为 0600，不会出现在 ally.toml、状态输出或诊断包中
• 两套凭证可以并存；切换 provider 只改变当前 assistant，不影响本机其他 assistant
• 请求仍由官方 Codex runtime 发出；work-ally 不实现模型 HTTP 转发、动态模型目录或第二套 agent loop

维护入口

• 命令分发：internal/dispatch.sh
• 通用路径/状态：internal/lib/common.sh
• 模型 provider 与 OpenRouter 凭证配置：internal/lib/model-provider.sh
• assistant 生命周期：internal/modules/runtime/*.sh
• assistant 管理：internal/modules/assistant/manage.sh
• bridge 入口：bridge/src/server.ts
• 入站主流程：bridge/src/receiver.ts
• 飞书 Channel SDK 适配：bridge/src/channels/feishu/adapter.ts
• 飞书标准消息映射：bridge/src/channels/feishu/channel-message.ts
• 飞书 reply 父消息查询与官方标准化：bridge/src/channels/feishu/message-snapshot.ts
• 飞书最终回复流：bridge/src/channels/feishu/final-stream.ts
• 飞书工作卡渲染：bridge/src/channels/feishu/progress-card.ts
• 飞书工作过程卡更新：bridge/src/channels/feishu/progress-card-updater.ts
• 飞书系统通知卡：bridge/src/channels/feishu/system-notice-card.ts
• 飞书附件解析与下载：bridge/src/channels/feishu/attachments.ts
• 飞书附件关联：bridge/src/channels/feishu/attachment-association.ts
• 飞书附件缓存：bridge/src/channels/feishu/attachment-cache.ts
• 飞书远程更新控制：bridge/src/system-update.ts
• 进度投递策略：bridge/src/progress-delivery.ts
• 更新后重启交接：internal/modules/runtime/restart-after-update.sh

飞书普通文件和图片统一下载到 assistant desk 的 .system/cache/feishu-attachments/，再由 receiver-runtime-policy.ts 把绝对路径交给 Codex。缓存是可清理、可重建的运行资产，不进入 conversation archive 或长期记忆。

飞书 /update 由 bridge 直接消费，不进入 Codex。机器级 npm 更新锁位于 ~/.ally/locks/product-update.lock/；重启完成通知暂存在当前 desk 的 .system/runtime/update-restart.json，成功投递后删除。

常用命令

ally --assistant <assistant_id> setup --workspace /path/to/project
ally --assistant <assistant_id> auth codex
# 或：ally --assistant <assistant_id> auth openrouter
ally --assistant <assistant_id> config set model gpt-5.5
ally --assistant <assistant_id> config set reasoning_effort medium
ally --assistant <assistant_id> config set memory.nightly_digest_enabled true
ally --assistant <assistant_id> start
ally --assistant <assistant_id> restart --progress off
ally --assistant <assistant_id> status
ally --assistant <assistant_id> stop
ally --assistant <assistant_id> logs bridge
ally --assistant <assistant_id> diagnostics export
ally assistant list
ally global list