zreport 1.0.0__tar.gz

zreport-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cyberelf
+
+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.

zreport-1.0.0/MANIFEST.in

@@ -0,0 +1 @@
+prune tests

zreport-1.0.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: zreport
+Version: 1.0.0
+Summary: zreport (Zero Report) 命令行客户端：本地周报工作台的项目/资料/TODO 终端工具
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cyberelf/pm
+Keywords: weekly-report,cli,todo,whisper
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# zreport (Zero Report)
+
+Local project management workspace for weekly plans, updates, source materials, GitHub/GitLab activity, generated Markdown reports, and deterministic risk warnings. Accounts are managed by a system administrator; every user only sees their own projects, TODOs, and voice jobs.
+
+## Run
+
+Install Python dependencies and start the server (on Windows use the `py` launcher — `py -m pip install -r requirements.txt`, `py run.py` — or run the commands below from Git Bash):
+
+```bash
+python3 -m pip install --user -r requirements.txt
+python3 run.py
+```
+
+Open `http://127.0.0.1:8000` and sign in.
+
+## Accounts
+
+- All API access requires login; the login screen appears on first visit.
+- On first startup the service bootstraps an administrator account named `darren`. The initial password comes from `REPORTS_ADMIN_PASSWORD` (`.env` or environment) and defaults to `changeme` — set it before the first start, then change it in 全局设置 → 修改密码.
+- Administrators manage accounts in 全局设置 → 用户管理 (create users, reset passwords, toggle admin/enabled, delete). A user whose projects/TODOs still exist cannot be deleted; the last enabled admin cannot be removed or demoted.
+- Users see only their own data: projects, TODOs, voice jobs, and queue tasks are filtered per account. Appearance preferences and Git tokens are stored per user too.
+- 全局设置 panels for 内部 Agent LLM, 语音 TODO (ASR service), and 任务队列, plus the GitHub/GitLab enable switches and 用户管理, are visible to administrators only.
+
+For a steadier background service on port 8765:
+
+```bash
+scripts/start_server.sh
+scripts/stop_server.sh
+```
+
+Set `PORT=9000` to choose another port. These scripts need bash (macOS, Linux, WSL, or Git Bash on Windows).
+
+Or keep machine-local settings in a `.env` file at the repo root (git-ignored):
+
+```bash
+PORT=8765
+REPORTS_HOST=10.200.200.3
+```
+
+Both `python3 run.py` and `scripts/install_service.sh` read `.env` for `PORT`, `REPORTS_HOST`, and `REPORTS_FAKE_PROVIDER` defaults. Real environment variables always take precedence over the file.
+
+The service also listens on HTTPS port `8443` (set `REPORTS_TLS_PORT` to change or set it empty to disable) with a self-signed certificate generated at `data/tls/`. Phones need this HTTPS listener to use microphone access for voice TODOs: open `https://<host>:8443` and accept the certificate warning once.
+
+For the most stable local service, install it as a per-user login service (restarts with the machine, same `.env`/port knobs):
+
+```bash
+PORT=8765 scripts/install_service.sh
+scripts/uninstall_service.sh            # add "asr" to remove the voice service instead
+```
+
+One script, three platforms:
+
+- macOS: LaunchAgent (launchd), as before.
+- Linux: systemd user service `zreport.service`; run `sudo loginctl enable-linger $USER` once so it also survives logout.
+- Windows: a `.bat` in the Start Menu Startup folder (run the script from Git Bash); a console window appears at login — minimize it. Inside WSL2, use the Linux flow instead.
+
+## Docker Compose
+
+An alternative server deployment mode that runs the backend and the local voice model as containers, with the same data layout as the native service:
+
+```bash
+docker compose up -d --build
+curl --noproxy '*' "http://127.0.0.1:${PORT:-8765}/api/auth/state"
+```
+
+- Two services: `reports` (the backend) and `asr` (a local voice model — the whisper.cpp server built from source at `docker/asr/Dockerfile`, pinned by `WHISPER_CPP_VERSION`, default `v1.9.3`). The first build compiles whisper.cpp and takes a few minutes.
+- Data (SQLite, uploads, TLS certificates) lives in a docker-managed named volume (`zreport_reports-data`), never in the checkout and never in the native service's `data/` directory — the volume starts empty and the two modes never share state. It survives `docker compose down`; remove it with `docker compose down -v`, and back it up with `docker compose cp reports:/app/data ./data-backup`. Deployments from before the zreport rename still hold their data in `weekly-reports_reports-data`; copy it across once with `docker run --rm -v weekly-reports_reports-data:/from -v zreport_reports-data:/to alpine sh -c 'cp -a /from/. /to/'`.
+- Host-side settings come from the repo-root `.env` (`PORT`, `REPORTS_TLS_PORT`, `REPORTS_FAKE_PROVIDER`, `REPORTS_QUEUE_CAPACITY`, `REPORTS_QUEUE_PARALLELISM`, `REPORTS_ADMIN_PASSWORD`, and for the asr service `ASR_PORT`, `ASR_MODEL`, `WHISPER_CPP_VERSION`). Inside the container the server binds `0.0.0.0` on fixed ports 8765/8443, published as `${PORT:-8765}` / `${REPORTS_TLS_PORT:-8443}`.
+- The image ships chromium for PDF export with CJK fonts. Set `REPORTS_ADMIN_PASSWORD` in `.env` before the first start so the bootstrapped `darren` admin does not use the default password.
+- Voice TODOs: put the GGML model in `data/models/` (see Voice TODO below) before starting — the `asr` container mounts that directory read-only and serves `/inference` on container port 8766. Set the ASR endpoint in 全局设置 to `http://asr:8766/inference` (container-to-container over the compose network). The port is also published on the host as `${ASR_PORT:-8766}`; if the native whisper service already listens there, set `ASR_PORT` in `.env` to a different host port. To use a natively installed whisper service instead of the container, point the endpoint at `http://host.docker.internal:8766/inference` (reachable through the `host-gateway` mapping).
+- NVIDIA GPU hosts: layer on the GPU override so the `asr` container runs whisper.cpp on the GPU instead of the CPU (needs nvidia-container-toolkit):
+
+  ```bash
+  docker compose -f compose.yaml -f compose.gpu.yaml up -d --build
+  ```
+
+  This builds `docker/asr/Dockerfile.cuda` (same runtime layout, CUDA kernels; the first build compiles for every architecture in the list and takes a while). Extra `.env` knobs: `CUDA_VERSION` (default `12.4.1`) and `CUDA_ARCHITECTURES` (default `75;80;90` — covers Turing through Hopper; set `120` for RTX 50 / Blackwell consumer cards). The large-v3-turbo model fits in roughly 6 GB of VRAM; use a smaller GGML model on smaller cards.
+- The self-signed TLS certificate is generated at startup. `REPORTS_TLS_SAN` (defaulting to `REPORTS_HOST` from `.env`) is added to the certificate SANs so the address phones use is covered.
+- On networks where `deb.debian.org` is unreachable, set `APT_MIRROR` (for example `mirrors.tuna.tsinghua.edu.cn`) in `.env` before building — it applies to both images.
+
+## Local Tools
+
+- Git repository activity goes through the GitHub REST API (api.github.com) and GitLab REST API v4 (self-hosted instances supported; the GitLab server address is configured once per account in 全局设置 → Git 集成, defaulting to `https://gitlab.com`). No `gh`/`glab` CLIs are needed.
+- Users configure their own access tokens in 全局设置 → Git 集成 (stored per account, never returned by the API — only a last-4 hint comes back). GitHub supports multiple tokens: an entry with an organization name is used only for that org's repositories (fine-grained token with that org as resource owner), and an entry with an empty organization is the fallback for everything else (classic token, or a personal fine-grained token). Read-only access is enough: fine-grained tokens need `Contents: Read-only`, classic tokens need `repo` (or `public_repo` for public repos only); org repos additionally require org approval (Settings → Third-party access) and, when the org enforces SAML SSO, a per-token SSO authorization. GitLab uses one personal access token with the `read_api` scope (Reporter role for private projects) plus the shared server address from 全局设置; for self-signed certificates, 跳过 SSL 证书校验 in the same panel disables TLS verification for that account's GitLab connections. Without a token only public repositories are reachable, and GitHub's anonymous rate limit is low. Administrators can disable either integration globally.
+- Report generation runs exclusively through the `internal` agent, which calls the configured LLM in-process through langchain's provider bindings. Configure it in 全局设置 → 内部 Agent LLM (admin only): provider (`openai` or `anthropic`), endpoint base URL, model name, and API key. A blank base URL defaults to `https://api.openai.com/v1` / `https://api.anthropic.com`; any OpenAI-compatible or Anthropic-compatible endpoint (LM Studio, gateways) works. The API key is stored only in the local database (never returned by the API) and falls back to `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` environment variables when unset.
+- Markdown report rendering uses `markdown-it-py` with a Python-Markdown fallback.
+- Set `REPORTS_FAKE_PROVIDER=1` only for local tests or dry runs that generate a deterministic report without calling the LLM. Normal service startup uses real provider execution.
+
+## Voice TODO
+
+- A floating microphone button at the bottom right records while held. The browser only captures audio and converts it to a 16 kHz mono WAV locally (no speech leaves the machine at this stage); Safari and Chrome are supported. Microphone access requires a secure context: use `localhost` or the HTTPS listener (`https://<host>:8443`) from phones.
+- On release, the WAV goes to `POST /api/todos/voice`, which starts a background voice job and returns immediately. Only one voice job runs at a time; while one is active the mic button becomes a stop button that cancels it (`POST /api/voice-jobs/{id}/cancel`), and the progress bubble with the transcript survives page reloads (`GET /api/voice-jobs/active`). The internal agent structures the transcript into one or more TODO items.
+- The ASR service is any OpenAI-compatible transcription endpoint. The bundled choice is the whisper.cpp server (`/inference` on port 8766, large-v3-turbo model), registered as a per-user login service by `scripts/install_asr_service.sh` — same three-platform flow as the main service (macOS LaunchAgent / Linux systemd user unit / Windows Startup-folder `.bat` from Git Bash; inside WSL2 use the Linux flow; `scripts/uninstall_service.sh asr` removes it). It needs two things first:
+  1. a `whisper-server` binary — macOS: `brew install whisper-cpp`; Linux: build once (`git clone https://github.com/ggml-org/whisper.cpp && cmake -S whisper.cpp -B whisper.cpp/build && cmake --build whisper.cpp/build --target whisper-server`, keep `build/bin/whisper-server` on `PATH` or point `WHISPER_SERVER` at it); Windows: a build from the [whisper.cpp releases](https://github.com/ggml-org/whisper.cpp/releases) (or the same CMake build), with `WHISPER_SERVER` pointing at the `.exe`.
+  2. the GGML model under `data/models/` (same file the docker `asr` container mounts):
+
+     ```bash
+     curl -L -o data/models/ggml-large-v3-turbo-q5_0.bin \
+       https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q5_0.bin
+     # if huggingface.co is unreachable: https://hf-mirror.com/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q5_0.bin
+     ```
+- Transcription requests carry a `language` hint from the 识别语言 dropdown, defaulting to 中文 (`zh`) so short Chinese clips are not mis-detected as English. `自动检测` omits the field so the service decides.
+- Appearance (theme color and light/dark mode) is stored per account server-side; `PUT /api/settings` is a partial update, so each settings panel only writes the keys it manages.
+- If the configured agent fails, the raw transcript still creates TODO item(s) and the UI reports the fallback.
+
+## Uploads
+
+Supported project material types:
+
+- Markdown: `.md`, `.markdown`
+- Plain text: `.txt`
+- PDF: `.pdf`
+
+Markdown and plain text are extracted as UTF-8. PDF files are parsed server-side with pypdf and surfaced in report context with extraction status; scans or unreadable PDFs are marked failed instead of blocking the report.
+
+## Report Context
+
+Generated reports use a structured context snapshot for change detection and audit metadata. The internal agent receives the bounded evidence inline (no tool execution, no direct database or file access). The most important current-week evidence is:
+
+- `new_materials_this_week`: project materials uploaded or manually entered during the current ISO project week in `Asia/Shanghai`.
+- `git_commits_this_week`: commits from each connected repository's (GitHub or GitLab) configured tracked branches during the current ISO project week.
+
+The prompt explicitly asks the model to use these as primary evidence and to say when no new materials or commits exist.
+
+## Tests
+
+```bash
+python3 -m unittest
+openspec validate "add-weekly-project-management-system"
+```
+
+## CLI Client
+
+`zreport` is the standard-library command-line client (`zreport.py` in the repo root). On machines without the checkout, install it from PyPI (`pip install zreport`); otherwise symlink it onto your PATH (`ln -sf "$PWD/zreport.py" ~/.local/bin/zreport`; on Windows create a `zreport.cmd` shim running `@python path\to\zreport.py %*`). Sign in once with the device flow — it prints a URL and a code; open the URL, sign in, and approve (the page is the same one a phone or another machine would use) — then work from the terminal:
+
+```bash
+zreport login --server http://127.0.0.1:8765    # add --insecure once for the self-signed HTTPS port
+zreport whoami
+zreport projects
+zreport materials add 周报系统 --text "本周完成设备授权" --title 进展
+zreport materials add 周报系统 --text - < notes.txt      # pipe content through stdin
+zreport materials add 周报系统 --file notes.md 设计稿.pdf
+zreport todos
+zreport todo add "整理部署文档" -d "补充 GPU compose 说明"
+zreport todo status 3 doing
+zreport todo done 3 --project 周报系统 --reason "文档已合并"
+```
+
+- The login exchanges a device code for a long-lived session token (365 days) stored in `<config>/zreport/cli.json` with `0600` permissions; `logout` revokes it server-side. Disabling or deleting a user revokes their CLI sessions too.
+- Requests carry `Authorization: Bearer`, so every authenticated `/api` route works unchanged for CLI clients. The client always bypasses system proxy variables. The global flags `--server`, `--token`, `--insecure`, and `--config` allow scripting without touching the stored credentials.
+- An agent skill (a `SKILL.md` teaching coding agents how to drive the CLI for weekly-report work) ships inside the package: `zreport skill install` writes it to `./.agents/skills/zreport/SKILL.md`, and `zreport skill install --global` to `~/.agents/skills/zreport/SKILL.md`. Point your agent at the `.agents/skills` directory (for Claude Code, symlink it into `~/.claude/skills`).
+
+## Android Client
+
+The native Android client lives in its own repository: `../pm-android`
+(voice TODOs, TODO board, weekly report reading; talks to this service's
+HTTPS API). It now needs a login: configure the same account as the web
+UI (server responses require the session cookie). Build and setup
+instructions are in that repo's README; the planning doc moved there too
+(`ANDROID_APP_PLAN.md`).

zreport-1.0.0/README.md

@@ -0,0 +1,160 @@
+# zreport (Zero Report)
+
+Local project management workspace for weekly plans, updates, source materials, GitHub/GitLab activity, generated Markdown reports, and deterministic risk warnings. Accounts are managed by a system administrator; every user only sees their own projects, TODOs, and voice jobs.
+
+## Run
+
+Install Python dependencies and start the server (on Windows use the `py` launcher — `py -m pip install -r requirements.txt`, `py run.py` — or run the commands below from Git Bash):
+
+```bash
+python3 -m pip install --user -r requirements.txt
+python3 run.py
+```
+
+Open `http://127.0.0.1:8000` and sign in.
+
+## Accounts
+
+- All API access requires login; the login screen appears on first visit.
+- On first startup the service bootstraps an administrator account named `darren`. The initial password comes from `REPORTS_ADMIN_PASSWORD` (`.env` or environment) and defaults to `changeme` — set it before the first start, then change it in 全局设置 → 修改密码.
+- Administrators manage accounts in 全局设置 → 用户管理 (create users, reset passwords, toggle admin/enabled, delete). A user whose projects/TODOs still exist cannot be deleted; the last enabled admin cannot be removed or demoted.
+- Users see only their own data: projects, TODOs, voice jobs, and queue tasks are filtered per account. Appearance preferences and Git tokens are stored per user too.
+- 全局设置 panels for 内部 Agent LLM, 语音 TODO (ASR service), and 任务队列, plus the GitHub/GitLab enable switches and 用户管理, are visible to administrators only.
+
+For a steadier background service on port 8765:
+
+```bash
+scripts/start_server.sh
+scripts/stop_server.sh
+```
+
+Set `PORT=9000` to choose another port. These scripts need bash (macOS, Linux, WSL, or Git Bash on Windows).
+
+Or keep machine-local settings in a `.env` file at the repo root (git-ignored):
+
+```bash
+PORT=8765
+REPORTS_HOST=10.200.200.3
+```
+
+Both `python3 run.py` and `scripts/install_service.sh` read `.env` for `PORT`, `REPORTS_HOST`, and `REPORTS_FAKE_PROVIDER` defaults. Real environment variables always take precedence over the file.
+
+The service also listens on HTTPS port `8443` (set `REPORTS_TLS_PORT` to change or set it empty to disable) with a self-signed certificate generated at `data/tls/`. Phones need this HTTPS listener to use microphone access for voice TODOs: open `https://<host>:8443` and accept the certificate warning once.
+
+For the most stable local service, install it as a per-user login service (restarts with the machine, same `.env`/port knobs):
+
+```bash
+PORT=8765 scripts/install_service.sh
+scripts/uninstall_service.sh            # add "asr" to remove the voice service instead
+```
+
+One script, three platforms:
+
+- macOS: LaunchAgent (launchd), as before.
+- Linux: systemd user service `zreport.service`; run `sudo loginctl enable-linger $USER` once so it also survives logout.
+- Windows: a `.bat` in the Start Menu Startup folder (run the script from Git Bash); a console window appears at login — minimize it. Inside WSL2, use the Linux flow instead.
+
+## Docker Compose
+
+An alternative server deployment mode that runs the backend and the local voice model as containers, with the same data layout as the native service:
+
+```bash
+docker compose up -d --build
+curl --noproxy '*' "http://127.0.0.1:${PORT:-8765}/api/auth/state"
+```
+
+- Two services: `reports` (the backend) and `asr` (a local voice model — the whisper.cpp server built from source at `docker/asr/Dockerfile`, pinned by `WHISPER_CPP_VERSION`, default `v1.9.3`). The first build compiles whisper.cpp and takes a few minutes.
+- Data (SQLite, uploads, TLS certificates) lives in a docker-managed named volume (`zreport_reports-data`), never in the checkout and never in the native service's `data/` directory — the volume starts empty and the two modes never share state. It survives `docker compose down`; remove it with `docker compose down -v`, and back it up with `docker compose cp reports:/app/data ./data-backup`. Deployments from before the zreport rename still hold their data in `weekly-reports_reports-data`; copy it across once with `docker run --rm -v weekly-reports_reports-data:/from -v zreport_reports-data:/to alpine sh -c 'cp -a /from/. /to/'`.
+- Host-side settings come from the repo-root `.env` (`PORT`, `REPORTS_TLS_PORT`, `REPORTS_FAKE_PROVIDER`, `REPORTS_QUEUE_CAPACITY`, `REPORTS_QUEUE_PARALLELISM`, `REPORTS_ADMIN_PASSWORD`, and for the asr service `ASR_PORT`, `ASR_MODEL`, `WHISPER_CPP_VERSION`). Inside the container the server binds `0.0.0.0` on fixed ports 8765/8443, published as `${PORT:-8765}` / `${REPORTS_TLS_PORT:-8443}`.
+- The image ships chromium for PDF export with CJK fonts. Set `REPORTS_ADMIN_PASSWORD` in `.env` before the first start so the bootstrapped `darren` admin does not use the default password.
+- Voice TODOs: put the GGML model in `data/models/` (see Voice TODO below) before starting — the `asr` container mounts that directory read-only and serves `/inference` on container port 8766. Set the ASR endpoint in 全局设置 to `http://asr:8766/inference` (container-to-container over the compose network). The port is also published on the host as `${ASR_PORT:-8766}`; if the native whisper service already listens there, set `ASR_PORT` in `.env` to a different host port. To use a natively installed whisper service instead of the container, point the endpoint at `http://host.docker.internal:8766/inference` (reachable through the `host-gateway` mapping).
+- NVIDIA GPU hosts: layer on the GPU override so the `asr` container runs whisper.cpp on the GPU instead of the CPU (needs nvidia-container-toolkit):
+
+  ```bash
+  docker compose -f compose.yaml -f compose.gpu.yaml up -d --build
+  ```
+
+  This builds `docker/asr/Dockerfile.cuda` (same runtime layout, CUDA kernels; the first build compiles for every architecture in the list and takes a while). Extra `.env` knobs: `CUDA_VERSION` (default `12.4.1`) and `CUDA_ARCHITECTURES` (default `75;80;90` — covers Turing through Hopper; set `120` for RTX 50 / Blackwell consumer cards). The large-v3-turbo model fits in roughly 6 GB of VRAM; use a smaller GGML model on smaller cards.
+- The self-signed TLS certificate is generated at startup. `REPORTS_TLS_SAN` (defaulting to `REPORTS_HOST` from `.env`) is added to the certificate SANs so the address phones use is covered.
+- On networks where `deb.debian.org` is unreachable, set `APT_MIRROR` (for example `mirrors.tuna.tsinghua.edu.cn`) in `.env` before building — it applies to both images.
+
+## Local Tools
+
+- Git repository activity goes through the GitHub REST API (api.github.com) and GitLab REST API v4 (self-hosted instances supported; the GitLab server address is configured once per account in 全局设置 → Git 集成, defaulting to `https://gitlab.com`). No `gh`/`glab` CLIs are needed.
+- Users configure their own access tokens in 全局设置 → Git 集成 (stored per account, never returned by the API — only a last-4 hint comes back). GitHub supports multiple tokens: an entry with an organization name is used only for that org's repositories (fine-grained token with that org as resource owner), and an entry with an empty organization is the fallback for everything else (classic token, or a personal fine-grained token). Read-only access is enough: fine-grained tokens need `Contents: Read-only`, classic tokens need `repo` (or `public_repo` for public repos only); org repos additionally require org approval (Settings → Third-party access) and, when the org enforces SAML SSO, a per-token SSO authorization. GitLab uses one personal access token with the `read_api` scope (Reporter role for private projects) plus the shared server address from 全局设置; for self-signed certificates, 跳过 SSL 证书校验 in the same panel disables TLS verification for that account's GitLab connections. Without a token only public repositories are reachable, and GitHub's anonymous rate limit is low. Administrators can disable either integration globally.
+- Report generation runs exclusively through the `internal` agent, which calls the configured LLM in-process through langchain's provider bindings. Configure it in 全局设置 → 内部 Agent LLM (admin only): provider (`openai` or `anthropic`), endpoint base URL, model name, and API key. A blank base URL defaults to `https://api.openai.com/v1` / `https://api.anthropic.com`; any OpenAI-compatible or Anthropic-compatible endpoint (LM Studio, gateways) works. The API key is stored only in the local database (never returned by the API) and falls back to `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` environment variables when unset.
+- Markdown report rendering uses `markdown-it-py` with a Python-Markdown fallback.
+- Set `REPORTS_FAKE_PROVIDER=1` only for local tests or dry runs that generate a deterministic report without calling the LLM. Normal service startup uses real provider execution.
+
+## Voice TODO
+
+- A floating microphone button at the bottom right records while held. The browser only captures audio and converts it to a 16 kHz mono WAV locally (no speech leaves the machine at this stage); Safari and Chrome are supported. Microphone access requires a secure context: use `localhost` or the HTTPS listener (`https://<host>:8443`) from phones.
+- On release, the WAV goes to `POST /api/todos/voice`, which starts a background voice job and returns immediately. Only one voice job runs at a time; while one is active the mic button becomes a stop button that cancels it (`POST /api/voice-jobs/{id}/cancel`), and the progress bubble with the transcript survives page reloads (`GET /api/voice-jobs/active`). The internal agent structures the transcript into one or more TODO items.
+- The ASR service is any OpenAI-compatible transcription endpoint. The bundled choice is the whisper.cpp server (`/inference` on port 8766, large-v3-turbo model), registered as a per-user login service by `scripts/install_asr_service.sh` — same three-platform flow as the main service (macOS LaunchAgent / Linux systemd user unit / Windows Startup-folder `.bat` from Git Bash; inside WSL2 use the Linux flow; `scripts/uninstall_service.sh asr` removes it). It needs two things first:
+  1. a `whisper-server` binary — macOS: `brew install whisper-cpp`; Linux: build once (`git clone https://github.com/ggml-org/whisper.cpp && cmake -S whisper.cpp -B whisper.cpp/build && cmake --build whisper.cpp/build --target whisper-server`, keep `build/bin/whisper-server` on `PATH` or point `WHISPER_SERVER` at it); Windows: a build from the [whisper.cpp releases](https://github.com/ggml-org/whisper.cpp/releases) (or the same CMake build), with `WHISPER_SERVER` pointing at the `.exe`.
+  2. the GGML model under `data/models/` (same file the docker `asr` container mounts):
+
+     ```bash
+     curl -L -o data/models/ggml-large-v3-turbo-q5_0.bin \
+       https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q5_0.bin
+     # if huggingface.co is unreachable: https://hf-mirror.com/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q5_0.bin
+     ```
+- Transcription requests carry a `language` hint from the 识别语言 dropdown, defaulting to 中文 (`zh`) so short Chinese clips are not mis-detected as English. `自动检测` omits the field so the service decides.
+- Appearance (theme color and light/dark mode) is stored per account server-side; `PUT /api/settings` is a partial update, so each settings panel only writes the keys it manages.
+- If the configured agent fails, the raw transcript still creates TODO item(s) and the UI reports the fallback.
+
+## Uploads
+
+Supported project material types:
+
+- Markdown: `.md`, `.markdown`
+- Plain text: `.txt`
+- PDF: `.pdf`
+
+Markdown and plain text are extracted as UTF-8. PDF files are parsed server-side with pypdf and surfaced in report context with extraction status; scans or unreadable PDFs are marked failed instead of blocking the report.
+
+## Report Context
+
+Generated reports use a structured context snapshot for change detection and audit metadata. The internal agent receives the bounded evidence inline (no tool execution, no direct database or file access). The most important current-week evidence is:
+
+- `new_materials_this_week`: project materials uploaded or manually entered during the current ISO project week in `Asia/Shanghai`.
+- `git_commits_this_week`: commits from each connected repository's (GitHub or GitLab) configured tracked branches during the current ISO project week.
+
+The prompt explicitly asks the model to use these as primary evidence and to say when no new materials or commits exist.
+
+## Tests
+
+```bash
+python3 -m unittest
+openspec validate "add-weekly-project-management-system"
+```
+
+## CLI Client
+
+`zreport` is the standard-library command-line client (`zreport.py` in the repo root). On machines without the checkout, install it from PyPI (`pip install zreport`); otherwise symlink it onto your PATH (`ln -sf "$PWD/zreport.py" ~/.local/bin/zreport`; on Windows create a `zreport.cmd` shim running `@python path\to\zreport.py %*`). Sign in once with the device flow — it prints a URL and a code; open the URL, sign in, and approve (the page is the same one a phone or another machine would use) — then work from the terminal:
+
+```bash
+zreport login --server http://127.0.0.1:8765    # add --insecure once for the self-signed HTTPS port
+zreport whoami
+zreport projects
+zreport materials add 周报系统 --text "本周完成设备授权" --title 进展
+zreport materials add 周报系统 --text - < notes.txt      # pipe content through stdin
+zreport materials add 周报系统 --file notes.md 设计稿.pdf
+zreport todos
+zreport todo add "整理部署文档" -d "补充 GPU compose 说明"
+zreport todo status 3 doing
+zreport todo done 3 --project 周报系统 --reason "文档已合并"
+```
+
+- The login exchanges a device code for a long-lived session token (365 days) stored in `<config>/zreport/cli.json` with `0600` permissions; `logout` revokes it server-side. Disabling or deleting a user revokes their CLI sessions too.
+- Requests carry `Authorization: Bearer`, so every authenticated `/api` route works unchanged for CLI clients. The client always bypasses system proxy variables. The global flags `--server`, `--token`, `--insecure`, and `--config` allow scripting without touching the stored credentials.
+- An agent skill (a `SKILL.md` teaching coding agents how to drive the CLI for weekly-report work) ships inside the package: `zreport skill install` writes it to `./.agents/skills/zreport/SKILL.md`, and `zreport skill install --global` to `~/.agents/skills/zreport/SKILL.md`. Point your agent at the `.agents/skills` directory (for Claude Code, symlink it into `~/.claude/skills`).
+
+## Android Client
+
+The native Android client lives in its own repository: `../pm-android`
+(voice TODOs, TODO board, weekly report reading; talks to this service's
+HTTPS API). It now needs a login: configure the same account as the web
+UI (server responses require the session cookie). Build and setup
+instructions are in that repo's README; the planning doc moved there too
+(`ANDROID_APP_PLAN.md`).

zreport-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zreport"
+description = "zreport (Zero Report) 命令行客户端：本地周报工作台的项目/资料/TODO 终端工具"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dynamic = ["version"]
+keywords = ["weekly-report", "cli", "todo", "whisper"]
+classifiers = [
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Office/Business :: Scheduling",
+]
+
+[project.urls]
+Homepage = "https://github.com/cyberelf/pm"
+
+[project.scripts]
+zreport = "zreport:main"
+
+# the PyPI package ships the standard-library CLI only; the server
+# (reports_app) stays a local app with its heavier deps installed from
+# requirements.txt
+[tool.setuptools]
+py-modules = ["zreport"]
+
+[tool.setuptools.dynamic]
+version = { attr = "zreport.__version__" }

zreport-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zreport-1.0.0/zreport.egg-info/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: zreport
+Version: 1.0.0
+Summary: zreport (Zero Report) 命令行客户端：本地周报工作台的项目/资料/TODO 终端工具
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cyberelf/pm
+Keywords: weekly-report,cli,todo,whisper
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# zreport (Zero Report)
+
+Local project management workspace for weekly plans, updates, source materials, GitHub/GitLab activity, generated Markdown reports, and deterministic risk warnings. Accounts are managed by a system administrator; every user only sees their own projects, TODOs, and voice jobs.
+
+## Run
+
+Install Python dependencies and start the server (on Windows use the `py` launcher — `py -m pip install -r requirements.txt`, `py run.py` — or run the commands below from Git Bash):
+
+```bash
+python3 -m pip install --user -r requirements.txt
+python3 run.py
+```
+
+Open `http://127.0.0.1:8000` and sign in.
+
+## Accounts
+
+- All API access requires login; the login screen appears on first visit.
+- On first startup the service bootstraps an administrator account named `darren`. The initial password comes from `REPORTS_ADMIN_PASSWORD` (`.env` or environment) and defaults to `changeme` — set it before the first start, then change it in 全局设置 → 修改密码.
+- Administrators manage accounts in 全局设置 → 用户管理 (create users, reset passwords, toggle admin/enabled, delete). A user whose projects/TODOs still exist cannot be deleted; the last enabled admin cannot be removed or demoted.
+- Users see only their own data: projects, TODOs, voice jobs, and queue tasks are filtered per account. Appearance preferences and Git tokens are stored per user too.
+- 全局设置 panels for 内部 Agent LLM, 语音 TODO (ASR service), and 任务队列, plus the GitHub/GitLab enable switches and 用户管理, are visible to administrators only.
+
+For a steadier background service on port 8765:
+
+```bash
+scripts/start_server.sh
+scripts/stop_server.sh
+```
+
+Set `PORT=9000` to choose another port. These scripts need bash (macOS, Linux, WSL, or Git Bash on Windows).
+
+Or keep machine-local settings in a `.env` file at the repo root (git-ignored):
+
+```bash
+PORT=8765
+REPORTS_HOST=10.200.200.3
+```
+
+Both `python3 run.py` and `scripts/install_service.sh` read `.env` for `PORT`, `REPORTS_HOST`, and `REPORTS_FAKE_PROVIDER` defaults. Real environment variables always take precedence over the file.
+
+The service also listens on HTTPS port `8443` (set `REPORTS_TLS_PORT` to change or set it empty to disable) with a self-signed certificate generated at `data/tls/`. Phones need this HTTPS listener to use microphone access for voice TODOs: open `https://<host>:8443` and accept the certificate warning once.
+
+For the most stable local service, install it as a per-user login service (restarts with the machine, same `.env`/port knobs):
+
+```bash
+PORT=8765 scripts/install_service.sh
+scripts/uninstall_service.sh            # add "asr" to remove the voice service instead
+```
+
+One script, three platforms:
+
+- macOS: LaunchAgent (launchd), as before.
+- Linux: systemd user service `zreport.service`; run `sudo loginctl enable-linger $USER` once so it also survives logout.
+- Windows: a `.bat` in the Start Menu Startup folder (run the script from Git Bash); a console window appears at login — minimize it. Inside WSL2, use the Linux flow instead.
+
+## Docker Compose
+
+An alternative server deployment mode that runs the backend and the local voice model as containers, with the same data layout as the native service:
+
+```bash
+docker compose up -d --build
+curl --noproxy '*' "http://127.0.0.1:${PORT:-8765}/api/auth/state"
+```
+
+- Two services: `reports` (the backend) and `asr` (a local voice model — the whisper.cpp server built from source at `docker/asr/Dockerfile`, pinned by `WHISPER_CPP_VERSION`, default `v1.9.3`). The first build compiles whisper.cpp and takes a few minutes.
+- Data (SQLite, uploads, TLS certificates) lives in a docker-managed named volume (`zreport_reports-data`), never in the checkout and never in the native service's `data/` directory — the volume starts empty and the two modes never share state. It survives `docker compose down`; remove it with `docker compose down -v`, and back it up with `docker compose cp reports:/app/data ./data-backup`. Deployments from before the zreport rename still hold their data in `weekly-reports_reports-data`; copy it across once with `docker run --rm -v weekly-reports_reports-data:/from -v zreport_reports-data:/to alpine sh -c 'cp -a /from/. /to/'`.
+- Host-side settings come from the repo-root `.env` (`PORT`, `REPORTS_TLS_PORT`, `REPORTS_FAKE_PROVIDER`, `REPORTS_QUEUE_CAPACITY`, `REPORTS_QUEUE_PARALLELISM`, `REPORTS_ADMIN_PASSWORD`, and for the asr service `ASR_PORT`, `ASR_MODEL`, `WHISPER_CPP_VERSION`). Inside the container the server binds `0.0.0.0` on fixed ports 8765/8443, published as `${PORT:-8765}` / `${REPORTS_TLS_PORT:-8443}`.
+- The image ships chromium for PDF export with CJK fonts. Set `REPORTS_ADMIN_PASSWORD` in `.env` before the first start so the bootstrapped `darren` admin does not use the default password.
+- Voice TODOs: put the GGML model in `data/models/` (see Voice TODO below) before starting — the `asr` container mounts that directory read-only and serves `/inference` on container port 8766. Set the ASR endpoint in 全局设置 to `http://asr:8766/inference` (container-to-container over the compose network). The port is also published on the host as `${ASR_PORT:-8766}`; if the native whisper service already listens there, set `ASR_PORT` in `.env` to a different host port. To use a natively installed whisper service instead of the container, point the endpoint at `http://host.docker.internal:8766/inference` (reachable through the `host-gateway` mapping).
+- NVIDIA GPU hosts: layer on the GPU override so the `asr` container runs whisper.cpp on the GPU instead of the CPU (needs nvidia-container-toolkit):
+
+  ```bash
+  docker compose -f compose.yaml -f compose.gpu.yaml up -d --build
+  ```
+
+  This builds `docker/asr/Dockerfile.cuda` (same runtime layout, CUDA kernels; the first build compiles for every architecture in the list and takes a while). Extra `.env` knobs: `CUDA_VERSION` (default `12.4.1`) and `CUDA_ARCHITECTURES` (default `75;80;90` — covers Turing through Hopper; set `120` for RTX 50 / Blackwell consumer cards). The large-v3-turbo model fits in roughly 6 GB of VRAM; use a smaller GGML model on smaller cards.
+- The self-signed TLS certificate is generated at startup. `REPORTS_TLS_SAN` (defaulting to `REPORTS_HOST` from `.env`) is added to the certificate SANs so the address phones use is covered.
+- On networks where `deb.debian.org` is unreachable, set `APT_MIRROR` (for example `mirrors.tuna.tsinghua.edu.cn`) in `.env` before building — it applies to both images.
+
+## Local Tools
+
+- Git repository activity goes through the GitHub REST API (api.github.com) and GitLab REST API v4 (self-hosted instances supported; the GitLab server address is configured once per account in 全局设置 → Git 集成, defaulting to `https://gitlab.com`). No `gh`/`glab` CLIs are needed.
+- Users configure their own access tokens in 全局设置 → Git 集成 (stored per account, never returned by the API — only a last-4 hint comes back). GitHub supports multiple tokens: an entry with an organization name is used only for that org's repositories (fine-grained token with that org as resource owner), and an entry with an empty organization is the fallback for everything else (classic token, or a personal fine-grained token). Read-only access is enough: fine-grained tokens need `Contents: Read-only`, classic tokens need `repo` (or `public_repo` for public repos only); org repos additionally require org approval (Settings → Third-party access) and, when the org enforces SAML SSO, a per-token SSO authorization. GitLab uses one personal access token with the `read_api` scope (Reporter role for private projects) plus the shared server address from 全局设置; for self-signed certificates, 跳过 SSL 证书校验 in the same panel disables TLS verification for that account's GitLab connections. Without a token only public repositories are reachable, and GitHub's anonymous rate limit is low. Administrators can disable either integration globally.
+- Report generation runs exclusively through the `internal` agent, which calls the configured LLM in-process through langchain's provider bindings. Configure it in 全局设置 → 内部 Agent LLM (admin only): provider (`openai` or `anthropic`), endpoint base URL, model name, and API key. A blank base URL defaults to `https://api.openai.com/v1` / `https://api.anthropic.com`; any OpenAI-compatible or Anthropic-compatible endpoint (LM Studio, gateways) works. The API key is stored only in the local database (never returned by the API) and falls back to `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` environment variables when unset.
+- Markdown report rendering uses `markdown-it-py` with a Python-Markdown fallback.
+- Set `REPORTS_FAKE_PROVIDER=1` only for local tests or dry runs that generate a deterministic report without calling the LLM. Normal service startup uses real provider execution.
+
+## Voice TODO
+
+- A floating microphone button at the bottom right records while held. The browser only captures audio and converts it to a 16 kHz mono WAV locally (no speech leaves the machine at this stage); Safari and Chrome are supported. Microphone access requires a secure context: use `localhost` or the HTTPS listener (`https://<host>:8443`) from phones.
+- On release, the WAV goes to `POST /api/todos/voice`, which starts a background voice job and returns immediately. Only one voice job runs at a time; while one is active the mic button becomes a stop button that cancels it (`POST /api/voice-jobs/{id}/cancel`), and the progress bubble with the transcript survives page reloads (`GET /api/voice-jobs/active`). The internal agent structures the transcript into one or more TODO items.
+- The ASR service is any OpenAI-compatible transcription endpoint. The bundled choice is the whisper.cpp server (`/inference` on port 8766, large-v3-turbo model), registered as a per-user login service by `scripts/install_asr_service.sh` — same three-platform flow as the main service (macOS LaunchAgent / Linux systemd user unit / Windows Startup-folder `.bat` from Git Bash; inside WSL2 use the Linux flow; `scripts/uninstall_service.sh asr` removes it). It needs two things first:
+  1. a `whisper-server` binary — macOS: `brew install whisper-cpp`; Linux: build once (`git clone https://github.com/ggml-org/whisper.cpp && cmake -S whisper.cpp -B whisper.cpp/build && cmake --build whisper.cpp/build --target whisper-server`, keep `build/bin/whisper-server` on `PATH` or point `WHISPER_SERVER` at it); Windows: a build from the [whisper.cpp releases](https://github.com/ggml-org/whisper.cpp/releases) (or the same CMake build), with `WHISPER_SERVER` pointing at the `.exe`.
+  2. the GGML model under `data/models/` (same file the docker `asr` container mounts):
+
+     ```bash
+     curl -L -o data/models/ggml-large-v3-turbo-q5_0.bin \
+       https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q5_0.bin
+     # if huggingface.co is unreachable: https://hf-mirror.com/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q5_0.bin
+     ```
+- Transcription requests carry a `language` hint from the 识别语言 dropdown, defaulting to 中文 (`zh`) so short Chinese clips are not mis-detected as English. `自动检测` omits the field so the service decides.
+- Appearance (theme color and light/dark mode) is stored per account server-side; `PUT /api/settings` is a partial update, so each settings panel only writes the keys it manages.
+- If the configured agent fails, the raw transcript still creates TODO item(s) and the UI reports the fallback.
+
+## Uploads
+
+Supported project material types:
+
+- Markdown: `.md`, `.markdown`
+- Plain text: `.txt`
+- PDF: `.pdf`
+
+Markdown and plain text are extracted as UTF-8. PDF files are parsed server-side with pypdf and surfaced in report context with extraction status; scans or unreadable PDFs are marked failed instead of blocking the report.
+
+## Report Context
+
+Generated reports use a structured context snapshot for change detection and audit metadata. The internal agent receives the bounded evidence inline (no tool execution, no direct database or file access). The most important current-week evidence is:
+
+- `new_materials_this_week`: project materials uploaded or manually entered during the current ISO project week in `Asia/Shanghai`.
+- `git_commits_this_week`: commits from each connected repository's (GitHub or GitLab) configured tracked branches during the current ISO project week.
+
+The prompt explicitly asks the model to use these as primary evidence and to say when no new materials or commits exist.
+
+## Tests
+
+```bash
+python3 -m unittest
+openspec validate "add-weekly-project-management-system"
+```
+
+## CLI Client
+
+`zreport` is the standard-library command-line client (`zreport.py` in the repo root). On machines without the checkout, install it from PyPI (`pip install zreport`); otherwise symlink it onto your PATH (`ln -sf "$PWD/zreport.py" ~/.local/bin/zreport`; on Windows create a `zreport.cmd` shim running `@python path\to\zreport.py %*`). Sign in once with the device flow — it prints a URL and a code; open the URL, sign in, and approve (the page is the same one a phone or another machine would use) — then work from the terminal:
+
+```bash
+zreport login --server http://127.0.0.1:8765    # add --insecure once for the self-signed HTTPS port
+zreport whoami
+zreport projects
+zreport materials add 周报系统 --text "本周完成设备授权" --title 进展
+zreport materials add 周报系统 --text - < notes.txt      # pipe content through stdin
+zreport materials add 周报系统 --file notes.md 设计稿.pdf
+zreport todos
+zreport todo add "整理部署文档" -d "补充 GPU compose 说明"
+zreport todo status 3 doing
+zreport todo done 3 --project 周报系统 --reason "文档已合并"
+```
+
+- The login exchanges a device code for a long-lived session token (365 days) stored in `<config>/zreport/cli.json` with `0600` permissions; `logout` revokes it server-side. Disabling or deleting a user revokes their CLI sessions too.
+- Requests carry `Authorization: Bearer`, so every authenticated `/api` route works unchanged for CLI clients. The client always bypasses system proxy variables. The global flags `--server`, `--token`, `--insecure`, and `--config` allow scripting without touching the stored credentials.
+- An agent skill (a `SKILL.md` teaching coding agents how to drive the CLI for weekly-report work) ships inside the package: `zreport skill install` writes it to `./.agents/skills/zreport/SKILL.md`, and `zreport skill install --global` to `~/.agents/skills/zreport/SKILL.md`. Point your agent at the `.agents/skills` directory (for Claude Code, symlink it into `~/.claude/skills`).
+
+## Android Client
+
+The native Android client lives in its own repository: `../pm-android`
+(voice TODOs, TODO board, weekly report reading; talks to this service's
+HTTPS API). It now needs a login: configure the same account as the web
+UI (server responses require the session cookie). Build and setup
+instructions are in that repo's README; the planning doc moved there too
+(`ANDROID_APP_PLAN.md`).

zreport-1.0.0/zreport.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+zreport.py
+zreport.egg-info/PKG-INFO
+zreport.egg-info/SOURCES.txt
+zreport.egg-info/dependency_links.txt
+zreport.egg-info/entry_points.txt
+zreport.egg-info/top_level.txt

zreport-1.0.0/zreport.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zreport-1.0.0/zreport.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zreport = zreport:main

zreport-1.0.0/zreport.egg-info/top_level.txt

@@ -0,0 +1 @@
+zreport

zreport-1.0.0/zreport.py

@@ -0,0 +1,525 @@
+#!/usr/bin/env python3
+"""Command-line client (zreport) for the zreport server.
+
+Standard library only. Sign in once with the OAuth-style device flow
+(`zreport login`), then work with projects, materials, and TODOs from
+the terminal:
+
+    python3 zreport.py login --server http://127.0.0.1:8765
+    python3 zreport.py projects
+    python3 zreport.py materials add my-project --text "shipped device auth" --title progress
+    python3 zreport.py materials add my-project --file notes.md spec.pdf
+    python3 zreport.py todos
+    python3 zreport.py todo add "write deploy docs" -d "include the GPU compose guide"
+    python3 zreport.py todo status 3 doing
+    python3 zreport.py todo done 3 --project my-project --reason "merged"
+
+The token is stored in <config>/zreport/cli.json (0600). Self-signed
+TLS: log in with --insecure once and the choice is remembered.
+"""
+
+import argparse
+import base64
+import json
+import os
+import ssl
+import sys
+import time
+import unicodedata
+import urllib.error
+import urllib.request
+import webbrowser
+from pathlib import Path
+from urllib.parse import urlparse
+
+DEFAULT_SERVER = "http://127.0.0.1:8765"
+__version__ = "1.0.0"
+LOGIN_TIMEOUT_SECONDS = 15 * 60
+MATERIAL_EXTENSIONS = {".md": "text/markdown", ".markdown": "text/markdown", ".txt": "text/plain", ".pdf": "application/pdf"}
+TODO_STATUSES = ("todo", "doing")
+# The editable copy lives at skills/zreport/SKILL.md in the repo; this
+# embedded copy ships inside the wheel (the package is a single module), and
+# a test asserts the two stay identical.
+SKILL_MD = """\
+---
+name: zreport
+description: Summarize and organize weekly-report material with the zreport CLI. Use when the user asks to collect or organize this week's work, draft a weekly report, review project progress or TODO status, submit work notes to a project, or manage TODOs.
+---
+
+# Summarize weekly-report material with zreport
+
+zreport is the command-line client of a local weekly-report workspace
+(projects, materials, TODOs, generated weekly reports). Drive the `zreport`
+command only — do not call the server's HTTP API directly.
+
+## Before you start
+
+- Server URL: read `server` from `~/.config/zreport/cli.json` when it exists;
+  otherwise ask the user. Every command also accepts `--server <URL>`.
+- Sign-in check: run `zreport whoami`. If it reports "Not signed in", run
+  `zreport login --server <URL>`: it prints a device code and a `/device`
+  URL. The browser approval step belongs to the user — agents cannot
+  approve their own device.
+
+## Collect the current state (read-only)
+
+- `zreport projects`
+- `zreport todos` and `zreport todos --all` (`--all` includes closed TODOs;
+  the PROJECT column shows which project a closed TODO was archived into)
+
+Limitation: the CLI has no subcommands yet for reading material bodies or
+archived weekly reports. If the task truly needs them, tell the user to
+open an issue at https://github.com/cyberelf/pm/issues instead of working
+around the CLI.
+
+## Organize the summary
+
+- Evidence order: what the user dictates or points at, then active TODOs and
+  TODOs closed this week, then archived TODOs (`todos --all`).
+- Time window: ISO week, timezone Asia/Shanghai.
+- Suggested structure: done this week / in progress / blockers and risks /
+  next week's plan. State only what the evidence supports; say explicitly
+  when nothing new exists instead of padding.
+- Show the draft to the user and get confirmation before writing anything.
+
+## Write back (confirm each item with the user first)
+
+- Text material: `echo "..." | zreport materials add <project ID or name> --text - --title "Title"`
+- Attachments: `zreport materials add <project> --file a.md b.pdf`
+  (supported: .md .markdown .txt .pdf)
+- TODOs: `zreport todo add "Title" -d "Details"`, then
+  `zreport todo status <ID> doing`, then
+  `zreport todo done <ID> -p <project> -r "closing note"` (done archives the
+  TODO as a material of that project).
+- Server-side constraint: only materials created in the current ISO week can
+  be edited or deleted; older ones are locked. Surface server errors as-is.
+"""
+
+
+class CliError(Exception):
+    pass
+
+
+# ---------------------------------------------------------------- config
+
+
+def default_config_path():
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(os.path.expanduser("~"), ".config")
+    return Path(base) / "zreport" / "cli.json"
+
+
+def load_config(path):
+    try:
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {}
+    except (OSError, ValueError) as exc:
+        raise CliError(f"cannot read config {path}: {exc}") from exc
+    return data if isinstance(data, dict) else {}
+
+
+def save_config(path, config):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # create with 0600 from the first byte: a plain write_text would briefly
+    # expose the token at the umask's default mode before chmod runs; the
+    # trailing chmod still tightens files written by older versions
+    payload = (json.dumps(config, ensure_ascii=False, indent=2) + "\n").encode("utf-8")
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "wb") as fh:
+        fh.write(payload)
+    path.chmod(0o600)
+
+
+# ---------------------------------------------------------------- http
+
+
+def build_opener(insecure):
+    # bypass http_proxy/https_proxy: the service is reached on the LAN or
+    # loopback, a system proxy would only break the request
+    return urllib.request.build_opener(
+        urllib.request.ProxyHandler({}),
+        urllib.request.HTTPSHandler(context=ssl._create_unverified_context() if insecure else None),
+    )
+
+
+def api_request(config, method, path, payload=None, timeout=30):
+    server = config["server"].rstrip("/")
+    # keep urllib's file/ftp handlers out of reach via a crafted --server
+    if urlparse(server).scheme not in ("http", "https"):
+        raise CliError(f"unsupported server URL: {config['server']} (only http:// or https://)")
+    opener = build_opener(not config.get("tls_verify", True))
+    data = None
+    headers = {}
+    if payload is not None:
+        data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+    if config.get("token"):
+        headers["Authorization"] = f"Bearer {config['token']}"
+    request = urllib.request.Request(server + path, data=data, headers=headers, method=method)
+    try:
+        with opener.open(request, timeout=timeout) as response:
+            body = response.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", "replace")
+        try:
+            detail = json.loads(detail).get("error") or detail
+        except ValueError:
+            pass
+        raise CliError(f"HTTP {exc.code}: {detail.strip()}") from exc
+    except urllib.error.URLError as exc:
+        hint = connection_error_hint(str(exc.reason))
+        raise CliError(f"cannot reach {config['server']}: {exc.reason}{hint}") from exc
+    try:
+        return json.loads(body) if body else {}
+    except ValueError:
+        preview = body.strip()[:120]
+        raise CliError(f"server returned non-JSON content; this is probably not a zreport server: {preview}") from None
+
+
+def connection_error_hint(reason):
+    """Turn bare SSL noise into an actionable hint."""
+    if "CERTIFICATE_VERIFY_FAILED" in reason:
+        return " (self-signed certificates trigger this: double-check the URL, or pass --insecure to skip verification)"
+    if "CERTIFICATE_REQUIRED" in reason:
+        return " (the peer demands a client certificate: this is probably not a zreport server, check URL and port)"
+    return ""
+
+
+# ---------------------------------------------------------------- output
+
+
+def display_width(text):
+    return sum(2 if unicodedata.east_asian_width(char) in ("F", "W") else 1 for char in str(text))
+
+
+def print_table(headers, rows):
+    widths = [display_width(header) for header in headers]
+    for row in rows:
+        for index, cell in enumerate(row):
+            widths[index] = max(widths[index], display_width(cell))
+
+    def format_row(cells):
+        padded = ""
+        for index, cell in enumerate(cells):
+            pad = " " * (widths[index] - display_width(cell))
+            padded += str(cell) + pad + ("  " if index + 1 < len(cells) else "")
+        return padded.rstrip()
+
+    print(format_row(headers))
+    print("  ".join("-" * width for width in widths))
+    for row in rows:
+        print(format_row(row))
+
+
+# ---------------------------------------------------------------- login
+
+
+def cmd_login(args, config, config_path):
+    server = (args.server or config.get("server") or DEFAULT_SERVER).rstrip("/")
+    login_config = {"server": server, "tls_verify": not args.insecure}
+    start = api_request(login_config, "POST", "/api/device/auth/start", payload={}, timeout=30)
+    user_code = start["user_code"]
+    url = server + start.get("verification_path", "/device")
+    print(f"1. Open the authorization page: {url}")
+    try:
+        webbrowser.open(url)
+    except Exception:
+        pass
+    print(f"2. Sign in and enter the code: {user_code}")
+    print("waiting for approval", end="", flush=True)
+
+    deadline = time.monotonic() + min(int(start.get("expires_in", 900)), LOGIN_TIMEOUT_SECONDS)
+    interval = max(1, int(start.get("interval", 5)))
+    while time.monotonic() < deadline:
+        time.sleep(interval)
+        result = api_request(login_config, "POST", "/api/device/auth/poll", payload={"device_code": start["device_code"]}, timeout=30)
+        status = result.get("status")
+        if status == "pending":
+            print(".", end="", flush=True)
+            continue
+        print()
+        if status == "approved":
+            config.update(login_config)
+            config["token"] = result["access_token"]
+            config["user"] = (result.get("user") or {}).get("username")
+            save_config(config_path, config)
+            print(f"Signed in as {config['user']} (credentials saved to {config_path})")
+            return 0
+        if status == "denied":
+            raise CliError("authorization denied")
+        raise CliError("device code expired, log in again")
+    print()
+    raise CliError("timed out waiting for approval, log in again")
+
+
+def cmd_logout(args, config, config_path):
+    if config.get("token"):
+        try:
+            api_request(config, "POST", "/api/auth/logout", payload={})
+        except CliError:
+            pass  # token may already be gone server-side; clear locally anyway
+    config.pop("token", None)
+    config.pop("user", None)
+    save_config(config_path, config)
+    print("Signed out")
+    return 0
+
+
+def cmd_whoami(args, config, config_path):
+    state = api_request(config, "GET", "/api/auth/state")
+    user = state.get("current_user")
+    if not user:
+        print("Not signed in (run the login command)")
+        return 1
+    role = "admin" if user.get("is_admin") else "user"
+    print(f"{user['username']} ({role}) @ {config['server']} (server v{state.get('version', '?')})")
+    return 0
+
+
+# ---------------------------------------------------------------- projects & materials
+
+
+def require_login(config):
+    if not config.get("token"):
+        raise CliError("not signed in: run the login command first")
+
+
+def fetch_projects(config):
+    state = api_request(config, "GET", "/api/state")
+    return state.get("projects") or []
+
+
+def resolve_project(config, ref):
+    projects = fetch_projects(config)
+    for project in projects:
+        if str(project["id"]) == str(ref) or project["name"] == ref:
+            return project
+    raise CliError(f"project not found: {ref} (see the projects command)")
+
+
+def cmd_projects(args, config, config_path):
+    require_login(config)
+    rows = [
+        (
+            project["id"],
+            project["name"],
+            project["status"],
+            project.get("timezone", ""),
+            (project.get("updated_at") or "")[:16].replace("T", " "),
+        )
+        for project in fetch_projects(config)
+    ]
+    print_table(["ID", "PROJECT", "STATUS", "TIMEZONE", "UPDATED"], rows)
+    return 0
+
+
+def cmd_materials_add(args, config, config_path):
+    require_login(config)
+    project = resolve_project(config, args.project)
+    if args.file:
+        files = []
+        for raw_path in args.file:
+            path = Path(raw_path).expanduser()
+            ext = path.suffix.lower()
+            if ext not in MATERIAL_EXTENSIONS:
+                raise CliError(f"unsupported file type: {path.name} (supported: {' '.join(sorted(MATERIAL_EXTENSIONS))})")
+            try:
+                raw = path.read_bytes()
+            except OSError as exc:
+                raise CliError(f"cannot read {path}: {exc}") from exc
+            files.append(
+                {
+                    "filename": path.name,
+                    "content_base64": base64.b64encode(raw).decode("ascii"),
+                    "content_type": MATERIAL_EXTENSIONS[ext],
+                }
+            )
+        result = api_request(
+            config,
+            "POST",
+            f"/api/projects/{project['id']}/materials",
+            payload={"files": files},
+            timeout=300,
+        )
+        print(f"Uploaded {len(files)} attachment(s) to '{project['name']}' (material IDs: {', '.join(str(i) for i in result.get('ids', []))})")
+        return 0
+    text = args.text
+    if text == "-":
+        text = sys.stdin.read()
+    text = (text or "").strip()
+    if not text:
+        raise CliError('provide content: --text "..." (or --text - to read stdin), or attach files with --file')
+    title = (args.title or "").strip() or "CLI note"
+    result = api_request(
+        config,
+        "POST",
+        f"/api/projects/{project['id']}/materials",
+        payload={"source_type": "manual", "title": title, "content": text},
+    )
+    print(f"Submitted text material to '{project['name']}' (material ID: {result.get('id')})")
+    return 0
+
+
+# ---------------------------------------------------------------- todos
+
+
+def cmd_todos(args, config, config_path):
+    require_login(config)
+    todos = api_request(config, "GET", "/api/todos").get("todos") or []
+    if not args.all:
+        todos = [todo for todo in todos if todo["status"] != "closed"]
+    rows = [
+        (
+            todo["id"],
+            todo["status"],
+            todo.get("project_name") or "-",
+            todo["title"],
+        )
+        for todo in todos
+    ]
+    print_table(["ID", "STATUS", "PROJECT", "TITLE"], rows)
+    return 0
+
+
+def cmd_todo_add(args, config, config_path):
+    require_login(config)
+    result = api_request(config, "POST", "/api/todos", payload={"title": args.title, "description": args.description or ""})
+    print(f"Created TODO #{result.get('id')}: {args.title}")
+    return 0
+
+
+def cmd_todo_status(args, config, config_path):
+    require_login(config)
+    api_request(config, "PUT", f"/api/todos/{args.id}", payload={"status": args.status})
+    print(f"TODO #{args.id} status set to {args.status}")
+    return 0
+
+
+def cmd_todo_done(args, config, config_path):
+    require_login(config)
+    project = resolve_project(config, args.project)
+    result = api_request(
+        config,
+        "POST",
+        f"/api/todos/{args.id}/close",
+        payload={"reason": args.reason, "project_id": project["id"]},
+    )
+    material_id = result.get("material_id")
+    archived = f", archived as material #{material_id} in '{project['name']}'" if material_id else ""
+    print(f"TODO #{args.id} done{archived}")
+    return 0
+
+
+# ---------------------------------------------------------------- agent skill
+
+
+def cmd_skill_install(args, config, config_path):
+    base = Path.home() / ".agents" if args.global_install else Path.cwd() / ".agents"
+    target = base / "skills" / "zreport" / "SKILL.md"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(SKILL_MD, encoding="utf-8")
+    print(f"Skill installed: {target}")
+    print("Point your coding agent at the .agents/skills directory (e.g. symlink it into ~/.claude/skills for Claude Code).")
+    return 0
+
+
+# ---------------------------------------------------------------- parser
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(prog="zreport", description="zreport (Zero Report) command-line client")
+    parser.add_argument("--server", help=f"server URL (default {DEFAULT_SERVER}; from saved config after login)")
+    parser.add_argument("--token", help="use this Bearer token (default: from saved config)")
+    parser.add_argument("--insecure", action="store_true", help="skip TLS certificate verification (self-signed certs)")
+    parser.add_argument("--config", help="credentials file path (default <config>/zreport/cli.json)")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    login = sub.add_parser("login", help="sign in with the device authorization flow")
+    login.add_argument("--server", help="server URL, e.g. http://127.0.0.1:8765")
+    login.add_argument("--insecure", action="store_true", help="skip TLS certificate verification (self-signed certs)")
+    login.set_defaults(func=cmd_login)
+
+    logout = sub.add_parser("logout", help="sign out and clear local credentials")
+    logout.set_defaults(func=cmd_logout)
+
+    whoami = sub.add_parser("whoami", help="show the signed-in user")
+    whoami.set_defaults(func=cmd_whoami)
+
+    projects = sub.add_parser("projects", help="list projects")
+    projects.set_defaults(func=cmd_projects)
+
+    materials = sub.add_parser("materials", help="project materials")
+    materials_sub = materials.add_subparsers(dest="materials_command", required=True)
+    materials_add = materials_sub.add_parser("add", help="add material (text or file attachment)")
+    materials_add.add_argument("project", help="project ID or name")
+    materials_add.add_argument("--text", help="text content; pass - to read from stdin")
+    materials_add.add_argument("--title", help="text material title (default: CLI note)")
+    materials_add.add_argument("--file", nargs="+", metavar="PATH", help="file attachments (.md .markdown .txt .pdf, multiple allowed)")
+    materials_add.set_defaults(func=cmd_materials_add)
+
+    todos = sub.add_parser("todos", help="list TODOs")
+    todos.add_argument("--all", action="store_true", help="include closed TODOs")
+    todos.set_defaults(func=cmd_todos)
+
+    todo = sub.add_parser("todo", help="TODO operations")
+    todo_sub = todo.add_subparsers(dest="todo_command", required=True)
+    todo_add = todo_sub.add_parser("add", help="create a TODO")
+    todo_add.add_argument("title", help="title")
+    todo_add.add_argument("-d", "--description", help="details")
+    todo_add.set_defaults(func=cmd_todo_add)
+
+    todo_status = todo_sub.add_parser("status", help="change a TODO's status")
+    todo_status.add_argument("id", type=int, help="TODO ID")
+    todo_status.add_argument("status", choices=TODO_STATUSES, help="target status")
+    todo_status.set_defaults(func=cmd_todo_status)
+
+    todo_done = todo_sub.add_parser("done", help="close a TODO and archive it to a project")
+    todo_done.add_argument("id", type=int, help="TODO ID")
+    todo_done.add_argument("-p", "--project", required=True, help="project to archive into (ID or name)")
+    todo_done.add_argument("-r", "--reason", default="done", help="closing reason (default: done)")
+    todo_done.set_defaults(func=cmd_todo_done)
+
+    skill = sub.add_parser("skill", help="manage the agent skill for coding agents")
+    skill_sub = skill.add_subparsers(dest="skill_command", required=True)
+    skill_install = skill_sub.add_parser(
+        "install",
+        help="install the skill into .agents/skills/zreport/ (current directory, or home with --global)",
+    )
+    skill_install.add_argument(
+        "--global", dest="global_install", action="store_true",
+        help="install into ~/.agents instead of ./.agents",
+    )
+    skill_install.set_defaults(func=cmd_skill_install)
+
+    return parser
+
+
+def main(argv=None, config_file=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    config_path = Path(args.config or config_file or default_config_path())
+    config = load_config(config_path)
+    if args.server:
+        config["server"] = args.server.rstrip("/")
+    elif not config.get("server"):
+        config["server"] = DEFAULT_SERVER
+    if args.token:
+        config["token"] = args.token
+    if args.insecure:
+        config["tls_verify"] = False
+    if not hasattr(args, "func"):
+        parser.print_usage()
+        return 2
+    try:
+        return args.func(args, config, config_path)
+    except CliError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\ncancelled", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())