Liberxue · Oct 6, 2026 · Aug 9, 2026 · Aug 9, 2026 · Oct 6, 2026 · Oct 6, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -52,6 +52,25 @@ jobs:
       - uses: taiki-e/install-action@cargo-audit
       - run: cargo audit
 
+  # —— 文档门:多语言文档链接 / 跨语言配对 校验(纯 Python,无需编译)——
+  docs:
+    name: docs link check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: check doc links
+        run: python3 scripts/docs-link-check.py --report
+      # 不论通过与否都留存报告,便于排查失效链接。
+      - name: upload report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-link-check-report
+          path: docs/link-check-report.md
+
   # —— 前端构建门:类型检查 + 产物构建,防 web/ 腐化 ——
   web:
     name: web build

diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ AI ROI · human-AI efficiency analytics · software engineering modeling · Task
 [![Rust](https://img.shields.io/badge/Rust-2021-orange.svg)](https://www.rust-lang.org/)
 [![License](https://img.shields.io/badge/License-GPL--2.0-blue.svg)](LICENSE)
 [![status](https://img.shields.io/badge/status-experimental-yellow.svg)](#status)
-&nbsp; · &nbsp; [简体中文](README.zh-CN.md) | English
+&nbsp; · &nbsp; [简体中文](README.zh-CN.md) · English
 
 Shepherd is a platform for supervising AI-driven development. AI can write code, but it won't judge whether it actually finished the requirement, and it won't be accountable for the result. Instead of building another "smarter agent," Shepherd sits around the agent: it breaks requirements down for AI executors to work on, puts a human approval step at two points (design and verification), and keeps a record of the whole thing.
 
@@ -17,9 +17,6 @@ Shepherd is a platform for supervising AI-driven development. AI can write code,
 
 <img src="docs/assets/screenshot-intro.png" alt="Shepherd — scenario run report" width="100%" />
 
-<!-- demo GIF pending: see docs/assets/. Uncomment the next line once it exists. -->
-<!-- ![demo](docs/assets/demo.gif) -->
-
 ## How it works
 
 A requirement roughly travels like this:
@@ -81,39 +78,6 @@ On top of that rule you get, per project and per requirement:
 
 It measures shipped outcomes rather than keystrokes. The numbers come out smaller and more boring than "90% of our code is AI-written" claims — which is the point.
 
-## Running it
-
-```bash
-# 1) A Postgres; migrations are applied automatically on startup
-docker run -d --name shep-pg \
-  -e POSTGRES_USER=msuser -e POSTGRES_PASSWORD=mspass -e POSTGRES_DB=mstest \
-  -p 55432:5432 postgres:16-alpine
-
-# 2) Start the server (the root sets default-members, so plain `cargo run` works)
-DATABASE_URL=postgres://msuser:mspass@localhost:55432/mstest \
-SHEPHERD_ADMIN_PASSWORD=s3cret \
-cargo run                       # → http://localhost:8088
-```
-
-```bash
-# Log in for a token
-curl -s localhost:8088/auth/login -H 'content-type: application/json' \
-  -d '{"username":"admin","password":"s3cret"}'
-```
-
-The web console, and starting an executor on an internal machine:
-
-```bash
-cd web && npm install && npm run dev          # Vite console
-
-SHEPHERD_AGENT_FLEET=1 cargo run              # server in fleet mode
-SHEPHERD_BASE=http://<server>:8088 SHEPHERD_CAPS=CLAUDE_CODE cargo run -p agent-runtime
-```
-
-<!-- console screenshot pending: see docs/assets/. -->
-
-Prefer one command? `docker compose -f deploy/docker/docker-compose.yml up --build` brings up the whole stack (server + agent-runtime + web + Postgres + Redis) — see the [usage guide](docs/USAGE.md) and [deployment guide](docs/DEPLOYMENT.md).
-
 ## What's in here
 
 Each business module is its own crate, laid out hexagonally: `domain` / `ports` / `application` are pure logic with no IO by default, while the database and HTTP live in `adapters` behind feature flags. `tests/architecture.rs` scans the source and fails the build if a pure layer ever imports an IO crate like sqlx or axum — that keeps the layering from quietly eroding over time.
@@ -145,37 +109,21 @@ web/               React + antd frontend
 ```
 </details>
 
-<details>
-<summary>Main environment variables</summary>
-
-Server (consolidated into a typed `ServerConfig`):
-
-| Variable | Default | Meaning |
-|---|---|---|
-| `DATABASE_URL` | local mstest | PG connection string |
-| `SHEPHERD_BIND` | `0.0.0.0:8088` | main API listen address |
-| `SHEPHERD_ADMIN_PASSWORD` | `admin` | admin password upserted idempotently on boot |
-| `SHEPHERD_AGENT_FLEET` | — | set to enable fleet mode |
-| `SHEPHERD_FLEET_REDIS` | — | set to use a Redis distributed queue / registry |
-| `SHEPHERD_FEISHU_*` / `SHEPHERD_WECOM_*` | — | OIDC third-party login |
-
-Executor `agent-runtime`:
-
-| Variable | Default | Meaning |
-|---|---|---|
-| `SHEPHERD_BASE` | `http://127.0.0.1:9180` | server address |
-| `SHEPHERD_CAPS` | `CLAUDE_CODE` | comma-separated capabilities (which tasks to claim) |
-| `AGENT_CONCURRENCY` | `1` | max concurrent tasks |
-| `CLAUDE_BIN` / `CODEX_CMD` / `OPENCODE_CMD` | `claude` / `codex exec` / `opencode run` | each CLI invocation |
-| `AGENT_MOCK` | — | set to use the mock backend (no real CLI) |
-</details>
+> Full environment-variable reference and per-crate configuration live in the [Usage guide](docs/USAGE.md#5-configuration-environment-variables).
+
+## Get started
+
+Prefer one command? `docker compose -f deploy/docker/docker-compose.yml up --build` brings up the whole stack (server + agent-runtime + web + Postgres + Redis).
+
+For everything else — from-source run, the full environment-variable reference, the web console, fleet & executor setup, and the HTTP API — see the **[Usage guide](docs/USAGE.md)** ([中文](docs/USAGE.zh-CN.md)). Production deployment (Helm, Terraform, CI/CD, day-2 ops) is covered in the **[Deployment & ops guide](docs/DEPLOYMENT.md)** ([中文](docs/DEPLOYMENT.zh-CN.md)).
 
 ## Documentation
 
 - **[Usage guide](docs/USAGE.md)** ([中文](docs/USAGE.zh-CN.md)) — concepts, quick start, the full configuration reference, the web console, fleet & executor setup, and the HTTP API.
 - **[Deployment & ops](docs/DEPLOYMENT.md)** ([中文](docs/DEPLOYMENT.zh-CN.md)) — Docker Compose, Kubernetes via Helm (`deploy/helm/shepherd`), multi-cloud Terraform (`deploy/terraform/{aws,gcp,azure}`), and CI/CD auto-deploy.
-- **[Install agent-runtime](docs/INSTALL.md)** — Homebrew, Windows (Scoop / PowerShell), Linux binary, and registering to a server.
+- **[Install agent-runtime](docs/INSTALL.md)** ([中文](docs/INSTALL.zh-CN.md)) — Homebrew, Windows (Scoop / PowerShell), Linux binary, and registering to a server.
 - **[Running AI executors](docs/EXECUTORS.md)** ([中文](docs/EXECUTORS.zh-CN.md)) — Claude Code / Codex / OpenCode / CodeBuddy behind `agent-runtime`.
+- **[Comment conventions](docs/COMMENT_CONVENTIONS.md)** ([中文](docs/COMMENT_CONVENTIONS.zh-CN.md)) — rules for code comments across the workspace.
 
 ## How it compares
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -8,7 +8,7 @@ AI ROI、人效分析、软件工程建模、Task Graph。
 [![Rust](https://img.shields.io/badge/Rust-2021-orange.svg)](https://www.rust-lang.org/)
 [![License](https://img.shields.io/badge/License-GPL--2.0-blue.svg)](LICENSE)
 [![status](https://img.shields.io/badge/status-experimental-yellow.svg)](#状态)
-&nbsp; · &nbsp; 简体中文 | [English](README.md)
+&nbsp; · &nbsp; 简体中文 · [English](README.md)
 
 Shepherd 是一个还在早期阶段的研发监督平台。AI 现在能写代码了,但它不会判断自己有没有真正做完需求,也不会替结果负责。与其再造一个"更聪明的 agent",Shepherd 做的是 agent 外面那一层——把需求拆给 AI 执行机去干,然后在设计和验证两个环节卡上人工审批,过程留痕。
 
@@ -81,39 +81,6 @@ Shepherd 是一个还在早期阶段的研发监督平台。AI 现在能写代
 
 它量的是交付结果,不是敲键盘。所以这些数字会比「我们 90% 的代码是 AI 写的」那种说法难看得多,但也更实。
 
-## 跑起来
-
-```bash
-# 1) 一个 Postgres,迁移会在启动时自动施加
-docker run -d --name shep-pg \
-  -e POSTGRES_USER=msuser -e POSTGRES_PASSWORD=mspass -e POSTGRES_DB=mstest \
-  -p 55432:5432 postgres:16-alpine
-
-# 2) 起服务(根目录设了 default-members,直接 cargo run)
-DATABASE_URL=postgres://msuser:mspass@localhost:55432/mstest \
-SHEPHERD_ADMIN_PASSWORD=s3cret \
-cargo run                       # → http://localhost:8088
-```
-
-```bash
-# 登录拿令牌
-curl -s localhost:8088/auth/login -H 'content-type: application/json' \
-  -d '{"username":"admin","password":"s3cret"}'
-```
-
-前端控制台,以及在内网机上起一台执行机:
-
-```bash
-cd web && npm install && npm run dev          # Vite 控制台
-
-SHEPHERD_AGENT_FLEET=1 cargo run              # 服务端开机群模式
-SHEPHERD_BASE=http://<server>:8088 SHEPHERD_CAPS=CLAUDE_CODE cargo run -p agent-runtime
-```
-
-<!-- 控制台截图待补:见 docs/assets/。 -->
-
-想一条命令起全栈?`docker compose -f deploy/docker/docker-compose.yml up --build` 会拉起整套服务(server + agent-runtime + web + Postgres + Redis)——详见[使用指南](docs/USAGE.zh-CN.md)与[部署指南](docs/DEPLOYMENT.zh-CN.md)。
-
 ## 里面有什么
 
 每个业务模块是一个独立 crate,按六边形分层:`domain` / `ports` / `application` 是纯逻辑、默认不碰 IO,数据库和 HTTP 都在 `adapters` 里用 feature 开关。`tests/architecture.rs` 会扫源码,纯层一旦引了 sqlx / axum 这类 IO crate 就让构建挂掉——免得分层写着写着被写穿。
@@ -145,37 +112,21 @@ web/               React + antd 前端
 ```
 </details>
 
-<details>
-<summary>主要环境变量</summary>
-
-服务端(收拢在 typed `ServerConfig`):
-
-| 变量 | 默认 | 含义 |
-|---|---|---|
-| `DATABASE_URL` | 本地 mstest | PG 连接串 |
-| `SHEPHERD_BIND` | `0.0.0.0:8088` | 主 API 监听 |
-| `SHEPHERD_ADMIN_PASSWORD` | `admin` | 启动时幂等 upsert 的 admin 密码 |
-| `SHEPHERD_AGENT_FLEET` | — | 设置即开机群模式 |
-| `SHEPHERD_FLEET_REDIS` | — | 设置即用 Redis 分布式队列 / 注册表 |
-| `SHEPHERD_FEISHU_*` / `SHEPHERD_WECOM_*` | — | OIDC 第三方登录 |
-
-执行机 `agent-runtime`:
-
-| 变量 | 默认 | 含义 |
-|---|---|---|
-| `SHEPHERD_BASE` | `http://127.0.0.1:9180` | 服务端地址 |
-| `SHEPHERD_CAPS` | `CLAUDE_CODE` | 逗号分隔的能力(认领哪类任务) |
-| `AGENT_CONCURRENCY` | `1` | 并发任务上限 |
-| `CLAUDE_BIN` / `CODEX_CMD` / `OPENCODE_CMD` | `claude` / `codex exec` / `opencode run` | 各 CLI 调用 |
-| `AGENT_MOCK` | — | 设置即用 mock 后端(免真实 CLI) |
-</details>
+> 完整环境变量与逐 crate 配置见[使用指南](docs/USAGE.zh-CN.md#5-配置环境变量)。
+
+## 快速开始
+
+想一条命令起全栈?`docker compose -f deploy/docker/docker-compose.yml up --build` 会拉起整套服务(server + agent-runtime + web + Postgres + Redis)。
+
+其余内容——源码方式运行、完整环境变量参考、Web 控制台、机群与执行机配置、HTTP API——见**[使用指南](docs/USAGE.zh-CN.md)**([English](docs/USAGE.md))。生产部署(Helm、Terraform、CI/CD、Day-2 运维)见**[部署与运维指南](docs/DEPLOYMENT.zh-CN.md)**([English](docs/DEPLOYMENT.md))。
 
 ## 文档
 
 - **[使用指南](docs/USAGE.zh-CN.md)**([English](docs/USAGE.md))—— 概念、快速上手、完整配置参考、Web 控制台、机群与执行机配置、HTTP API。
 - **[部署与运维](docs/DEPLOYMENT.zh-CN.md)**([English](docs/DEPLOYMENT.md))—— Docker Compose、Kubernetes(Helm,`deploy/helm/shepherd`)、多云 Terraform(`deploy/terraform/{aws,gcp,azure}`)、CI/CD 自动部署。
+- **[安装 agent-runtime](docs/INSTALL.zh-CN.md)**([English](docs/INSTALL.md))—— Homebrew、Windows(Scoop / PowerShell)、Linux 二进制,以及接入服务端。
 - **[AI 执行者运行指南](docs/EXECUTORS.zh-CN.md)**([English](docs/EXECUTORS.md))—— 在 `agent-runtime` 下运行 Claude Code / Codex / OpenCode / CodeBuddy。
-- **[安装 agent-runtime](docs/INSTALL.md)** —— Homebrew、Windows(Scoop / PowerShell)、Linux 二进制,以及接入服务端(目前为英文)。
+- **[注释规范](docs/COMMENT_CONVENTIONS.zh-CN.md)**([English](docs/COMMENT_CONVENTIONS.md))—— 全仓库代码注释的统一约定。
 
 ## 和别的方案比
 

diff --git a/crates/server/src/scenario_run.rs b/crates/server/src/scenario_run.rs
@@ -212,7 +212,14 @@ impl ScenarioRunner {
         pool_id: Option<&str>,
     ) -> Result<StartedRun, RunError> {
         let (nodes, count) = self.prepare(scenario_id).await?;
-        let env = self.resolve_env(environment_id).await?;
+        // Env fallback: when the caller does not pin an environment, use the
+        // scenario's own configured environment (meta.envId) so scenarios that
+        // declare a default base URL still resolve relative paths correctly.
+        let effective_env = match environment_id.filter(|s| !s.trim().is_empty()) {
+            Some(eid) => Some(eid.to_string()),
+            None => self.default_env_of(scenario_id).await,
+        };
+        let env = self.resolve_env(effective_env.as_deref()).await?;
         let report_id = self
             .reports
             .create("SERIAL", count as i32)

diff --git a/docs/COMMENT_CONVENTIONS.md b/docs/COMMENT_CONVENTIONS.md
@@ -1,5 +1,7 @@
 # Comment Conventions
 
+[简体中文](COMMENT_CONVENTIONS.zh-CN.md) · English
+
 Unified rules for comments in this workspace. The goal is consistent, English,
 rustdoc-friendly comments across every crate.
 

diff --git a/docs/COMMENT_CONVENTIONS.zh-CN.md b/docs/COMMENT_CONVENTIONS.zh-CN.md
@@ -0,0 +1,87 @@
+# 注释规范
+
+简体中文 · [English](COMMENT_CONVENTIONS.md)
+
+本仓库注释的统一规则。目标是让每个 crate 的注释都保持一致、用英文、对 rustdoc 友好。
+
+## 1. 注释形式
+
+| 语法 | 用途 |
+| ----------- | --------------------------------------------------- |
+| `//!` | 模块级或 crate 级文档(放在文件顶部)。 |
+| `///` | 紧跟其后的条目的文档。 |
+| `//` | 行内说明、`TODO`、理由——非公开 API。 |
+| `// TODO:` | 待办工作(英文)。优先附上 issue 链接。 |
+
+- 凡是公开面的一部分(导出的类型、函数、方法、模块),用 `///` / `//!`;内部推理用 `//`。
+- 文档文本不要用 `/* ... */` 块注释;正文用行注释,这样 `cargo doc` 才能收录。行内 `/* */` 用于临时注释代码没问题。
+
+## 2. 语言
+
+- 所有**文档文本**都用**英文**:`//`、`///`、`//!` 注释行,`utoipa` 的 `description = "..."` 属性,以及 `#[error(...)]` / `#[ignore = "..."]` / `#[schema(...)]` 里的消息。
+- 不要用中文、拼音或中英混杂写文档。
+- **例外:** 作为测试夹具或 mock 数据的字符串字面量(例如 `#[test]` / `r#"..."#` 里的 `"登录"`、`"张三"`)。这些是有意用来跑 i18n 的,保持原样。
+
+## 3. 风格
+
+- **首字母大写。** 每句以句号结尾(`.`)。
+- `//`、`///`、`//!` 后**空一格**:`/// Returns the count.`
+- 用**第三人称或祈使句**作为摘要句:
+  - `/// Returns the number of active users.`
+  - `/// Parses the raw payload into a `Proposal`.`
+  - 避免 `This function returns...`;以动作开头。
+- 注释**精简**;不要复述代码一眼就看得懂的东西。解释 *为什么*、约束,以及不直观的行为。
+- 结构体 / 枚举字段,优先用以句号结尾的名词短语:`/// The user's display name.`
+
+## 4. 代码与标识符
+
+- 类型、函数、模块、路径用反引号包起来:`Vec<T>`、`parse()`、`crate::domain::Proposal`、`Result<T, Error>`。
+- 超过一行的行内代码片段,用围栏代码块:
+
+  ```rust
+  let req = Proposal::new(..)?;
+  ```
+
+## 5. Markdown
+
+- 文档注释(`///`、`//!`)支持 Markdown:列表、链接、表格、代码围栏。
+- 列表用 `-`;仅当列表需要引导句时,在首项前空一行。
+
+## 6. 示例
+
+```rust
+//! HTTP adapters for the requirement crate.
+//! Exposes REST endpoints backed by the PostgreSQL repository.
+
+/// Creates a new requirement from the given draft.
+///
+/// Returns an error if the title is empty after trimming.
+pub fn create(draft: Draft) -> Result<Requirement> {
+    // Reject empty titles early to avoid a round-trip to the DB.
+    if draft.title.trim().is_empty() {
+        return Err(Error::EmptyTitle);
+    }
+    // ...
+}
+```
+
+## 7. 检查
+
+确认注释行里没有残留中文:
+
+```bash
+# 粗检:标出 // 行里、字符串字面量之外的中文字符
+python3 - <<'PY'
+import os, re
+def cjk(s): return any('\u4e00' <= c <= '\u9fff' for c in s)
+for root, _, fs in os.walk('crates'):
+    for f in fs:
+        if not f.endswith('.rs'):
+            continue
+        for i, line in enumerate(open(os.path.join(root, f), encoding='utf-8', errors='ignore'), 1):
+            s = re.sub(r'"[^"]*"', '""', line)
+            s = re.sub(r"'[^']*'", "''", s)
+            if cjk(s) and re.match(r'\s*//', line):
+                print(f'{os.path.join(root, f)}:{i}: {line.rstrip()}')
+PY
+```
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
@@ -1,5 +1,7 @@
 # Shepherd — Deployment & Operations
 
+[简体中文](DEPLOYMENT.zh-CN.md) · English
+
 This guide covers building images, running locally, deploying to Kubernetes via Helm,
 provisioning cloud infrastructure with Terraform, the CI/CD pipeline, and Day-2
 operations. For end-user and API usage see [USAGE.md](./USAGE.md).

diff --git a/docs/DEPLOYMENT.zh-CN.md b/docs/DEPLOYMENT.zh-CN.md
@@ -1,5 +1,7 @@
 # Shepherd — 部署与运维
 
+简体中文 · [English](DEPLOYMENT.md)
+
 本指南涵盖镜像构建、本地运行、通过 Helm 部署到 Kubernetes、使用 Terraform 预置云基础设施、
 CI/CD 流水线以及 Day-2 运维。终端用户与 API 使用方式见 [USAGE.zh-CN.md](./USAGE.zh-CN.md)。
 

diff --git a/docs/EXECUTORS.md b/docs/EXECUTORS.md
@@ -1,5 +1,7 @@
 # Shepherd — Running AI Executors
 
+[简体中文](EXECUTORS.zh-CN.md) · English
+
 How to run each supported AI executor (Claude Code / Codex / OpenCode / CodeBuddy / DeepCode)
 behind `agent-runtime`. For fleet architecture and server-side setup see
 [USAGE.md §7](./USAGE.md); for image builds and deployment see [DEPLOYMENT.md](./DEPLOYMENT.md).

diff --git a/docs/EXECUTORS.zh-CN.md b/docs/EXECUTORS.zh-CN.md
@@ -1,5 +1,7 @@
 # Shepherd — AI 执行者运行指南
 
+简体中文 · [English](EXECUTORS.md)
+
 介绍如何在 `agent-runtime` 下运行各家 AI 执行者(Claude Code / Codex / OpenCode /
 CodeBuddy / DeepCode)。机群架构与服务端配置见 [USAGE.zh-CN.md §7](./USAGE.zh-CN.md),
 镜像构建与部署见 [DEPLOYMENT.zh-CN.md](./DEPLOYMENT.zh-CN.md)。

diff --git a/docs/INSTALL.md b/docs/INSTALL.md
@@ -1,5 +1,7 @@
 # Install
 
+[简体中文](INSTALL.zh-CN.md) · English
+
 How to get `agent-runtime` running on your machine. `agent-runtime` is the executor that registers to a Shepherd server, long-polls for work, and shells out to your AI CLI (Claude Code / Codex / OpenCode / CodeBuddy). The server and web console are deployed separately — see [Deployment & ops](DEPLOYMENT.md) and the [GHCR docker-compose](../deploy/docker/docker-compose.ghcr.yml) for a single-host Linux deploy.
 
 Pick the install method for your OS: