work-ally 0.2.0-alpha.1 → 0.2.0-alpha.3

package/README.md

@@ -31,7 +31,7 @@
 - `docs/completed/`：已完成专题与已落地 spec，回答“哪些专题已经收口”。
 - `docs/planning/`：feature spec、专项设计稿、下一阶段规划，回答“后面准备做什么”或“哪些点仍待确认”。
 - `docs/product-onboarding.md`：产品同事入场指引，回答“先看什么、按什么顺序看”。
-- `docs/user-quickstart.md`：CLI 用户从零到启动的主路径。
+- `docs/user-quickstart.md`：CLI 用户从零到启动的主路径（含日志包导出）。
 - `docs/developer-workflow.md`：研发联调、验证入口、日常改动路径。
 - `docs/ops-runbook.md` 与 `docs/troubleshooting.md`：运行、恢复、值班和排障口径。
 - `docs/manual-acceptance.md`：人工验收清单。
@@ -60,6 +60,7 @@
 - bridge 主干在 `bridge/src/`
 - 产品级 Skill 包在 `skills/`
 - 默认安装与升级走 npm（install-first）
+- 安装后可先执行 `ally prepare` 做 Codex CLI 预检查
 - 官方 Codex runtime 包装在 `runtime/`
 - assistant 长期资产在 `~/.work-ally/assistants/<name>/`
 - 运行期状态、日志、会话都在 assistant desk 的 `.system/`
@@ -92,12 +93,26 @@
 
 ## CLI 用户主路径
 
+先安装（NPM）：
+
+```bash
+npm i -g work-ally@alpha
+```
+
+再启动：
+
 ```bash
 ally setup <assistant-name> --workspace /path/to/project
 ally start --assistant <assistant-name>
 ally status --assistant <assistant-name>
 ```
 
+升级同样走 NPM：
+
+```bash
+npm i -g work-ally@alpha
+```
+
 这里的 `<assistant-name>` 是你给这位 assistant 起的本机名字，例如 `pm`、`reviewer`、`ally`；它不是固定值。
 
 `ally setup <assistant-name> --workspace /path/to/project` 会自动完成：
@@ -180,6 +195,7 @@ ally status --assistant <assistant-name>
 ## 核心边界
 
 - `ally.sh` 是唯一用户入口
+- 日志导出统一走 `ally logs export`，产物是本地 zip 路径（不上报）
 - `skills/` 承接机制性 workflow，不承接主身份；不要把它们继续写回 bridge core
 - 发布入口为 npm alpha：`npm publish --tag alpha`（由 `npm run release:alpha` 统一执行）
 - 当前项目目录只承载项目代码与项目级 `AGENTS.md`

package/ally.sh

@@ -85,14 +85,16 @@ usage() {
 Usage: $CMD_NAME <command> [args]
 
 Commands:
+  prepare            [machine scope] Preflight Codex CLI prerequisites
   setup              [assistant scope] Create or bind an assistant to a project path
   assistant <subcmd> [global scope] Manage named assistant profiles
   start              [assistant scope] Start a named assistant from anywhere
   stop               [assistant scope] Stop a named assistant from anywhere
   restart            [assistant scope] Restart a named assistant from anywhere
   status             [assistant scope] Show status for a named assistant
-  logs [timeline|bridge|runtime|routine] [follow|print|--tail N]
+  logs [timeline|bridge|runtime|routine|supervisor] [follow|print|--tail N]
                      [assistant scope] View logs for a named assistant
+  logs export         [machine scope] Export assistant log bundle (.zip)
   update             [assistant scope] Show npm-based update guidance
   codex              [assistant scope] Launch official Codex CLI with assistant-bound profile
   new                [assistant scope] Start a new managed Codex thread in the assistant desk

package/docs/developer-workflow.md

@@ -23,6 +23,12 @@ npm test
 npm run release:alpha
 ```
 
+发布前仅自检（不真正发布）：
+
+```bash
+npm run release:alpha:check
+```
+
 4. 在目标机器验证安装形态：
 
 ```bash

package/docs/user-quickstart.md

@@ -6,7 +6,7 @@
 - 首发正式支持平台：`macOS arm64`
 - 已有可用的模型 provider 环境变量
 
-## 安装
+## 安装（NPM）
 
 ```bash
 npm i -g work-ally@alpha
@@ -18,6 +18,12 @@ npm i -g work-ally@alpha
 ally help
 ```
 
+安装后先做一次预检查：
+
+```bash
+ally prepare
+```
+
 ## 三步启动
 
 ```bash
@@ -26,14 +32,24 @@ ally start --assistant <assistant-name>
 ally status --assistant <assistant-name>
 ```
 
-## 升级
+## 升级（NPM）
 
 ```bash
-npm update -g work-ally
-# 或固定 alpha 通道
 npm i -g work-ally@alpha
 ```
 
+## 降级 / 固定版本
+
+```bash
+npm i -g work-ally@0.2.0-alpha.1
+```
+
+## 卸载
+
+```bash
+npm rm -g work-ally
+```
+
 ## 关键说明
 
 - 默认是 install-first：`ally` 行为来自当前 npm 安装版本
@@ -44,3 +60,30 @@ WORK_ALLY_SOURCE_DIR=/path/to/work-ally ally status --assistant <assistant-name>
 ```
 
 - 当前不支持用户侧定时任务能力；默认不会在无触发时自行执行任务
+- Codex CLI 是必需依赖；未安装时请先按官方指南安装：<https://openrouter.ai/docs/guides/guides/codex-cli>
+
+## 导出日志包（给支持同学）
+
+导出某一位助理：
+
+```bash
+ally logs export --assistant <assistant-name>
+```
+
+导出全部助理：
+
+```bash
+ally logs export --all
+```
+
+可指定输出路径：
+
+```bash
+ally logs export --all --output /tmp/work-ally-logs.zip
+```
+
+说明：
+
+- 命令会生成 zip 文件并打印最终路径
+- 每个助理对应 zip 内一个独立目录
+- 默认只打包日志与运行健康信息，不包含 `config.toml` 或 `.system/config.env`

package/internal/dispatch.sh

@@ -12,6 +12,7 @@ usage() {
 Usage: $cmd_name <command> [args]
 
 Commands:
+  prepare                                  # machine scope; preflight checks for Codex CLI prerequisites
   setup                                    # assistant scope; requires --workspace <path>
   assistant <add|ensure|bind|remove|rename|list|show> [args]   # global profile management
   start                                    # assistant scope; use --assistant <name> when needed
@@ -19,6 +20,7 @@ Commands:
   restart                                  # assistant scope; use --assistant <name> when needed
   status                                   # assistant scope; use --assistant <name> when needed
   logs [bridge|runtime|supervisor|routine] [follow|print|--tail N]   # assistant scope
+  logs export [--assistant <name>|--all] [--output <zip-path>]     # machine scope
   update                                   # assistant scope
   codex                                    # assistant scope; launch official Codex CLI with assistant profile
   new|continue|attach|threads [args]       # assistant scope; managed Codex thread actions
@@ -50,6 +52,9 @@ work_ally_init_context
 work_ally_ensure_state_dirs
 
 case "$CMD" in
+  prepare)
+    exec "$SCRIPT_DIR/modules/runtime/prepare.sh" "$@"
+    ;;
   setup)
     exec "$SCRIPT_DIR/modules/bootstrap/setup.sh" "$@"
     ;;

package/internal/lib/common.sh

@@ -1448,3 +1448,17 @@ work_ally_install_bridge_dependencies() {
   )
   work_ally_ok "Bridge dependencies installed"
 }
+
+work_ally_registry_list_assistants() {
+  [ -f "$WORK_ALLY_ASSISTANT_REGISTRY_FILE" ] || return 0
+  awk '
+    /^  [^[:space:]]+:$/ {
+      name = $0
+      sub(/^  /, "", name)
+      sub(/:$/, "", name)
+      if (name != "") {
+        print name
+      }
+    }
+  ' "$WORK_ALLY_ASSISTANT_REGISTRY_FILE"
+}

package/internal/modules/ops/log-export.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/../../lib/common.sh"
+
+work_ally_init_context
+work_ally_ensure_state_dirs
+
+usage() {
+  local cmd_name
+  cmd_name=$(work_ally_cmd_name)
+  cat <<USAGE
+Usage: $cmd_name logs export [--assistant <name>] [--all] [--output <zip-path>]
+
+Options:
+  --assistant <name>    Export logs for one assistant
+  --all                 Export logs for all registered assistants
+  --output <zip-path>   Target zip path (default: <workspace>/work-ally-logs-<timestamp>.zip)
+USAGE
+}
+
+assistant_name=""
+export_all=0
+output_zip=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --assistant)
+      [ "$#" -ge 2 ] || work_ally_die "--assistant requires a value"
+      assistant_name="$2"
+      shift 2
+      ;;
+    --assistant=*)
+      assistant_name="${1#--assistant=}"
+      shift
+      ;;
+    --all)
+      export_all=1
+      shift
+      ;;
+    --output)
+      [ "$#" -ge 2 ] || work_ally_die "--output requires a value"
+      output_zip="$2"
+      shift 2
+      ;;
+    --output=*)
+      output_zip="${1#--output=}"
+      shift
+      ;;
+    help|-h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      work_ally_die "Unknown argument: $1"
+      ;;
+  esac
+done
+
+if [ "$export_all" -eq 1 ] && [ -n "$assistant_name" ]; then
+  work_ally_die "Use either --assistant <name> or --all, not both"
+fi
+
+if [ "$export_all" -eq 0 ] && [ -z "$assistant_name" ]; then
+  assistant_name=$(work_ally_resolve_assistant_name_from_args || true)
+  [ -n "$assistant_name" ] || work_ally_die "Missing target assistant. Use --assistant <name> or --all"
+fi
+
+if ! command -v zip >/dev/null 2>&1; then
+  work_ally_die "zip is required"
+fi
+
+assistants=()
+if [ "$export_all" -eq 1 ]; then
+  while IFS= read -r name; do
+    [ -n "$name" ] || continue
+    assistants+=("$name")
+  done <<EOF2
+$(work_ally_registry_list_assistants)
+EOF2
+  [ "${#assistants[@]}" -gt 0 ] || work_ally_die "No assistants registered yet."
+else
+  work_ally_require_registered_assistant "$assistant_name"
+  assistants+=("$assistant_name")
+fi
+
+stamp=$(date +%Y%m%d-%H%M%S)
+if [ -z "$output_zip" ]; then
+  output_zip="$WORK_ALLY_WORKSPACE_ROOT/work-ally-logs-$stamp.zip"
+fi
+
+case "$output_zip" in
+  /*) ;;
+  *) output_zip="$WORK_ALLY_WORKSPACE_ROOT/$output_zip" ;;
+esac
+
+tmp_root=$(mktemp -d "${TMPDIR:-/tmp}/work-ally-log-export.XXXXXX")
+cleanup() {
+  rm -rf "$tmp_root"
+}
+trap cleanup EXIT
+
+bundle_root="$tmp_root/work-ally-logs-$stamp"
+mkdir -p "$bundle_root"
+
+copied_assistants=0
+for name in "${assistants[@]}"; do
+  assistant_home=$(work_ally_assistant_registered_home "$name")
+  [ -n "$assistant_home" ] || continue
+  logs_dir="$assistant_home/.system/logs"
+  runtime_dir="$assistant_home/.system/runtime"
+
+  if [ ! -d "$logs_dir" ] && [ ! -d "$runtime_dir" ]; then
+    continue
+  fi
+
+  assistant_bundle_dir="$bundle_root/$name"
+  mkdir -p "$assistant_bundle_dir"
+
+  if [ -d "$logs_dir" ]; then
+    mkdir -p "$assistant_bundle_dir/logs"
+    cp -R "$logs_dir/." "$assistant_bundle_dir/logs/"
+  fi
+
+  if [ -d "$runtime_dir" ]; then
+    mkdir -p "$assistant_bundle_dir/runtime"
+    find "$runtime_dir" -maxdepth 1 -type f -name '*.health.json' -exec cp {} "$assistant_bundle_dir/runtime/" \;
+    find "$runtime_dir" -maxdepth 1 -type f -name '*.pid' -exec cp {} "$assistant_bundle_dir/runtime/" \;
+  fi
+
+  copied_assistants=$((copied_assistants + 1))
+done
+
+[ "$copied_assistants" -gt 0 ] || work_ally_die "No log files found for selected assistant(s)."
+
+mkdir -p "$(dirname "$output_zip")"
+rm -f "$output_zip"
+(
+  cd "$tmp_root"
+  zip -qr "$output_zip" "$(basename "$bundle_root")"
+)
+
+work_ally_ok "Log bundle exported"
+printf 'path: %s\n' "$output_zip"
+printf 'assistants: %s\n' "$copied_assistants"

package/internal/modules/ops/logs.sh

@@ -5,6 +5,14 @@ SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/../../lib/common.sh"
 work_ally_init_context
+work_ally_ensure_state_dirs
+work_ally_load_env
+
+if [ "${1:-}" = "export" ]; then
+  shift || true
+  exec "$SCRIPT_DIR/log-export.sh" "$@"
+fi
+
 if [ -z "${WORK_ALLY_ASSISTANT_NAME:-}" ]; then
   WORK_ALLY_ASSISTANT_NAME=$(work_ally_resolve_assistant_name_from_args "$@" || true)
 fi

package/internal/modules/runtime/prepare.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/../../lib/common.sh"
+
+work_ally_init_context
+work_ally_ensure_state_dirs
+
+check_ok=1
+
+work_ally_note "Running preflight checks for official Codex CLI integration"
+
+if command -v codex >/dev/null 2>&1; then
+  codex_bin=$(command -v codex)
+  codex_version=$(codex --version 2>/dev/null | head -n 1 || true)
+  work_ally_ok "codex found: ${codex_bin}${codex_version:+ ($codex_version)}"
+else
+  work_ally_warn "codex command not found"
+  check_ok=0
+fi
+
+global_codex_config="$HOME/.codex/config.toml"
+if [ -f "$global_codex_config" ]; then
+  work_ally_ok "global Codex config found: $global_codex_config"
+else
+  work_ally_warn "global Codex config missing: $global_codex_config"
+  check_ok=0
+fi
+
+if [ -n "${WORK_ALLY_ASSISTANT_NAME:-}" ] && work_ally_registry_has_assistant "$WORK_ALLY_ASSISTANT_NAME"; then
+  assistant_codex_home=$(work_ally_assistant_registered_codex_home "$WORK_ALLY_ASSISTANT_NAME")
+  if [ -n "$assistant_codex_home" ] && [ -d "$assistant_codex_home" ]; then
+    work_ally_ok "assistant codex home ready: $assistant_codex_home"
+  else
+    work_ally_warn "assistant codex home not ready for ${WORK_ALLY_ASSISTANT_NAME:-unknown}"
+  fi
+fi
+
+if [ "$check_ok" -eq 0 ]; then
+  cat <<'EOF2'
+
+Codex CLI is required before using work-ally runtime features.
+Install and configure Codex CLI first:
+https://openrouter.ai/docs/guides/guides/codex-cli
+EOF2
+  work_ally_die "Preflight failed"
+fi
+
+cat <<'EOF2'
+
+Preflight passed.
+You can continue with:
+  ally setup <assistant-name> --workspace <path>
+  ally start --assistant <assistant-name>
+EOF2
+
+work_ally_ok "Prepare checks passed"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "work-ally",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.3",
   "private": false,
   "type": "module",
   "bin": {
@@ -25,13 +25,14 @@
     "test:full": "npm test",
     "test:fast": "node --test \"tests/unit/**/*.test.mjs\" \"tests/integration/**/*.test.mjs\"",
     "test:maintainer": "bash dev/run-regression-suite.sh",
-    "test:shell": "bash tests/shell/smoke.sh && bash tests/shell/assistant.sh && bash tests/shell/assistant-remove.sh && bash tests/shell/assistant-rename.sh && bash tests/shell/assistant-lock.sh && bash tests/shell/global-entrypoint.sh && bash tests/shell/global-manage.sh && bash tests/shell/security.sh && bash tests/shell/ops.sh && bash tests/shell/lifecycle.sh && bash tests/shell/channel-lock.sh && bash tests/shell/mcp.sh && bash tests/shell/routines.sh && bash tests/shell/recovery.sh && bash tests/shell/service-mode.sh && bash tests/shell/bridge-health-fallback.sh && bash tests/shell/startup-delivery-gate.sh && bash tests/shell/status-health.sh && bash tests/shell/codex-runtime.sh && bash tests/shell/codex-handoff.sh && bash tests/shell/supervised-start-boundary.sh",
+    "test:shell": "bash tests/shell/smoke.sh && bash tests/shell/assistant.sh && bash tests/shell/assistant-remove.sh && bash tests/shell/assistant-rename.sh && bash tests/shell/assistant-lock.sh && bash tests/shell/global-entrypoint.sh && bash tests/shell/global-manage.sh && bash tests/shell/security.sh && bash tests/shell/ops.sh && bash tests/shell/lifecycle.sh && bash tests/shell/channel-lock.sh && bash tests/shell/mcp.sh && bash tests/shell/routines.sh && bash tests/shell/recovery.sh && bash tests/shell/service-mode.sh && bash tests/shell/bridge-health-fallback.sh && bash tests/shell/startup-delivery-gate.sh && bash tests/shell/status-health.sh && bash tests/shell/codex-runtime.sh && bash tests/shell/codex-handoff.sh && bash tests/shell/supervised-start-boundary.sh && bash tests/shell/log-export.sh && bash tests/shell/prepare.sh",
     "test:bridge": "node --test \"tests/unit/**/*.test.mjs\" \"tests/integration/**/*.test.mjs\"",
     "dev:debug-workspace": "bash dev/prepare-debug-workspace.sh",
     "bridge:start": "node bridge/src/server.ts",
     "runtime:health": "node runtime/host/healthcheck-codex-app-server.ts",
     "runtime:probe": "node runtime/host/probe-codex-app-server.ts",
-    "release:alpha": "bash script/release-npm-alpha.sh"
+    "release:alpha": "bash script/release-npm-alpha.sh",
+    "release:alpha:check": "WORK_ALLY_RELEASE_PUBLISH=0 bash script/release-npm-alpha.sh"
   },
   "dependencies": {
     "@larksuiteoapi/node-sdk": "^1.50.0",