feishu-codex-console 1.0.0-beta.8 → 1.0.0-beta.9

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes are recorded here. Versions follow Semantic Versioning while the public API stabilizes.
 
+## 1.0.0-beta.9 - 2026-07-18
+
+### Added
+
+- A task-oriented Chinese quickstart covering Feishu app setup, first installation, first messages, multi-project group conventions, remote-readiness checks, upgrades, and common recovery paths.
+
+### Changed
+
+- Prerelease installation and upgrade examples now use the npm `next` channel explicitly, and the source-install directory name matches the public repository.
+
 ## 1.0.0-beta.8 - 2026-07-18
 
 ### Fixed

package/README.en.md

@@ -9,7 +9,7 @@ The bridge is local-first and outbound-only. It maps a local Codex thread to a d
 Requirements: macOS or Linux, Node.js 22+, a local `codex login`, and a Feishu custom app with Bot, long-connection message events, and CardKit enabled.
 
 ```bash
-npx feishu-codex-console init
+npx feishu-codex-console@next init
 ```
 
 The guided installer validates the environment and Feishu capabilities, discovers your member/chat identity from one test message, writes a private configuration, installs a LaunchAgent or systemd user service, waits for both event consumers, and sends the first product card.
@@ -59,7 +59,7 @@ feishu-codex-bridge doctor --fix
 feishu-codex-bridge support-bundle
 feishu-codex-bridge backup
 feishu-codex-bridge version
-npx feishu-codex-console@latest upgrade --config /absolute/path/default.env
+npx feishu-codex-console@next upgrade --config /absolute/path/default.env
 ```
 
 An upgrade is a read-only preview until `--yes` is added. It blocks live-task replacement, creates a verified database backup, checks the new package, validates service health, and attempts automatic data/service rollback on failure.

package/README.md

@@ -1,6 +1,6 @@
 # Feishu Codex Console
 
-[English](README.en.md) · [安装](docs/INSTALLATION.md) · [配置](docs/CONFIGURATION.md) · [兼容与升级](docs/COMPATIBILITY.md) · [Roadmap](ROADMAP.md)
+[10 分钟快速上手](docs/QUICKSTART.md) · [English](README.en.md) · [安装](docs/INSTALLATION.md) · [配置](docs/CONFIGURATION.md) · [兼容与升级](docs/COMPATIBILITY.md) · [Roadmap](ROADMAP.md)
 
 把本地 Codex thread 映射成一个可持续交流、可以协作和接管的飞书工作会话。人在外面时，可以在飞书里继续提问、分析、写文件、修改代码、回答 Codex 追问并处理权限确认；本机不需要开放公网端口。
 
@@ -55,21 +55,21 @@ flowchart LR
 
 要求：macOS 或 Linux、Node.js 22 或更高版本、本机已完成 `codex login`，并已配置可接收消息事件的飞书自建应用。项目会安装并优先使用固定版本的 `lark-cli`。
 
-推荐使用交互式向导：
+当前仍是公开测试版，推荐通过 `next` 通道使用交互式向导：
 
 ```bash
-npx feishu-codex-console init
+npx feishu-codex-console@next init
 ```
 
 向导会检查 Node、Codex 登录和飞书 Bot 身份，等待一条测试消息自动识别 `open_id`/`chat_id`，提供个人安全、团队安全和高级模式三档权限预设，并把配置以 `0600` 权限写入用户配置目录。自检通过后，它会安装 macOS LaunchAgent 或 Linux systemd user service。
 
-完整步骤见 [安装指南](docs/INSTALLATION.md)，全部配置见 [配置参考](docs/CONFIGURATION.md)，常见问题见 [故障排查](docs/TROUBLESHOOTING.md)，五分钟完整闭环见 [产品演示](docs/DEMO.md)。产品方向和逐项需求见 [产品需求地图](docs/PRODUCT_REQUIREMENTS_MAP.md)，公开路线见 [Roadmap](ROADMAP.md)，版本与依赖承诺见 [兼容矩阵](docs/COMPATIBILITY.md)。
+第一次部署直接看 [10 分钟快速上手](docs/QUICKSTART.md)。完整步骤见 [安装指南](docs/INSTALLATION.md)，全部配置见 [配置参考](docs/CONFIGURATION.md)，常见问题见 [故障排查](docs/TROUBLESHOOTING.md)，五分钟完整闭环见 [产品演示](docs/DEMO.md)。产品方向和逐项需求见 [产品需求地图](docs/PRODUCT_REQUIREMENTS_MAP.md)，公开路线见 [Roadmap](ROADMAP.md)，版本与依赖承诺见 [兼容矩阵](docs/COMPATIBILITY.md)。
 
 从源码安装：
 
 ```bash
 git clone https://github.com/LeoChaseYoung/feishu-codex-console.git
-cd feishu-codex-bridge
+cd feishu-codex-console
 npm install
 npx lark-cli config init --new
 npx lark-cli whoami --as bot
@@ -320,8 +320,8 @@ feishu-codex-bridge backups --config /absolute/path/to/default.env
 从新 npm 包升级时，先运行不带 `--yes` 的只读预览。执行模式会拒绝替换仍有活动任务的服务，依次完成校验备份、新包自检、服务安装和双消费者健康验证；失败时尝试恢复数据与仍可用的旧服务包。
 
 ```bash
-npx feishu-codex-console@latest upgrade --config /absolute/path/to/default.env
-npx feishu-codex-console@latest upgrade --config /absolute/path/to/default.env --yes
+npx feishu-codex-console@next upgrade --config /absolute/path/to/default.env
+npx feishu-codex-console@next upgrade --config /absolute/path/to/default.env --yes
 ```
 
 回滚会替换当前 SQLite，必须先停止服务；命令会先保存回滚前状态，并校验清单、SHA-256 和数据库完整性：

package/docs/COMPATIBILITY.md

@@ -30,13 +30,13 @@ The stable `1.x` promise covers documented CLI commands, configuration keys, run
 Preview an upgrade first:
 
 ```bash
-npx feishu-codex-console@latest upgrade --config /absolute/path/default.env
+npx feishu-codex-console@next upgrade --config /absolute/path/default.env
 ```
 
 The preview is read-only. When no task is actively running, repeat with `--yes`. The command creates a verified SQLite backup, runs the new package’s doctor, stops the old service, installs the new service, and waits for both Feishu consumers to become healthy. Failure triggers a data rollback and, when the previous package location is still available, reinstalls and verifies the previous service.
 
 ```bash
-npx feishu-codex-console@latest upgrade \
+npx feishu-codex-console@next upgrade \
   --config /absolute/path/default.env \
   --yes
 ```

package/docs/INSTALLATION.md

@@ -19,7 +19,7 @@
 ## 推荐安装
 
 ```bash
-npx feishu-codex-console init
+npx feishu-codex-console@next init
 ```
 
 向导会依次检查运行环境、选择权限预设、选择项目、自动识别飞书成员和会话、写入私有配置并安装后台服务。服务管理器返回后，向导还会等待消息与卡片事件连接同时就绪，并核对后台进程实际读取的配置文件；任一项不一致都不会显示安装完成。
@@ -89,7 +89,7 @@ feishu-codex-bridge discover
 ## 非交互式安装
 
 ```bash
-npx feishu-codex-console init \
+npx feishu-codex-console@next init \
   --yes \
   --preset personal \
   --open-id ou_replace_me \
@@ -99,7 +99,7 @@ npx feishu-codex-console init \
 团队示例：
 
 ```bash
-npx feishu-codex-console init \
+npx feishu-codex-console@next init \
   --yes \
   --preset team \
   --open-id ou_operator \
@@ -150,8 +150,8 @@ feishu-codex-bridge backups --config /absolute/path/team.env
 更新 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
+npx feishu-codex-console@next upgrade --config /absolute/path/default.env
+npx feishu-codex-console@next upgrade --config /absolute/path/default.env --yes
 ```
 
 升级会拒绝活动任务，创建一致性备份，用目标包自检，替换服务并验证产品版本、PID、配置路径、心跳和两个事件消费者。失败时会尝试恢复数据，并在旧包位置仍存在时恢复和验证旧服务。完整承诺见 [兼容与版本策略](COMPATIBILITY.md)。
@@ -177,7 +177,7 @@ feishu-codex-bridge status --config /absolute/path/team.env
 如果以前通过克隆仓库、编辑仓库根目录 `.env` 并安装 LaunchAgent 的方式运行，可以迁移到用户级配置：
 
 ```bash
-npx feishu-codex-console migrate --from /absolute/path/to/old/feishu-codex-bridge
+npx feishu-codex-console@next migrate --from /absolute/path/to/old/feishu-codex-bridge
 ```
 
 迁移器会复制并规范化旧配置，把相对路径转换为以旧源码目录为基准的绝对路径，继续使用原来的 SQLite/JSON 数据，然后运行 doctor。确认切换后，新服务必须通过健康和配置一致性检查才算迁移完成；旧 `.env` 和数据不会自动删除。非交互迁移使用 `--yes`，目标配置已存在时需显式添加 `--force`，迁移器会先备份再合并。

package/docs/OPEN_SOURCE_PRODUCT_PLAN.md

@@ -25,7 +25,7 @@
 
 ### v0.1：别人能装上
 
-- `npx feishu-codex-console init` 交互式初始化。
+- `npx feishu-codex-console@next init` 交互式初始化。
 - 个人安全、团队安全、高级模式三档权限预设。
 - Node、Codex 登录、飞书 Bot 身份、项目目录和服务状态检查。
 - 配置写入用户配置目录，不把凭证或成员标识写进 Git 仓库。

package/docs/PRODUCT_REQUIREMENTS_MAP.md

@@ -83,7 +83,7 @@ Feishu Codex Console 是一个开源、本地优先的 Codex 远程工作会话
 
 ### 当前已有
 
-- `npx feishu-codex-console init` 初始化向导。
+- `npx feishu-codex-console@next init` 初始化向导。
 - 个人安全、团队安全和高级模式预设。
 - 自动识别 `open_id`、`chat_id` 和会话类型。
 - 私有配置和数据目录。

package/docs/QUICKSTART.md

@@ -0,0 +1,202 @@
+# 10 分钟快速上手
+
+这份文档只讲一件事：让一台已经能运行 Codex 的 Mac 或 Linux 电脑，在飞书里收到第一条任务。
+
+> 当前仍是公开测试版，请使用 `@next` 安装。管理员只需在运行 Codex 的电脑上部署一次，其他团队成员不需要安装 Node.js、Codex 或本项目。
+
+## 先理解它怎么工作
+
+```text
+飞书消息 → 飞书长连接 → 你电脑上的 Bridge → 本机 Codex → 原飞书会话
+```
+
+- 不需要公网 IP、域名、Webhook 或开放 SSH/HTTP 端口。
+- 电脑必须开机、联网，Codex 和 Bridge 服务必须在线。
+- 任务实际读取和修改的是这台电脑上明确授权的项目目录。
+
+## 1. 准备本机
+
+需要：
+
+- macOS，或支持 systemd user service 的 Linux。
+- Node.js 22 或更高版本。
+- 本机 Codex 已登录。
+- 至少一个准备授权给机器人的本地项目目录。
+
+先检查：
+
+```bash
+node --version
+codex --version
+codex login
+```
+
+## 2. 准备飞书自建应用
+
+在飞书开放平台创建一个企业自建应用，然后完成下面四项：
+
+1. 启用“机器人”能力。
+2. 添加权限 `im:message:readonly` 和 `cardkit:card:write`。
+3. 在“事件与回调”中选择长连接，并订阅：
+   - `im.message.receive_v1`
+   - `card.action.trigger`
+4. 创建并发布一个应用版本，让权限和事件订阅真正生效。
+
+如果要在群聊使用，还需要把机器人加入目标群。权限或事件后来有变化时，要再次发布应用版本。
+
+## 3. 在本机绑定飞书应用
+
+运行：
+
+```bash
+npx lark-cli config init --new
+npx lark-cli whoami --as bot
+```
+
+按提示填写飞书应用的 App ID 和 App Secret。Secret 由 `lark-cli` 保存在用户配置目录，不要写入项目 `.env`，也不要提交到 Git。
+
+已有 `lark-cli` 应用配置时，第一条命令去掉 `--new`。
+
+## 4. 运行安装向导
+
+```bash
+npx feishu-codex-console@next init
+```
+
+第一次使用建议：
+
+- 选择“个人安全”预设。
+- 选择一个真实的 Git 项目作为默认项目。
+- 保持 `workspace-write`，不要一开始就开启完全访问。
+- 向导提示监听消息时，在飞书私聊机器人发送“连接测试”。
+
+向导会自动识别你的 `open_id` 和当前会话、写入私有配置，并安装 macOS LaunchAgent 或 Linux systemd user service。
+
+安装完成后检查：
+
+```bash
+npx feishu-codex-console@next status
+npx feishu-codex-console@next doctor
+```
+
+默认配置文件：
+
+```text
+~/.config/feishu-codex-bridge/default.env
+```
+
+## 5. 在飞书发送第一组消息
+
+按顺序发送：
+
+```text
+新手引导
+控制台
+项目
+读取项目
+这个项目是做什么的？
+```
+
+前三条用于确认设备、Codex 和项目都正确；`读取项目` 只做本地快照，不调用模型。最后一条才会进入真实 Codex 会话。
+
+之后可以直接自然表达，不需要先选任务类型：
+
+```text
+分析登录模块为什么容易出错，不修改文件
+```
+
+```text
+在 docs 目录写一份部署说明
+```
+
+```text
+修复失败测试，运行验证并告诉我改了哪些文件
+```
+
+问题和只读分析使用简洁文字回复；写文件和改代码才显示任务进度、文件变化和测试结果卡。
+
+## 6. 群聊、多项目和会话规则
+
+推荐团队约定：**一个项目对应一个群聊。**
+
+- 群里新发一条顶层消息：开始一件新事情，创建独立 Codex 会话。
+- 在机器人回复串中继续说：延续同一件事情和同一个 Codex thread。
+- 另一个项目：进入它自己的群，或先发送“项目”切换并确认路径。
+- 同时处理多个项目：分别在对应项目群或不同回复串中发起，任务卡始终显示项目名。
+
+私聊适合个人连续使用；团队协作优先使用项目群和回复串，避免上下文混在一起。
+
+## 7. 最常用的飞书命令
+
+| 发送内容 | 作用 |
+|---|---|
+| `新手引导` | 重新打开使用引导 |
+| `控制台` / `状态` | 查看设备、Codex、项目、队列与远程就绪 |
+| `项目` | 选择或切换项目 |
+| `读取项目` | 生成 0 AI token 的项目快照 |
+| `模型` / `设置` | 切换模型、推理强度和后续任务权限 |
+| `额度` | 查看 Codex 账户额度与重置时间 |
+| `会话` | 恢复历史 Codex 会话或新建会话 |
+| `任务` | 查看运行中、排队和最近任务 |
+| `追加 <要求>` | 给正在运行的任务补充要求 |
+| `排队 <任务>` | 明确创建下一项独立任务 |
+| `停止` | 停止当前任务并清理本会话队列 |
+| `帮助` | 查看完整命令帮助 |
+
+## 8. 在外使用前检查
+
+在飞书发送“控制台”，确认：
+
+- 飞书连接在线。
+- Codex 引擎在线。
+- 当前项目正确。
+- 权限符合预期。
+- Mac 已接通电源，并按需开启“远程就绪”。
+
+远程就绪只能防止空闲睡眠，不能让关机、断网或不满足合盖运行条件的 Mac 保持在线。
+
+## 9. 常见问题
+
+### 给机器人发消息没有回复
+
+依次检查：
+
+1. 飞书应用版本是否已经发布。
+2. 机器人是否已加入当前群聊。
+3. 权限和两个事件是否已启用。
+4. 本机运行：
+
+```bash
+npx feishu-codex-console@next status
+npx feishu-codex-console@next doctor
+```
+
+### 项目列表没有目标项目
+
+重新运行安装向导添加扫描根目录，或在私有配置中设置 `CODEX_PROJECT_ROOTS`，然后重启服务。
+
+### 群聊被拒绝
+
+完全访问模式下，群聊必须加入 `ALLOWED_FEISHU_CHAT_IDS`。运行：
+
+```bash
+npx feishu-codex-console@next discover
+```
+
+在目标群发送一条消息，取得 `chat_id` 后重新运行向导或更新私有配置。
+
+### 需要升级
+
+先预览，不会修改服务：
+
+```bash
+npx feishu-codex-console@next upgrade --config ~/.config/feishu-codex-bridge/default.env
+```
+
+确认后执行：
+
+```bash
+npx feishu-codex-console@next upgrade --config ~/.config/feishu-codex-bridge/default.env --yes
+```
+
+更多问题见 [安装指南](INSTALLATION.md)、[配置参考](CONFIGURATION.md)和[故障排查](TROUBLESHOOTING.md)。

package/docs/TROUBLESHOOTING.md

@@ -114,7 +114,7 @@ feishu-codex-bridge install --config /absolute/path/to/default.env
 旧源码安装使用：
 
 ```bash
-npx feishu-codex-console migrate --from /absolute/path/to/old/source
+npx feishu-codex-console@next migrate --from /absolute/path/to/old/source
 ```
 
 迁移不会删除旧 `.env` 或数据。新服务通过验证后再手工归档旧目录。

package/docs/requirements/D1_INSTALLATION_AND_FIRST_CONNECTION.md

@@ -86,7 +86,7 @@ MVP 绑定用户已有的飞书自建应用，不替用户自动创建飞书应
 ## 6. 端到端安装流程
 
 ```text
-运行 npx feishu-codex-console init
+运行 npx feishu-codex-console@next init
   ↓
 欢迎页与已有安装检测
   ↓

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feishu-codex-console",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0-beta.9",
   "description": "A reliable Feishu control plane for local Codex projects, sessions, approvals, and live Card 2.0 tasks.",
   "private": false,
   "license": "MIT",