feishu-codex-console 1.0.0-beta.6

package/docs/CONFIGURATION.md

@@ -0,0 +1,88 @@
+# Configuration reference
+
+The recommended path is `feishu-codex-console init`. It writes a private `0600` env file and preserves unknown advanced keys when rerun. Start every managed file with `BRIDGE_CONFIG_VERSION=1`; a newer unknown contract fails closed instead of being guessed.
+
+## Identity and team access
+
+| Key | Default | Purpose |
+|---|---|---|
+| `ALLOWED_FEISHU_OPEN_IDS` | required | Comma-separated operators allowed to start Codex work |
+| `FEISHU_ADMIN_OPEN_IDS` | operators | Administrators; configure explicitly for a team |
+| `FEISHU_VIEWER_OPEN_IDS` | empty | Read-only dashboard and status members |
+| `FEISHU_MEMBER_LABELS_JSON` | empty | Product-facing labels; missing labels become anonymous member codes |
+| `ALLOWED_FEISHU_CHAT_IDS` | private chats only | Optional chat allowlist; full-access groups require it |
+| `FEISHU_GROUP_SESSION_SCOPE` | `member` | `member` isolates each group member; `chat` deliberately shares context |
+| `FEISHU_PROJECT_ACL_JSON` | empty | Project selector to member-ID arrays; admins bypass ACLs |
+| `FEISHU_BOT_MENTION_NAMES` | empty | Names stripped from leading group mentions |
+
+## Projects and Codex
+
+| Key | Default | Purpose |
+|---|---|---|
+| `CODEX_WORKDIR` | required by installer | Default authorized project |
+| `CODEX_PROJECT_ROOTS` | default project | Additional roots recursively scanned for Git repositories |
+| `CODEX_PROJECT_SCAN_DEPTH` | `8` | Maximum discovery depth |
+| `MAX_CODEX_PROJECTS` | `200` | Discovery result cap |
+| `CODEX_SYNC_SAVED_PROJECTS` | `true` in generated config | Include projects saved by the local Codex app |
+| `CODEX_PROJECT_STATE_FILE` | Codex home default | Optional saved-project state override |
+| `CODEX_CLI_PATH` | bundled binary | Optional Codex executable override |
+| `CODEX_MODEL` | native default | Deployment-level model default |
+| `CODEX_REASONING_EFFORT` | native default | Deployment-level reasoning default |
+| `CODEX_MULTI_AGENT_ENABLED` | `false` | Enable Codex subagent tools; keep off for predictable token use |
+| `CODEX_TIMEOUT_MS` | `1200000` | Turn timeout |
+| `CODEX_SKIP_GIT_REPO_CHECK` | `false` | Permit an authorized non-Git project |
+
+## Permission ceiling
+
+| Key | Default | Purpose |
+|---|---|---|
+| `CODEX_SANDBOX_MODE` | `workspace-write` | Service/admin maximum |
+| `CODEX_OPERATOR_SANDBOX_MODE` | safe service maximum | Ordinary operator maximum |
+| `CODEX_NETWORK_ACCESS` | `false` | Network access passed to Codex |
+| `CODEX_WEB_SEARCH_MODE` | `disabled` | `disabled`, `cached`, or `live` |
+| `CODEX_ALLOWED_ENV_VARS` | empty | Explicit project variables copied into Codex’s minimized environment |
+| `EXTERNAL_CONFIRMATION_TTL_MINUTES` | `10` | Commit/push/deploy/publish/PR confirmation lifetime |
+
+`danger-full-access` is only a ceiling. A member still needs a temporary lease in the settings card, and external actions still require confirmation. A repository policy can reduce these limits further.
+
+`CODEX_MULTI_AGENT_ENABLED=false` is the cost-safe default. Ultra reasoning can proactively delegate work, and every subagent has its own model/tool loop. When enabled, the bridge still asks Codex to delegate only after an explicit user request.
+
+## Capacity, files, and retention
+
+| Key | Default | Purpose |
+|---|---|---|
+| `MAX_CONCURRENT_TASKS` | `2` | Global task concurrency |
+| `MAX_QUEUED_PER_CONVERSATION` | `5` | Per-member conversation queue cap |
+| `MAX_ATTACHMENT_BYTES` | `20971520` | Attachment download cap |
+| `MAX_TEXT_ATTACHMENT_BYTES` | `131072` | Text decoded into a prompt |
+| `ATTACHMENT_RETENTION_HOURS` | `72` | Local attachment retention |
+| `MAX_REPLY_CHARS` | `12000` | Reliable text fallback cap |
+| `MAX_SEEN_EVENTS` | `2000` | Event deduplication retention bound |
+| `MAX_LOG_BYTES` | `10485760` | Per-log rotation threshold |
+| `LOG_MESSAGE_CONTENT` | `false` | Content logging; keep disabled outside local debugging |
+
+## Instance and local data
+
+| Key | Default | Purpose |
+|---|---|---|
+| `BRIDGE_INSTANCE_ID` | `default` | Stable service and data instance name |
+| `BRIDGE_DATA_DIR` | package `var` or installer user-data path | SQLite, health, logs, attachments, and backups |
+| `BRIDGE_DATABASE_FILE` | `<data>/state.sqlite` | Advanced database override |
+| `BRIDGE_STATE_FILE` | `<data>/state.json` | One-time legacy JSON migration source |
+| `FEISHU_COMPLETION_NOTIFICATIONS` | `false` | Optional compact completion notice after the original task card updates; failures always get a fallback |
+| `FEISHU_AUTO_ONBOARDING` | `true` | One-time member onboarding card |
+
+Do not place App Secret in this file. `lark-cli` owns the Bot identity in its user configuration. Do not commit the managed env file, runtime data, support bundles, or real member/chat IDs.
+
+## Repository-controlled files
+
+- `.feishu-codex-policy.json`: schema v1 permission and external-action policy; can only tighten host limits.
+- `.feishu-codex-runbooks.json`: schema v1 reviewed team prompts; cannot request full access or pre-authorize external mutations.
+
+Create a safe runbook starter in any project with:
+
+```bash
+feishu-codex-bridge init-runbooks --project /absolute/path/to/project
+```
+
+The command never overwrites an existing catalog.

package/docs/DEMO.md

@@ -0,0 +1,45 @@
+# Product demo
+
+This is the repeatable five-minute demo for a release candidate. Use a disposable repository without customer data and a private Feishu chat.
+
+## Setup
+
+1. Install with the personal-safe preset and keep `workspace-write`, network off, and Web search disabled.
+2. Open a small Git repository with one intentionally failing test.
+3. In Feishu, send `新手引导`; verify the welcome card shows one clear primary action for the current device/project/role state.
+
+## Demo story
+
+| Moment | Action | Product proof |
+|---|---|---|
+| 0:00 | Send `控制台` or `额度` | Device, consumers, Codex, independent native quota windows, reset times, project, queue, permission, and sampled time are clear |
+| 0:30 | Send `项目` and select the demo repo | Path/branch/dirty state prevent wrong-project execution |
+| 1:00 | Ask Codex to diagnose the failing test | A single live task card shows context, progress, model, reasoning, and permission |
+| 2:00 | Send a follow-up requirement | The same turn records steering instead of silently creating a second task |
+| 2:30 | Answer a non-secret question or one-shot approval | Native interaction resumes the same Codex task and expires safely |
+| 3:15 | Open `查看验证`, inspect a Diff, then `返回结果` | The original task card switches surfaces without adding messages; tests, attribution, and paged diff remain visible |
+| 4:00 | Send `任务`, then `团队` | Task history and privacy-preserving team aggregate use consistent product cards |
+| 4:30 | Send `运行手册` | A reviewed repository task can run without raising the member’s permission |
+
+## Failure proof
+
+Repeat one short task, then stop the bridge process while it is running. After the service restarts:
+
+- the task is marked interrupted rather than replayed;
+- already-written file changes remain reviewable;
+- the card or reliable fallback gives a recovery action;
+- a never-started queued task can resume safely.
+
+## Release evidence
+
+Capture the same desktop width and Feishu theme for each release. Redact names, project paths, member IDs, tokens, prompts containing private code, and attachments. Keep these seven frames:
+
+1. installation success;
+2. device console;
+3. project selector;
+4. live task;
+5. question or approval;
+6. result review;
+7. recovery state.
+
+The demo passes only when controls are usable, text is not clipped, every ordinary response uses the shared Card 2.0 shell, and no card claims success before the underlying state is verified.

package/docs/GOOD_FIRST_ISSUES.md

@@ -0,0 +1,23 @@
+# Good first issues
+
+Starter issues should teach one product boundary without requiring a contributor to run a real Feishu tenant or expose local credentials. Maintainers can copy one of the following into a GitHub issue and add the `good first issue` label.
+
+## Ready-to-scope candidates
+
+| Candidate | Primary files | Done when |
+|---|---|---|
+| Add another redaction fixture | `src/redaction.ts`, `test/redaction.test.ts` | A realistic secret shape is hidden without corrupting ordinary text |
+| Improve one doctor remediation | `src/doctor.ts`, `test/diagnostics.test.ts` | A failed check prints one safe, executable next step |
+| Add one Card 2.0 contract fixture | one card module, `test/card-contract.test.ts` | Element IDs and supported component shape pass the contract suite |
+| Clarify one Linux troubleshooting path | `docs/TROUBLESHOOTING.md` | A clean systemd user install can follow the steps without source knowledge |
+| Add a safe sample runbook | `.feishu-codex-runbooks.example.json`, runbook tests | The template parses, cannot elevate permissions, and contains no external action |
+
+## Maintainer checklist
+
+- Explain the user-visible problem, not just the desired code change.
+- Keep the expected change within one subsystem and avoid authentication or approval redesigns.
+- List exact acceptance checks and a likely test file.
+- State which credentials or live services are not required.
+- Reserve cross-user authorization, migration, arbitrary command policy, and production release changes for experienced contributors.
+
+Use the repository’s “Good first issue proposal” form for new candidates. The label means the issue is scoped and maintainer-approved; it does not mean unreviewed code can bypass security or migration checks.

package/docs/INSTALLATION.md

@@ -0,0 +1,207 @@
+# 安装 Feishu Codex Bridge
+
+这份文档面向第一次部署的个人和团队维护者。目标是在不开放公网端口的前提下，让本地 Codex 在飞书中可用。
+
+## 前置条件
+
+- macOS 或带 systemd user service 的 Linux。
+- Node.js 22 或更高版本。
+- 本机安装 Codex，并已运行 `codex login`。
+- 一个飞书自建应用，已启用机器人、长连接事件和 CardKit 权限。
+
+飞书应用至少需要：
+
+- `im:message:readonly`
+- `cardkit:card:write`
+- `im.message.receive_v1`
+- `card.action.trigger`
+
+## 推荐安装
+
+```bash
+npx feishu-codex-console init
+```
+
+向导会依次检查运行环境、选择权限预设、选择项目、自动识别飞书成员和会话、写入私有配置并安装后台服务。服务管理器返回后，向导还会等待消息与卡片事件连接同时就绪，并核对后台进程实际读取的配置文件；任一项不一致都不会显示安装完成。
+
+默认配置位置：
+
+```text
+~/.config/feishu-codex-bridge/default.env
+```
+
+默认数据位置：
+
+```text
+~/.local/share/feishu-codex-bridge/default/
+```
+
+配置文件使用 `0600` 权限，数据目录使用 `0700` 权限。
+
+重新运行 `init` 时会识别已有安装、显示上次安全进度、备份旧配置并保留未知高级配置。只有显式使用 `--force-reset` 才会完整重建配置。
+
+## 配置飞书应用身份
+
+如果向导提示 Bot 身份不可用，运行：
+
+```bash
+npx lark-cli config init --new
+npx lark-cli whoami --as bot
+```
+
+已有应用时去掉 `--new`。App Secret 由 `lark-cli` 保存在用户配置目录，不应写进桥接服务的 `.env`。
+
+## 自动识别 open_id
+
+初始化向导会提示你给机器人发送一条消息，并从只读事件流中自动提取 `sender_id`、`chat_id` 和会话类型。也可以单独运行：
+
+```bash
+feishu-codex-bridge discover
+```
+
+监听最多接收一个事件，并在两分钟后自动退出。自动识别失败时，向导会回退到手工输入。团队部署仍需分别记录管理员、操作者和只读成员；不要提交包含真实 ID 的输出。
+
+## 权限预设
+
+### 个人安全（推荐）
+
+- 管理员和操作者都是当前用户。
+- 最大权限为工作区写入。
+- 网络和 Web 搜索默认关闭。
+
+### 团队安全
+
+- 显式区分管理员、操作者和只读成员。
+- 群聊按成员隔离项目、会话、设置和队列。
+- 最大权限为工作区写入。
+
+### 高级模式
+
+- 服务上限为完全访问。
+- 普通操作者仍限制为工作区写入。
+- 群聊未加入白名单时会被拒绝。
+- 初始化时必须再次确认风险。
+
+非交互式安装高级模式必须显式传入 `--allow-full-access`。
+
+默认情况下，私聊身份发现会在服务健康后自动回复一张安装测试卡；群聊需要再次确认。自动化环境可以使用 `--no-test-card` 跳过，或使用 `--send-test-card` 明确允许群聊测试卡。
+
+## 非交互式安装
+
+```bash
+npx feishu-codex-console init \
+  --yes \
+  --preset personal \
+  --open-id ou_replace_me \
+  --workdir /absolute/path/to/project
+```
+
+团队示例：
+
+```bash
+npx feishu-codex-console init \
+  --yes \
+  --preset team \
+  --open-id ou_operator \
+  --admin-id ou_admin \
+  --viewer-id ou_viewer \
+  --workdir /srv/repos/frontend \
+  --project-roots /srv/repos
+```
+
+团队安装后建议在私有配置中补充卡片友好名称：
+
+```dotenv
+FEISHU_MEMBER_LABELS_JSON={"ou_admin":"平台管理员","ou_operator":"前端同学","ou_viewer":"产品同学"}
+```
+
+名称只用于飞书卡片；SQLite 与审计仍保留真实身份 ID，数据目录和备份必须保持私有。要启用团队运行手册，在每个项目根目录生成并评审示例（不会覆盖已有文件）：
+
+```bash
+feishu-codex-bridge init-runbooks --project /absolute/path/to/project
+```
+
+完整交接、团队面板和模板安全规则见 [D9 团队协作](requirements/D9_TEAM_COLLABORATION.md)。
+
+## 诊断和服务管理
+
+```bash
+feishu-codex-bridge doctor
+feishu-codex-bridge doctor --fix
+feishu-codex-bridge doctor --diagnostics /private/path/diagnostic.json
+feishu-codex-bridge support-bundle
+feishu-codex-bridge version
+feishu-codex-bridge status
+feishu-codex-bridge backup
+feishu-codex-bridge uninstall
+```
+
+`doctor --fix` 只修复运行目录/文件权限、失效健康标记和超限日志，不会修改成员、项目 ACL、sandbox 或用户代码。诊断包包含有界健康、数据库和日志摘要并统一脱敏，分享前仍应人工检查。
+
+升级前可以手动创建和列出 SQLite 一致性备份：
+
+```bash
+feishu-codex-bridge backup --config /absolute/path/team.env
+feishu-codex-bridge backups --config /absolute/path/team.env
+```
+
+数据库结构迁移也会自动备份并在失败时回滚。手动恢复需要先停止服务，运行 `rollback --backup <id> --yes`，再重新 `install`。
+
+更新 npm 包时先预览；没有 `--yes` 不会修改服务或数据：
+
+```bash
+npx feishu-codex-console@latest upgrade --config /absolute/path/default.env
+npx feishu-codex-console@latest upgrade --config /absolute/path/default.env --yes
+```
+
+升级会拒绝活动任务，创建一致性备份，用目标包自检，替换服务并验证产品版本、PID、配置路径、心跳和两个事件消费者。失败时会尝试恢复数据，并在旧包位置仍存在时恢复和验证旧服务。完整承诺见 [兼容与版本策略](COMPATIBILITY.md)。
+
+单独运行 `install` 也会执行同一套服务健康和配置一致性检查。慢速机器可以调整等待时间：
+
+```bash
+feishu-codex-bridge install --health-timeout 60s
+```
+
+运行时健康信息保存在实例数据目录的 `bridge-health.json`，仅包含实例、PID、配置路径、事件消费者状态和时间戳，不包含飞书凭据或消息正文。
+
+使用非默认实例或自定义配置文件时：
+
+```bash
+feishu-codex-bridge status --config /absolute/path/team.env
+```
+
+自检失败时不会安装后台服务。修复飞书 Bot、Codex 登录或项目目录后，再运行 `doctor` 和 `install`。
+
+## 从旧源码安装迁移
+
+如果以前通过克隆仓库、编辑仓库根目录 `.env` 并安装 LaunchAgent 的方式运行，可以迁移到用户级配置：
+
+```bash
+npx feishu-codex-console migrate --from /absolute/path/to/old/feishu-codex-bridge
+```
+
+迁移器会复制并规范化旧配置，把相对路径转换为以旧源码目录为基准的绝对路径，继续使用原来的 SQLite/JSON 数据，然后运行 doctor。确认切换后，新服务必须通过健康和配置一致性检查才算迁移完成；旧 `.env` 和数据不会自动删除。非交互迁移使用 `--yes`，目标配置已存在时需显式添加 `--force`，迁移器会先备份再合并。
+
+## 安装完成
+
+在飞书中发送：
+
+```text
+新手引导
+```
+
+欢迎卡会根据当前状态直接给出下一步：设备离线时查看连接、没有项目时选择授权项目、准备完成时直接开始使用。卡片不会要求成员理解安装参数；团队或多项目并行时，只需记住一个项目建一个群，新事情发新消息，继续同一件事就在回复里说。之后可以直接提问、分析、写文件或执行一个安全的首次代码任务。
+
+## 维护者发布
+
+每次推送 `v<package version>` 标签时，Release workflow 会重新运行类型检查、测试、生产构建和 tarball 干净安装测试，然后使用 npm provenance 发布并创建 GitHub Release。
+
+仓库需要配置：
+
+- GitHub Environment：`npm`，建议要求维护者审批。
+- Environment secret：`NPM_TOKEN`。
+- npm 账号开启双因素认证，并使用适合 CI 的 granular access token。
+
+标签必须与 `package.json` 完全一致，例如 `1.0.0-beta.4` 对应 `v1.0.0-beta.4`。
+
+Ubuntu 与 macOS 的自动门禁、两端实机验证和飞书团队权限验收见 [发布检查清单](RELEASE_CHECKLIST.md)。安装异常见 [故障排查](TROUBLESHOOTING.md)，所有环境变量见 [配置参考](CONFIGURATION.md)。

package/docs/OPEN_SOURCE_PRODUCT_PLAN.md

@@ -0,0 +1,113 @@
+# Feishu Codex Bridge 开源产品升级计划
+
+## 产品承诺
+
+> 10 分钟把本地 Codex 安全接入飞书，无需开放公网端口。
+
+首个公开版本只聚焦“飞书控制本地 Codex”。多 IM、多 Agent、托管云端和跨设备中继不进入当前主线，避免安装体验尚未稳定时扩大维护面。
+
+## 目标用户
+
+1. **个人开发者**：在外通过飞书查看并操作自己电脑上的 Codex。
+2. **小团队维护者**：部署一台共享开发机，为成员分配项目和权限。
+3. **开源贡献者**：能够在不阅读全部架构代码的情况下完成安装、诊断和提交修复。
+
+## 成功标准
+
+- 从安装命令到收到第一张飞书控制卡不超过 10 分钟。
+- 默认安装不启用完全访问、不启用网络、不允许未知用户执行任务。
+- 配置文件权限为 `0600`，运行数据目录权限为 `0700`。
+- 安装失败时给出下一条可执行命令，而不是只输出堆栈。
+- 新成员在飞书完成第一个成功任务后，才视为激活完成。
+- 服务升级不丢失 SQLite 会话、队列、审计和成员设置。
+
+## 三阶段路线
+
+### v0.1：别人能装上
+
+- `npx feishu-codex-console init` 交互式初始化。
+- 个人安全、团队安全、高级模式三档权限预设。
+- Node、Codex 登录、飞书 Bot 身份、项目目录和服务状态检查。
+- 配置写入用户配置目录，不把凭证或成员标识写进 Git 仓库。
+- macOS LaunchAgent 与 Linux systemd 使用同一份显式配置文件。
+- npm `bin`、发布文件白名单、`prepack` 构建和公开包元数据。
+- README 首屏安装路径和独立安装文档。
+
+### v0.2：第一次就成功
+
+- 唯一、可持续更新的“飞书主页卡”，旧卡只跳转到最新主页。
+- 新手引导只要求项目和权限预设；模型与推理强度使用默认值。
+- 项目卡或设置卡保存后自动继续引导，不要求用户滚回旧卡。
+- 提供“只读扫描项目”“运行测试”“查看未提交改动”三个安全任务。
+- 第一个任务成功后完成引导；失败时保留进度并提供修复入口。
+- 激活数据只保存在本地 SQLite，默认不上传遥测。
+
+### v0.3：长期敢使用
+
+- 完全访问按本次任务、当前会话或一小时临时提升并自动回退。
+- `doctor --fix`、脱敏诊断包和一键复制支持信息。
+- 数据库迁移前备份、升级检查和回滚命令。
+- 服务启动、重连和持续离线通知。
+- 在功能检测后实验性接入 Codex app-server remote-control 配对能力。
+
+### v1.0：别人能维护
+
+- 配置、持久状态、SQLite、仓库策略和运行手册均使用显式版本契约。
+- `version`、`support-bundle` 和安全 `upgrade` 形成发布、诊断、备份、验证与回退闭环。
+- npm tarball 覆盖中断恢复、运行手册初始化和只读升级预览，而不依赖源码目录。
+- 公开兼容矩阵、配置参考、演示脚本、Roadmap 和 Good First Issue 路径。
+- 内部适配边界先稳定，不在 1.0 暴露安全关键插件 API，也不默认收集遥测。
+
+## v0.1 安装流程
+
+```text
+运行 init
+  → 检查 Node / Codex / 飞书 Bot
+  → 选择权限预设
+  → 选择默认项目和扫描根目录
+  → 填写操作者与管理员 open_id
+  → 写入私有配置文件
+  → 运行 doctor
+  → 安装后台服务
+  → 提示在飞书发送“新手引导”
+```
+
+### 权限预设
+
+| 预设 | 服务上限 | 操作者上限 | 网络 | 群聊策略 | 适用场景 |
+|---|---|---|---|---|---|
+| 个人安全 | 工作区写入 | 工作区写入 | 关闭 | 按成员隔离 | 个人电脑，推荐默认值 |
+| 团队安全 | 工作区写入 | 工作区写入 | 关闭 | 按成员隔离 | 共享开发机与小团队 |
+| 高级模式 | 完全访问 | 工作区写入 | 关闭 | 必须配置群白名单后才能在群里用 | 管理员确实需要本机命令能力 |
+
+高级模式仍不自动放行提交、推送、发布、部署和 PR/MR 操作。普通操作者默认保持工作区写入；完全访问只授予管理员。
+
+## 配置与目录约定
+
+```text
+~/.config/feishu-codex-bridge/<instance>.env
+~/.local/share/feishu-codex-bridge/<instance>/
+```
+
+macOS 也沿用相同路径，便于文档、迁移和诊断保持一致。可以通过 `--config` 和 `BRIDGE_DATA_DIR` 覆盖。
+
+配置分为两层：
+
+- 初始化向导只生成身份、项目、权限、实例和数据目录等必要项。
+- 队列、附件、超时、日志和模型覆盖继续使用现有环境变量，归入高级配置。
+
+## 发布检查清单
+
+- [ ] 包不再标记为 private，并提供 `feishu-codex-bridge` CLI。
+- [ ] `npm pack --dry-run` 只包含运行需要的文件。
+- [ ] Linux 与 macOS 安装说明均经过一次干净环境验证。
+- [ ] README 包含 30 秒演示、三条命令快速开始和安全边界。
+- [ ] GitHub 仓库公开，默认分支包含 LICENSE、SECURITY、CONTRIBUTING 和 Issue 模板。
+- [ ] 创建带校验和与变更说明的首个预发布版本。
+
+## 暂不进入主线
+
+- Docker 默认部署：本产品需要访问本地 Codex 登录态、项目目录和桌面保存项目，容器会显著增加安装摩擦。
+- 托管中继：当前长连接不需要开放公网入口，先保持本地优先。
+- 多 IM 与插件市场：等飞书安装成功率和首任务成功率稳定后再评估。
+- 自研远程协议：优先对齐 Codex app-server，并对实验能力做功能检测。