feishu-codex-console 1.0.0-beta.6

package/.env.example

@@ -0,0 +1,101 @@
+# Configuration contract version. New releases migrate older versions explicitly
+# and refuse unknown future versions instead of guessing.
+BRIDGE_CONFIG_VERSION=1
+
+# Required: one or more authorized Feishu user open_ids, comma-separated.
+ALLOWED_FEISHU_OPEN_IDS=ou_replace_me
+
+# Team roles. ALLOWED_FEISHU_OPEN_IDS are operators. When the admin list is
+# empty, all operators are treated as admins for backward-compatible personal
+# installs. Viewers may inspect dashboards but cannot start or mutate tasks.
+FEISHU_ADMIN_OPEN_IDS=
+FEISHU_VIEWER_OPEN_IDS=
+
+# Optional product-facing member names. Cards never expose raw open_ids; when a
+# label is missing, the bridge shows a stable anonymous member code instead.
+FEISHU_MEMBER_LABELS_JSON={"ou_replace_me":"Alice"}
+
+# Group chats are isolated per member by default so teammates never share a
+# Codex thread, selected project, queue, or settings by accident. Use "chat"
+# only when the entire group intentionally collaborates in one shared context.
+FEISHU_GROUP_SESSION_SCOPE=member
+
+# Optional project ACL JSON. Keys may be an absolute path, project name,
+# display path, or "*"; values are Feishu open_id arrays. Admins always bypass
+# project ACLs. When empty, every authorized member sees every discovered project.
+FEISHU_PROJECT_ACL_JSON=
+
+# Optional: restrict use to selected chats. Empty allows authorized private
+# chats; in danger-full-access mode, group chats remain blocked until listed.
+ALLOWED_FEISHU_CHAT_IDS=
+
+# Default project when a chat has not selected one yet.
+CODEX_WORKDIR=/absolute/path/to/a/git/repository
+
+# Mirror local projects saved in the Codex app. The state-file override is
+# optional; by default it uses $CODEX_HOME/.codex-global-state.json.
+CODEX_SYNC_SAVED_PROJECTS=true
+CODEX_PROJECT_STATE_FILE=
+
+# Optional additional roots scanned recursively for Git repositories. Use
+# commas for multiple roots. Empty means only scan CODEX_WORKDIR in addition to
+# the exact projects saved in Codex.
+CODEX_PROJECT_ROOTS=
+CODEX_PROJECT_SCAN_DEPTH=8
+MAX_CODEX_PROJECTS=200
+
+# Modes: read-only, workspace-write, danger-full-access. Full access can run
+# arbitrary local commands; use a strict sender allowlist and keep the external
+# action confirmation gate enabled.
+CODEX_SANDBOX_MODE=workspace-write
+# Maximum default for non-admin operators. It cannot exceed CODEX_SANDBOX_MODE.
+# When the service maximum is danger-full-access, this defaults to workspace-write.
+CODEX_OPERATOR_SANDBOX_MODE=workspace-write
+CODEX_SKIP_GIT_REPO_CHECK=false
+CODEX_NETWORK_ACCESS=false
+CODEX_WEB_SEARCH_MODE=disabled
+# Disabled by default for predictable remote-task cost. Enable only when the
+# team explicitly wants Codex subagent workflows.
+CODEX_MULTI_AGENT_ENABLED=false
+
+# Optional Codex overrides. Empty values use the local Codex defaults.
+CODEX_CLI_PATH=
+CODEX_MODEL=
+CODEX_REASONING_EFFORT=
+CODEX_TIMEOUT_MS=1200000
+
+# Codex receives a minimized child-process environment, so bridge credentials
+# and common token/password variables are not inherited. Explicitly list only
+# project-specific variables that a confirmed workflow truly needs.
+CODEX_ALLOWED_ENV_VARS=
+
+# Different chats may run concurrently; one chat remains strictly serial.
+MAX_CONCURRENT_TASKS=2
+MAX_QUEUED_PER_CONVERSATION=5
+
+# Feishu attachment limits. Images are passed directly to Codex; common text
+# and source files are decoded up to MAX_TEXT_ATTACHMENT_BYTES.
+MAX_ATTACHMENT_BYTES=20971520
+MAX_TEXT_ATTACHMENT_BYTES=131072
+ATTACHMENT_RETENTION_HOURS=72
+
+# External-action confirmation cards expire and are persisted across restarts.
+EXTERNAL_CONFIRMATION_TTL_MINUTES=10
+
+# Used to remove the leading @mention from group-chat prompts.
+FEISHU_BOT_MENTION_NAMES=你的飞书机器人名称
+
+MAX_REPLY_CHARS=12000
+MAX_SEEN_EVENTS=2000
+# Distinguishes multiple installations for LaunchAgent/systemd service names.
+BRIDGE_INSTANCE_ID=default
+# Runtime data can live outside the Git checkout. Defaults to ./var.
+BRIDGE_DATA_DIR=
+# Optional explicit file overrides. The legacy JSON path is read once for migration only.
+BRIDGE_DATABASE_FILE=
+BRIDGE_STATE_FILE=
+FEISHU_COMPLETION_NOTIFICATIONS=false
+# Show the interactive guide once per new private chat or isolated group member.
+FEISHU_AUTO_ONBOARDING=true
+MAX_LOG_BYTES=10485760
+LOG_MESSAGE_CONTENT=false

package/.feishu-codex-policy.example.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "sandbox": {
+    "maximum": "workspace-write"
+  },
+  "operations": {
+    "allow": ["commit", "push", "pull_request"],
+    "deny": ["deploy"],
+    "requireApproval": ["commit", "push", "pull_request"]
+  }
+}

package/.feishu-codex-runbooks.example.json

@@ -0,0 +1,36 @@
+{
+  "version": 1,
+  "runbooks": [
+    {
+      "id": "verify",
+      "name": "测试并修复",
+      "description": "运行项目已有测试，定位失败原因并完成必要修复",
+      "prompt": "运行当前项目已有的测试与静态检查，修复发现的问题，并总结修改内容与验证结果。",
+      "sandboxMode": "workspace-write",
+      "reasoningEffort": "high"
+    },
+    {
+      "id": "inspect-module",
+      "name": "检查指定模块",
+      "description": "对指定模块做只读结构、风险和测试覆盖检查",
+      "prompt": "只读检查 {{module}} 模块，说明它的职责、主要依赖、潜在风险和测试覆盖缺口，不修改文件。",
+      "sandboxMode": "read-only",
+      "parameters": [
+        {
+          "name": "module",
+          "label": "模块",
+          "description": "仓库内的目录或模块名",
+          "required": true
+        }
+      ]
+    },
+    {
+      "id": "refresh-docs",
+      "name": "刷新项目文档",
+      "description": "根据当前代码更新项目内已有文档并检查链接",
+      "prompt": "检查当前实现与项目文档的一致性，更新过期说明并验证文档内的本地链接。完成后只汇报变更与验证结果。",
+      "sandboxMode": "workspace-write",
+      "reasoningEffort": "medium"
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog
+
+All notable changes are recorded here. Versions follow Semantic Versioning while the public API stabilizes.
+
+## 1.0.0-beta.6 - 2026-07-17
+
+### Fixed
+
+- Task-review baselines now serialize index-backed Git reads, disable optional index locks, and bypass the untracked cache so freshly created pre-existing files are captured consistently on Linux.
+
+## 1.0.0-beta.5 - 2026-07-17
+
+### Fixed
+
+- Task-review baselines now use streamed SHA-256 content fingerprints instead of filesystem timestamps, preventing unchanged pre-existing files from being attributed to a Codex task on Linux or after metadata-only timestamp changes.
+- Added cross-platform regression coverage for dirty-worktree attribution before publishing.
+
+## 1.0.0-beta.4 - 2026-07-17
+
+### Added
+
+- Native Codex account quota summaries in the device and model control centers, plus a dedicated detail card for independent limit buckets, remaining percentage, reset time, plan, and available reset count; `额度`, `/usage`, and `/quota` open the live view.
+- Local task-intent routing for answers, read-only analysis, content/file writing, and code changes, with mode-specific cards, retry copy, validation states, and sandbox clamping.
+- Zero-token local project overview for `读取项目` / `/overview`, with bounded Git, README, package, language, and directory inspection.
+- Accurate per-task token accounting across every model call, split into new input, cached input, output, and model-call count.
+- Cost-safe subagent defaults: multi-agent tools are disabled unless a deployment explicitly sets `CODEX_MULTI_AGENT_ENABLED=true`.
+- Public `feishu-codex-console` package with `feishu-codex-console` and backward-compatible `feishu-codex-bridge` CLIs.
+- Read-only Feishu message discovery that automatically captures the installer operator and conversation IDs.
+- Resumable non-sensitive installation state; existing config, service, runtime-data, and health detection; atomic configuration updates; private backups; and preservation of unknown advanced settings.
+- Feishu Bot/message/card-event capability probes with concrete remediation, plus an end-to-end installation success card.
+- Private service health heartbeats that verify the live PID, both Feishu event consumers, instance identity, and the exact loaded configuration before installation can complete.
+- A non-destructive `migrate --from <source>` flow for old repository-local `.env` installs that preserves advanced settings and reuses legacy runtime data.
+- Personal-safe, team-safe, and power-user setup presets with explicit full-access confirmation.
+- Private per-user configuration and data directories that work with macOS LaunchAgent and Linux systemd.
+- Installation guide and open-source product roadmap.
+- Clean tarball installation smoke test plus protected npm provenance and GitHub Release workflow.
+- Package-level recovery coverage that interrupts initialization before configuration write and verifies a second run resumes from the saved safe checkpoint.
+- Ubuntu/macOS CI and release preflight matrices, plus maintainer release and operator troubleshooting guides.
+- Truthful device availability states with status sampling time, per-member last-success time, hidden controls when callbacks are unavailable, and an explicit Codex reconnect action.
+- Persisted device-console card references that refresh in place after restart, plus rate-limited recovery notices after a meaningful unexpected outage.
+- Per-member project favorites and recent usage, consistent ranked numeric selection, searchable path-aware project choices, and current Git branch/dirty/ahead/behind status.
+- Impact-aware project switching with native card confirmation and explicit text confirmation whenever tasks, queues, or saved Codex context would be interrupted.
+- Automatic names for newly created native Codex threads based on the first task.
+- Live queue-position updates, task-card model/reasoning/thread context, and visible steering counts for follow-up messages.
+- A per-task stop control in the task center, accurate member/admin task scopes, and read-only cards without false mutation controls.
+- Actionable timeout, policy, permission, connection, and queue failure guidance, plus explicit file-impact copy for stopped work.
+- Safe restart semantics that recover untouched queued work but mark previously running work interrupted instead of replaying potentially destructive commands.
+- Capability-aware model controls with a semantic native-default option, per-model reasoning choices, task-time fallback for removed capabilities, and a read-only compatibility mode when the Codex catalog is unavailable.
+- One-shot audited runtime approvals and questions with explicit scope/expiry copy, stale-card recovery guidance, cancellation, and ownership enforcement.
+- End-to-end secret-question protection that removes remote answer controls, blocks text/card forwarding, and redacts message-content logging.
+- Run-start Git baselines with dirty-worktree attribution, file fingerprints, additions/deletions, post-task staleness detection, and safe fallback for legacy or non-Git work.
+- A read-only CardKit review center with paginated files and per-file diffs, task-card/task-center entry points, and explicit mixed-worktree guidance.
+- Structured test evidence from actual commands and exit codes; the latest rerun wins, missing tests stay visible, and a completed turn with failing tests is no longer styled as success.
+- Sensitive review-path blocking plus token, password, bearer credential, and private-key redaction for Diff and test excerpts.
+- Time-bounded full-access leases for the next task, 30 minutes, or the current Codex thread, bound to the member, conversation, project, and session with automatic safe fallback.
+- Repository-local `.feishu-codex-policy.json` controls that can lower the sandbox ceiling, allowlist external actions, or deny them, with validation at confirmation, enqueue, and execution time.
+- Shared credential redaction across runtime logs, doctor output, durable text replies, audit summaries, task/approval/confirmation cards, test excerpts, and review diffs.
+- A unified Card 2.0 response shell for controls, approvals, runtime questions, long-running work, and exceptional recovery states, with reliable text fallback.
+- Feishu API timeout, `Retry-After`, transient-error retry, backoff, and outbound API health reporting.
+- `doctor --fix` for safe local runtime repairs and private redacted JSON diagnostic bundles.
+- Verified SQLite runtime backups, backup listing, service stop/restart, and guarded rollback commands.
+- Automatic pre-migration SQLite snapshots, explicit schema versions, integrity checks, and rollback when schema or state conversion fails.
+- Conservative startup reconciliation across persisted task status, CardKit phase, start time, and Codex thread evidence.
+- Terminal-result fallback when a task card cannot be updated, even when proactive completion notifications are disabled.
+- Explicit task initiator/current-controller state with friendly member labels, group handoff, initiator reclaim, administrator takeover, ACL revalidation, restart recovery, and audited control changes.
+- A privacy-preserving team dashboard for member status, project load, task outcomes and token usage without prompts, results, paths or raw open IDs.
+- Repository-local `.feishu-codex-runbooks.json` templates with parameters, defaults, model/reasoning hints, permission lowering, safe one-click execution, and failure-closed external-action validation.
+- Explicit config/version compatibility metadata, a safe package upgrade preview/execution path, verified service rollback, and a private support-bundle command.
+- An installed-package `init-runbooks` command that creates a reviewed starter without overwriting team-owned catalogs.
+- English onboarding, configuration/compatibility/demo references, a public Roadmap, scoped Good First Issue guidance, and release-contract verification.
+
+### Changed
+
+- First-run onboarding is now one adaptive welcome card instead of a four-step wizard. It exposes one primary action for offline, missing-project, viewer, or ready states; realistic prompt examples and a short optional team convention replace configuration-heavy setup screens.
+- Conversational replies now promote concise lead conclusions into native Feishu rich-text titles, keep loading states visually quiet, and avoid leaking leading Markdown syntax into the chat-list preview.
+- Questions and read-only analysis now use one editable Feishu Markdown reply instead of a full success task card; the final answer hides task, model, permission, thread, and token metadata.
+- Top-level group prompts now start isolated reply-thread sessions. Later replies use Feishu `root_id`/`thread_id` context to resume the same Codex thread, while new topics inherit project and preferences without inheriting old Codex context or temporary permission leases.
+- Routine acknowledgements now use native Markdown. Card 2.0 is reserved for controls, approvals, questions, file/code execution, and exceptional states.
+- Questions and analysis no longer create Git baselines, consume temporary full-access leases, show missing-test warnings, or expose empty review actions; content and code tasks retain file-aware verification.
+- Completed tasks now keep one canonical card: a compact result summary opens the full answer or validation in place, irrelevant review actions stay hidden, and successful card updates no longer produce duplicate result messages by default.
+- Local absolute-path Markdown links are rendered as safe file labels in Feishu while external links remain clickable.
+- Reasoning-effort labels now match the Codex interface and hide internal enum values from visible controls.
+- Package metadata now includes a publishable binary, runtime file allowlist, and prepack build.
+- A conversation can explicitly return to the native Codex default even when the deployment pins a global model.
+- `CODEX_SANDBOX_MODE=danger-full-access` is now a service/role ceiling; persistent conversation settings are clamped to workspace write and require an explicit temporary lease for each elevated scope.
+- Task control is now distinct from task ownership; existing task records automatically assign control to their original initiator.
+- Ordinary acknowledgements and validation feedback now stay on the lightweight native message surface; consequential controls and exceptional recovery states use the semantic Card 2.0 shell.
+
+### Fixed
+
+- Native conversational replies now edit rich-text messages through the Feishu `PUT` message API instead of the card-only `PATCH` API. Progressive updates respect Feishu's 20-edit limit and reserve capacity for the terminal answer.
+- Team task cards now use CardKit-compliant element IDs in every collaboration state; contract coverage includes the dynamic team panel.
+- If a full task card is unavailable, its lightweight fallback card now updates in place from queued to running to terminal state instead of posting separate accepted and completed messages.
+
+## 1.0.0-beta.2 - 2026-07-16
+
+### Added
+
+- Native three-step Feishu Card 2.0 onboarding for connection, workspace/model setup, and the first task.
+- Automatic first-run onboarding with per-member SQLite progress, completion, dismissal, and manual restart.
+- Direct onboarding shortcuts to the device console, project workspace, model settings, sessions, and task center.
+- A viewer-specific read-only onboarding path and `FEISHU_AUTO_ONBOARDING` deployment control.
+
+### Fixed
+
+- macOS service reinstalls no longer force-start a second bridge process while the new LaunchAgent is registering its Feishu event consumers.
+
+## 1.0.0-beta.1 - 2026-07-16
+
+### Added
+
+- Codex-native model catalog, model selection, reasoning-effort selection, and per-conversation sandbox profiles.
+- Historical session browser, thread resume, context compaction, and task center.
+- Team roles: administrator, operator, and viewer.
+- Per-member group isolation, task/card/thread ownership, project ACLs, and a bounded SQLite audit log.
+- Automatic steering for follow-up messages and explicit `/queue` for independent work.
+- Proactive completion notifications backed by the durable text outbox.
+- Configurable instance/data paths plus macOS LaunchAgent and Linux systemd user services.
+- Bundled `@larksuite/cli`, MIT license, contribution guide, conduct policy, architecture docs, and GitHub templates.
+
+### Changed
+
+- Persisted state schema upgraded from version 5 to 6 with automatic migration.
+- Non-admin operators default to `workspace-write` when the service maximum is `danger-full-access`.
+- Group chats default to one Codex context per member.
+
+## 0.8.0 - 2026-07-15
+
+- Persistent Codex app-server, native approvals and questions, SQLite recovery, CardKit 2.0 task/device cards, and macOS Remote Ready.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Code of Conduct
+
+We want this project to be a practical, welcoming place for people building secure developer tools.
+
+Be respectful, assume good intent, discuss technical tradeoffs with evidence, and make space for contributors with different backgrounds and experience levels. Harassment, threats, discriminatory language, deliberate exposure of private information, and sustained personal attacks are not acceptable.
+
+Project maintainers may edit or remove contributions and restrict participation when behavior puts people or the project at risk. Report conduct concerns privately to the maintainers through GitHub rather than escalating them in a public thread.

package/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+Thanks for helping make Feishu Codex Bridge safer and easier to self-host.
+
+## Before opening a change
+
+- Search existing issues and pull requests.
+- For security vulnerabilities, follow `SECURITY.md` instead of opening a public issue.
+- Keep the bridge self-hosted and outbound-only by default. Features that require a public inbound endpoint need an explicit threat model.
+- Do not commit Feishu credentials, Codex login data, `.env`, SQLite files, logs, attachments, real open IDs, or absolute personal paths.
+
+## Local development
+
+```bash
+npm ci
+cp .env.example .env
+npm run check
+npm test
+npm run build
+npm run test:package
+```
+
+`npm run doctor` and `npm run smoke:codex` use local credentials, so they are optional for contributors who only change pure code or cards.
+
+## Code map
+
+| Area | Main files | Required evidence |
+|---|---|---|
+| Feishu routing and task lifecycle | `src/index.ts`, `src/task-queue.ts` | ownership, deduplication, queue, and restart tests |
+| Card 2.0 presentation | `src/*-card.ts`, `src/response-card.ts` | focused card test plus `test/card-contract.test.ts` |
+| Identity and permissions | `src/team-policy.ts`, `src/project-policy.ts`, `src/policy.ts` | allow and deny cases; no real member IDs |
+| Persistence and recovery | `src/state-store.ts`, `src/state-backup.ts` | old-state migration, interruption, integrity, and rollback tests |
+| Codex integration | `src/app-server-client.ts`, `src/model-capabilities.ts` | normalized fixtures; do not require experimental methods for core flows |
+| Installer and service | `scripts/cli.mjs`, `scripts/*d.mjs` | pure helper tests and `npm run test:package` |
+
+Start with [good first issues](docs/GOOD_FIRST_ISSUES.md) if you do not have a live Feishu test tenant. Product decisions and subsystem acceptance criteria live in [the requirements map](docs/PRODUCT_REQUIREMENTS_MAP.md).
+
+## Pull requests
+
+- Keep each pull request focused and explain the user-visible behavior.
+- Add or update tests for policy, persistence, app-server normalization, or CardKit contracts.
+- Preserve backward migration from earlier persisted state versions.
+- New CardKit `element_id` values must start with a letter, contain only letters/numbers/underscores, remain at most 20 characters, and be unique within a card.
+- Document new environment variables in `.env.example` and `README.md`.
+- Keep documented CLI/config/runbook/policy behavior backward compatible within `1.x`; otherwise propose a migration and version change first.
+- Run `npm run check && npm test && npm run build && npm run test:package && npm audit` before requesting review.
+
+Changes to cross-user authorization, external commands, full access, migrations, backup/rollback, redaction, or release workflows are security-sensitive. Describe the threat and failure behavior in the pull request and include both a denied path and a recovery path.
+
+Maintainers additionally run `npm run release:check -- v<version>` and the real macOS/Linux/Feishu checklist. Contributors should not publish packages or create release tags from a pull request.
+
+By contributing, you agree that your contribution is licensed under the MIT License in this repository.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Feishu Codex Bridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,81 @@
+# Feishu Codex Console
+
+Use Feishu to safely continue working with Codex on your own computer—without exposing SSH, an HTTP server, or a webhook port.
+
+The bridge is local-first and outbound-only. It maps a local Codex thread to a durable Feishu workspace session: direct messages continue one context, while a top-level group prompt starts a dedicated reply thread that keeps its own project and Codex context. SQLite preserves executions, queues, approvals, review state, and team ownership behind that conversation.
+
+## Quick start
+
+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
+```
+
+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.
+
+In Feishu, send:
+
+```text
+新手引导
+```
+
+The adaptive welcome card shows only the next useful action: inspect the connection when the device is offline, select an authorized project when none is ready, or start immediately with realistic examples. Team use stays a short optional tip—one project per group, new work as a new message, and follow-ups in replies—while deployment settings stay out of the member experience.
+
+## Core commands
+
+| Feishu message | Purpose |
+|---|---|
+| `控制台` / `状态` | Device, Codex, compact account-quota summary, queue, power, permission, and current project |
+| `额度` / `/usage` / `/quota` | Full native account quota windows, reset times, plan, and available resets |
+| `项目` / `/projects` | Search, select, favorite, and inspect authorized projects |
+| `读取项目` / `/overview` | Build a local Git/package/file snapshot without starting Codex or spending AI tokens |
+| `设置` / `/settings` | Model, reasoning effort, sandbox, and temporary full-access leases |
+| `会话` / `/sessions` | Resume, compact, or start a native Codex thread |
+| `任务` / `/tasks` | Active, queued, interrupted, and recent tasks |
+| `团队` / `/team` | Privacy-preserving team workload and outcomes |
+| `运行手册` / `/runbooks` | Reviewed repository task templates |
+| `追加 <request>` | Steer the current Codex turn |
+| `排队 <task>` | Create a separate queued task |
+| `停止` | Stop current work without pretending written files were reverted |
+
+Questions and read-only analysis use one editable Feishu Markdown reply that evolves from a compact working state into the final answer. Cards are reserved for controls, approvals, questions, long-running file/code work, and failures; reliable text remains the final delivery fallback.
+
+Ordinary messages are routed locally as answers, read-only analysis, file/content writing, or code work. Questions and analysis cannot consume a write/full-access lease or create fake test/review states; only explicit code work expects test evidence. `读取项目` stays a deterministic local snapshot with zero AI tokens.
+
+## Team and safety model
+
+- Group-level controls are isolated per member by default. Inside a Feishu reply thread, all messages resolve to the same workspace session and Codex thread; execution control still requires explicit ownership or handoff.
+- Administrators, operators, and viewers have separate capabilities; project ACLs hide unauthorized workspaces.
+- Tasks keep an immutable initiator and explicit current controller for audited handoff, reclaim, and admin takeover.
+- `danger-full-access` is a ceiling, not a permanent default. Members use temporary leases, while commit, push, release, deployment, and PR mutations still require confirmation.
+- Repository policy and runbooks can only lower permissions. Secret questions cannot be answered through Feishu.
+- Runtime logs, diagnostics, cards, reviews, and text fallbacks share credential redaction. Code and prompts are not uploaded as telemetry.
+
+## Operations
+
+```bash
+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
+```
+
+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.
+
+## Documentation
+
+- [Installation](docs/INSTALLATION.md)
+- [Configuration](docs/CONFIGURATION.md)
+- [Compatibility and upgrades](docs/COMPATIBILITY.md)
+- [Product demo](docs/DEMO.md)
+- [Security](SECURITY.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [V4 workspace-session interaction model](docs/V4_WORKSPACE_SESSION_FLOW.md)
+- [Roadmap](ROADMAP.md)
+- [Contributing](CONTRIBUTING.md)
+
+The detailed product documentation is currently Chinese-first; this English entry covers the complete installation, safety, and operations path.
+
+MIT licensed. Security issues should be reported privately through GitHub Security Advisories, not a public issue.